feat(libkernel): implement kevent EV_DISABLE, EV_DISPATCH and EV_FORCEONESHOT

[akkadbakkad89]

What

kevent no longer throws on EV_DISABLE, EV_DISPATCH, EV_FORCEONESHOT or a negative nevents, following kqueue_register/kqueue_scan in FreeBSD 11's kern_event.c:

• KernelEqueueEvent gains an enabled flag (FreeBSD's KN_DISABLED). PollEvents, TriggerExpiredTimers, TriggerEvent, WaitForDescriptors interest registration and NextTimerWaitMicros all skip disabled knotes, so a disabled knote never fires.
• EV_DISABLE on EV_ADD registers the knote disabled; on an existing knote EV_DISABLE/EV_ENABLE toggles it. EV_ENABLE | EV_DISABLE still returns EINVAL.
• EV_DISPATCH reports the event once, then disables the knote until re-enabled - both collect paths (CollectTriggered, CollectOncePerWait).
• EV_FORCEONESHOT is ignored on a new knote; on an existing knote it sets EV_ONESHOT and fires it, as kqueue_register does at l.1339-1341.
• A modify updates only udata, the filter's touch/fflags and enable/disable - no flag adoption, matching kqueue_register.
• Negative nevents returns EINVAL.

Known deviation documented in docs/dev/debt/libkernel.md: a NOTE_TRIGGER raised while a user knote is disabled is kept and reported after EV_ENABLE, where FreeBSD's knote drops it.

File-level overlap note: Kqueue.cpp/Equeue.cpp are also touched by open PRs #5749 (EVFILT_VNODE on macOS) and #5493 (vnode error naming) - different code paths, line-adjacent only.

Tested

WSL Ubuntu 24.04, gcc, host CPU only:

• guest_kqueue: all pass, including DisableAndDispatch cases - register-disabled socket knote stays silent until EV_ENABLE; EV_DISPATCH fires once, suppresses further data, re-arms on EV_ENABLE, disables again; EV_FORCEONESHOT on add stays a normal level knote (delivers twice), on modify sets oneshot and fires (EV_DELETE then ENOENT); disabled user knote keeps its NOTE_TRIGGER until re-enable; Errors gains the nevents < 0 -> EINVAL check and the old EV_DISABLE throw expectation is removed
• guest_equeue_events, guest_ult_queue_* (8 tests): pass
• Rebuilt neighbors guest_socket_pair, guest_dup, guest_fstatfs, guest_getrlimit, guest_signals: pass
• tools/check_conventions.py --base upstream/main: clean

Checklist

• Based on current main; no other open PR implements the same functions
• One topic per PR; follow-ups go in a new PR
• No comments in code except technical debt
• Unimplemented paths throw (NotImplemented_nid_no_patch); silent stubs are listed under Silent stubs in their library's technical debt file
• No notes, investigation .md files or images added to the repository (attach them to this PR)
• New third-party code is a submodule built from source
• Generic behaviour, not specific to one title
• Depends on: none
• Unblocks: none
• GPUs tested: n/a
• AI-assisted: yes

[adriadam10]

Thanks, the enabled flag and the EV_DISPATCH collect paths look right and guest_kqueue passes here. Two points differ from kern_event.c (the commit the debt entry cites):

• EV_FORCEONESHOT on a new knote: kqueue_register only clears it from kn_kevent.flags on the attach path (l.1303-1304). It sets EV_ONESHOT and activates the knote only when the knote already exists (l.1339-1341). Kqueue.cpp:252 applies it on add, and GuestKqueue.cpp:250-253 pins that. Please follow the source: no oneshot on add; on an existing knote set EV_ONESHOT and trigger it.
• ModifyKnote (Kqueue.cpp:232) ORs EV_ONESHOT | EV_CLEAR | EV_DISPATCH into an existing knote. kqueue_register does not do that for an existing knote (only udata, the filter's touch/fflags, and enable/disable). It also lets EV_CLEAR through on a socket knote, which AddDescriptorKnote throws on at add time. Drop the line (or, if you have a source for it, cite it and keep the throw for EV_CLEAR on sockets), and fix the PR body and the debt entry accordingly.

[akkadbakkad89]

Both points fixed in 637cb1ed4, thanks for the line references:

• EV_FORCEONESHOT on add now does nothing beyond KNOTE_CLEARED_FLAGS stripping it; on an existing knote ModifyKnote sets EV_ONESHOT and marks the knote triggered. The test now pins both halves: EV_ADD | EV_FORCEONESHOT delivers as a normal level knote twice, then the same change on the existing knote fires once and the knote is gone (EV_DELETE -> ENOENT).
• The EV_ONESHOT | EV_CLEAR | EV_DISPATCH OR on modify is dropped; a modify now touches only udata, enable/disable, EV_FORCEONESHOT and the filter's touch/fflags, matching kqueue_register. No EV_CLEAR can reach a socket knote through modify any more.

PR body and the libkernel.md debt entry updated to describe the new behaviour. guest_kqueue green locally (WSL).

[github-actions]

Other open pull requests touch the same code. Merging one will break the other, or both implement the same thing. If this one builds on them, list them in Depends on.

Pull request	Conflicting files (lines on main)	Same exports	Same new files
PR 5973	docs/dev/debt/libkernel.md L111-112
PR 6343	docs/dev/debt/libkernel.md L111-112
PR 6510	core/libs/prx/libkernel/Equeue/Equeue.cpp L52-53, L68-69, L84-85, L101-102, L123, L130, L155, L167-168 core/libs/prx/libkernel/Equeue/src/Kqueue.cpp L225, L244-252 core/libs/tests/GuestKqueue.cpp L59, L252, L534-535 docs/dev/debt/libkernel.md L111-112
PR 6542	docs/dev/debt/libkernel.md L110-112

Some comparisons could not be completed because a pull request conflicts with the base branch. Review these shared files manually before concluding that there is no overlap.

Pull request	Shared files not compared
PR 3891	docs/dev/debt/libkernel.md
PR 4156	docs/dev/debt/libkernel.md
PR 4396	docs/dev/debt/libkernel.md
PR 4397	docs/dev/debt/libkernel.md
PR 4422	docs/dev/debt/libkernel.md
PR 4423	docs/dev/debt/libkernel.md
PR 4424	docs/dev/debt/libkernel.md
PR 4520	docs/dev/debt/libkernel.md
PR 4521	docs/dev/debt/libkernel.md
PR 4522	docs/dev/debt/libkernel.md
PR 4523	docs/dev/debt/libkernel.md
PR 4566	docs/dev/debt/libkernel.md
PR 4599	docs/dev/debt/libkernel.md
PR 4718	docs/dev/debt/libkernel.md
PR 4740	docs/dev/debt/libkernel.md
PR 4749	docs/dev/debt/libkernel.md
PR 4760	docs/dev/debt/libkernel.md
PR 4813	docs/dev/debt/libkernel.md
PR 5021	docs/dev/debt/libkernel.md
PR 5835	docs/dev/debt/libkernel.md
PR 6044	core/libs/tests/GuestKqueue.cpp
PR 6222	docs/dev/debt/libkernel.md
PR 6447	core/libs/prx/libkernel/Equeue/Equeue.cpp

[adriadam10]

Both points are fixed: EV_FORCEONESHOT is a no-op on add and sets EV_ONESHOT and triggers on an existing knote, as in kqueue_register, and a modify no longer adopts flags. Checked the build and ctest on the PR merged onto main, guest_kqueue passes and fails without the change; merging once the full Build is green.