NAME

Linux::Event::Kernel::Event - eventfd-backed Loop notification

SYNOPSIS

use v5.36;
use Linux::Event::Loop;
use Linux::Event::Kernel::Event;

my $loop = Linux::Event::Loop->new;
my $notifications = 0;
my $event = Linux::Event::Kernel::Event->new(
    loop => $loop,
    on_event => sub ($event, $count) {
        $notifications += $count;
        $event->loop->stop;
    },
);

# From a worker thread, native extension, or forked child:
$event->signal;
$loop->run;

DESCRIPTION

Linux::Event::Kernel::Event is the public eventfd notification leaf. It lets another execution context make the owning Loop runnable without pretending that an eventfd transports arbitrary Perl values or callbacks.

The eventfd carries a 64-bit counter. Application payloads belong in an appropriate queue, shared native structure, pipe, socket, or other IPC channel. Publish the payload first, then call signal.

CALLBACKS AND SUBCLASS POLICY

on_event => sub ($event, $count) { ... } may be passed directly to new. This closure form is usually best for one object because it can capture lexical application state. A constructor callback overrides a same-named subclass method for that object.

A subclass method remains useful when many Event objects share named, testable behavior:

package ResultsReady;
use parent 'Linux::Event::Kernel::Event';

sub on_event ($event, $count) {
    drain_results($event->data, $count);
}

Linux::Event resolves the method once per subclass or retains the constructor closure once per object. Delivery uses the resulting cached CV; it does not perform a method lookup or choose between the two forms for every event.

CONSTRUCTION AND CALLBACK

A subclass may define, or new may receive:

sub on_event ($event, $count) { ... }

data typically contains the application-owned queue or state associated with the notification. loop => $loop attaches immediately; otherwise add the detached object with $loop->add($event).

$count is the counter value drained from eventfd. Multiple producer writes may coalesce into one callback, so the payload channel rather than $count is the source of truth for individual work items.

SIGNALING

signal writes one to the counter. signal($increment) adds an explicit positive increment and returns the Event object. Signaling never invokes on_event inline; delivery occurs on the owning Loop thread.

The eventfd is nonblocking and close-on-exec. Counter saturation is reported as a kernel write failure rather than discarding existing readiness.

THREAD AND FORK BOUNDARY

Linux::Event does not require a threaded Perl. Event is useful for native worker threads, external libraries, and forked processes as well as Perl ithreads.

On an ithread-enabled Perl, a cloned Event handle may signal only. It cannot manage the Loop, callback, or owner data. The clone uses its own descriptor duplicate so destruction or descriptor reuse in one interpreter cannot corrupt another.

A forked child may signal the inherited eventfd until exec. Cross-process payloads still require real IPC or shared storage.

LIFECYCLE

cancel is idempotent and terminal. It removes the Loop registration and releases owner-side state. Callback exceptions propagate through ordinary Loop dispatch and do not silently cancel the Event.

The native eventfd extension dispatches on_event directly.

SEE ALSO

Linux::Event::Loop, docs/EVENT-DESIGN.md.