macOS declarations for kqueue event registration, one-shot readiness and timer filters, and the kevent wait operation.

Functions that report failure with -1 set errno.

Constants

Event filters

NameValueMeaning
EVFILT_READ-1i16Read-event filter.
EVFILT_TIMER-7i16Timer-event filter.
EVFILT_WRITE-2i16Write-event filter.

Change-list actions

NameValueMeaning
EV_ADD0x0001n16Adds an event registration.
EV_DELETE0x0002n16Deletes an event registration.

Event flags

NameValueMeaning
EV_ONESHOT0x0010n16Removes an event after one delivery.

Timer units

NameValueMeaning
NOTE_NSECONDS0x00000004n32Uses nanoseconds for a timer interval.
NOTE_USECONDS0x00000002n32Uses microseconds for a timer interval.

Schemas

struct_kevent

(-- struct_kevent) Defines one kernel event record.

Dict schema

FieldSchemaRole
identNatxevent identifier
filterInt16filter selector
flagsNat16event flags
fflagsNat32filter-specific flags
dataIntxfilter-specific data
udataNatxcaller-selected user data
  • For relative EVFILT_TIMER changes, data is the timer interval in milliseconds by default; NOTE_NSECONDS or NOTE_USECONDS in fflags selects nanoseconds or microseconds.
  • Returned timer events report the number of expirations since the last arming or delivery in data.

Helpers

EV_SET

(kev ident filter flags fflags data udata --) Fills one event record from its identifier, filter, flags, filter flags, data, and user data.

Inputs

  • kev: struct_kevent Ref writable record that the call fills.
  • ident: event identifier; the call casts it to Natx.
  • filter: Int16 filter, such as EVFILT_READ.
  • flags: Nat16 action and flag values, such as EV_ADD EV_ONESHOT or.
  • fflags: Nat32 filter-specific flags; 0n32 for none.
  • data: filter-specific data; the call casts it to Intx.
  • udata: caller-selected user data; the call casts it to Natx.

Outputs

  • None.

Imported functions

Stack effects list a C function's parameters with the first parameter on top; see importFunction.

kevent

(timeout nevents eventlist nchanges changelist kq -- result) Applies event changes and waits for ready events.

Inputs

  • timeout: timespec Cref borrowed wait timeout in seconds and nanoseconds, or a typed NIL timespec Cref to wait until an event arrives; a zero timespec returns immediately.
  • nevents: Int32 event-list capacity; with 0, the call applies the changes and returns without waiting.
  • eventlist: struct_kevent Ref caller-owned writable event storage, or a typed NIL struct_kevent Ref when nevents is 0; the call writes ready events or per-change error records; an error record has EV_ERROR (0x4000n16) set in flags and its error number in data.
  • nchanges: Int32 number of changes in changelist.
  • changelist: struct_kevent Cref borrowed event changes to apply, or a typed NIL struct_kevent Cref when nchanges is 0.
  • kq: Int32 kqueue descriptor.

Outputs

  • result: Int32 number of records returned, including per-change errors, 0 on timeout, or -1 on failure, including a failed change that finds no room for its error record in eventlist.

kqueue

(-- result) Creates a kernel event queue.

Inputs

  • None.

Outputs

  • result: Int32 new descriptor, or -1 on failure.

Examples

macOS declaration inspection

"control"     use
"macos/macos" use

{} Int32 {} [
  @kevent printStack _:;
  @kqueue printStack _:;
  struct_kevent fieldCount printStack _:;
  EVFILT_READ printStack _:;
  0
] "main" exportFunction

Expected Output During Compilation

{kq: Int32; changelist: {ident: Natx; filter: Int16; flags: Nat16; fflags: Nat32; data: Intx; udata: Natx;} Cref; nchanges: Int32; eventlist: {ident: Natx; filter: Int16; flags: Nat16; fflags: Nat32; data: Intx; udata: Natx;} Ref; nevents: Int32; timeout: {tv_sec: Intx; tv_nsec: Intx;} Cref;} Int32 {convention: "";} codeRef
{} Int32 {convention: "";} codeRef
6
-1i16

macOS kqueue example

"String"      use
"control"     use
"macos/macos" use
"macos/posix" use

{} Int32 {} [
  kq: kqueue;
  ("created=" kq 0 < ~ LF
    "close=" kq close 0 = LF) printList
  0
] "main" exportFunction

Expected Output

created=TRUE
close=TRUE

See also