NAME

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

SYNOPSIS

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

sub on_event ($event, $count) {
    my $queue = $event->data;
    process($queue->dequeue_nb) while $queue->pending;
}

package main;
my $event = $loop->add(ResultsReady->new(data => $queue));

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

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.

CONSTRUCTION AND CALLBACK

A subclass must define:

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.