Download the PHP package php-io-extensions/kqueue without Composer

php-io-extensions/kqueue

1:1 PHP bindings of macOS <sys/event.h>, in plain C. Global functions, same names, same argument order as C. No wrapper package, no policy.

Platform: macOS (Darwin). Binds kevent64(), which only macOS has. PHP ≥ 8.4, 64-bit, NTS + ZTS.

Install

PIE:

Source checkout, Homebrew [email protected] + [email protected] (or pass PHP binaries as args):

Script builds in temp copy, installs kqueue.so into each PHP's extension_dir, ad-hoc signs it, writes 30-kqueue.ini into its conf.d.

Manual:

API

Constants: all 87 EVFILT_*, EV_*, NOTE_*, KEVENT_FLAG_* from the SDK header, values taken at compile time, plus errno values kqueue(2) documents: EACCES EBADF EFAULT EINTR EINVAL EMFILE ENFILE ENOENT ENOMEM ESRCH.

Mapping to C

• Structs. struct kevent, struct kevent64_s, struct timespec → final classes, typed public props named as C fields, zero-initialised, no dynamic props. Class and function share name kevent as in C; PHP keeps them in separate symbol tables.
• Arrays in, arrays out. changelist = PHP array of kevent (kevent64_s for kevent64); first $nchanges entries in iteration order are sent. $eventlist receives list of new kevent/kevent64_s, length = return value. On -1, $eventlist untouched, as C leaves its buffer.
• timeout. null = C NULL = block. new timespec() = poll.
• Widths. filter (int16_t), flags (uint16_t), fflags and kevent64 flags (uint32_t) accept either signed or unsigned reading of their width, as C's implicit conversion does. Wider values throw ValueError. EV_SET/EV_SET64 store the value as the C field holds it: EV_SET($k, 0, 0xffff, -1, NOTE_PCTRLMASK, 0, 0) → filter -1, flags 65535, fflags 0xfff00000. Constants carry C expression values: NOTE_PCTRLMASK = ~0x000fffff = -1048576.
• ident. EV_SET/EV_SET64 take int, a stream resource, or a Socket (when ext-sockets is loaded). Stream and Socket resolve to their fd, same as epoll_ctl's $fd; the struct stores the int. Non-fd filters (EVFILT_SIGNAL, EVFILT_PROC, EVFILT_TIMER, EVFILT_USER) pass their int ident as before. Other types throw TypeError; a closed stream throws TypeError, a stream with no fd ValueError.
• 64-bit fields. ident, data, udata, ext[] pass through as bit patterns. udata is pointer-sized int: kernel returns exactly what you set, nothing more. Unsigned 64-bit values ≥ 2^63 read back negative.
• errno. PHP runtime can overwrite errno before PHP code runs, so each binding saves it right after the syscall on -1. kqueue_errno() reads it. Reset per request.
• Descriptor lifetime. close(2) is POSIX, not kqueue: use Posi\System::close() from php-io-extensions/posi.
• Invalid arguments (nchanges outside changelist, negative nevents, wrong element class, unset prop, malformed ext) throw ValueError/TypeError/Error before any syscall.

Kernel behaviour passes through unchanged:

• A change that fails while $nevents > 0 comes back as an event with EV_ERROR in flags and errno in data; with $nevents = 0 the call returns -1 and kqueue_errno() holds errno. EV_RECEIPT forces the event form.
• XNU binds a kqueue to the first ABI it is used with. kevent64() on a kqueue already used with kevent() (or reverse) returns -1, EINVAL.
• Signals interrupt a blocking kevent(): -1, EINTR.

Tests

Pest v4. Needs extension loaded:

Regenerating arginfo

kqueue_arginfo.h is generated from kqueue.stub.php; edit stub, then:

License

MIT