/ 
Linux-Event-0.117
/ Linux::Event::Kernel

NAME

Linux::Event::Kernel - Linux kernel notification and lifecycle resources

SYNOPSIS

Choose the concrete kernel resource that matches the event you need:

use Linux::Event::Kernel::Timer;
use Linux::Event::Kernel::Signal;
use Linux::Event::Kernel::Event;
use Linux::Event::Kernel::Inotify;
use Linux::Event::Kernel::Process;

DESCRIPTION

Linux::Event::Kernel is the namespace for Linux::Event resources built around Linux kernel notification, timing, filesystem, process, and synchronization facilities.

It is a category, not a generic kernel-event object.

Applications normally use one of the concrete classes beneath it.

TIMER

Linux::Event::Kernel::Timer schedules callbacks using Linux::Event's shared native timer scheduler.

For example:

my $timer = Linux::Event::Kernel::Timer->new(
    loop  => $loop,
    after => 2,

    on_timer => sub ($self) {
        say "two seconds passed";
    },
);

Timers support:

one-shot delays
absolute monotonic deadlines
recurring intervals

A Loop does not create one timerfd for every Timer object.

Linux::Event uses one scheduler timerfd and a native timer heap for the Loop.

SIGNAL

Linux::Event::Kernel::Signal subscribes to Unix signals through Linux signalfd.

For example:

my $signal = Linux::Event::Kernel::Signal->new(
    loop    => $loop,
    signals => ['INT', 'TERM'],

    on_signal => sub ($self, $number, $count) {
        ...
    },
);

Linux::Event delivers signal notifications through the event loop rather than ordinary asynchronous Perl signal handlers.

The Signal resource also preserves process signal-mask ownership so it does not blindly undo masking that belonged to application code before the subscription was created.

EVENT

Linux::Event::Kernel::Event provides an explicit event-loop notification mechanism backed by Linux eventfd.

For example:

my $event = Linux::Event::Kernel::Event->new(
    loop => $loop,

    on_event => sub ($self, $count) {
        say "notification count: $count";
    },
);

Another execution context can signal it with:

$event->signal;

or add several notification units at once:

$event->signal(5);

The eventfd counter allows several notifications to accumulate without reducing them to one boolean wakeup.

Event is a notification mechanism, not a payload queue.

A common design is:

shared queue or other state
    +
Event notification

The producer publishes the payload first, then signals the Event.

INOTIFY

Linux::Event::Kernel::Inotify monitors filesystem changes using Linux inotify.

For example:

my $inotify = Linux::Event::Kernel::Inotify->new(
    loop => $loop,
);

my $watch = $inotify->watch(
    'log.txt',

    on_modify => sub ($event) {
        say $event->path . " changed";
    },
);

The parent Inotify object owns the kernel inotify source.

Each call to watch returns a logical Linux::Event::Kernel::Inotify::Watch subscription.

Filesystem records are represented by Linux::Event::Kernel::Inotify::Event values.

Several logical subscriptions can safely share one underlying kernel watch when appropriate.

PROCESS

Linux::Event::Kernel::Process manages process lifecycle and asynchronous subprocess I/O.

For example:

my $process = Linux::Event::Kernel::Process->new(
    loop    => $loop,
    command => ['/usr/bin/sort'],
    stdin   => 'pipe',
    stdout  => 'pipe',

    on_stdout => sub ($self, $bytes) {
        print $bytes;
    },

    on_exit => sub ($self, $status) {
        ...
    },
);

Process uses Linux process facilities such as pidfd for identity and lifecycle observation.

When pipes are requested, Linux::Event also manages the subprocess's standard I/O asynchronously.

A Process can either spawn a child or observe an existing PID, depending on how it is constructed.

IO AND KERNEL ARE DIFFERENT CATEGORIES

Linux::Event::Kernel contains resources whose primary purpose is kernel notification, timing, synchronization, filesystem observation, or process lifecycle.

Application data I/O resources instead live below Linux::Event::IO.

For example:

Linux::Event::IO::Pipe
Linux::Event::IO::TTY
Linux::Event::IO::Sock::Stream
Linux::Event::IO::Sock::Listener
Linux::Event::IO::Sock::Dgram

The distinction is organizational.

Both categories attach to the same Linux::Event::Loop and participate in the same epoll-driven event system.

CALLBACKS AND SUBCLASSES

Kernel resources use constructor callbacks where appropriate.

For example:

my $timer = Linux::Event::Kernel::Timer->new(
    after => 1,

    on_timer => sub ($self) {
        ...
    },
);

Reusable behavior can instead be placed in subclasses:

package Heartbeat;

use parent 'Linux::Event::Kernel::Timer';

sub on_timer ($self) {
    ...
}

When both forms are supported, a constructor callback overrides the corresponding subclass callback for that object.

Inotify is slightly different because filesystem event callbacks belong to each logical Watch rather than to a subclass of the parent source.

LOOP ATTACHMENT

Kernel resources generally follow the normal Linux::Event attachment model.

They may be constructed already attached:

loop => $loop

or constructed detached and added later:

my $timer = Linux::Event::Kernel::Timer->new(
    after => 1,
    on_timer => sub ($self) {
        ...
    },
);

$loop->add($timer);

The concrete resource documentation describes any special activation or lifecycle rules.

For example, an Inotify parent does not create its kernel inotify descriptor until it is attached to a Loop.

CANCELLATION AND TERMINAL STATE

Many kernel resources provide explicit cancellation or closing operations.

For example:

$timer->cancel;
$signal->cancel;
$event->cancel;
$watch->cancel;
$inotify->close;

The exact terminal states differ by resource.

Applications should use the concrete resource's documented lifecycle rather than assuming every kernel object has the same close or cancel method.

FORK BEHAVIOR IS RESOURCE-SPECIFIC

Linux::Event's managed fork support does not treat every kernel resource the same way.

The correct disposition depends on the underlying Linux facility.

For example:

  • Timer supports clone and move.

  • Inotify supports clone and move.

  • Signal, Event, and Process are currently child-drop resources in managed fork.

The Loop itself is always recreated independently in the child.

No parent and child Linux::Event::Loop objects share one epoll instance.

See Linux::Event::Loop and each concrete resource for the full managed-fork contract.

THERE IS NO GENERIC KERNEL OBJECT

This is not a public construction API:

Linux::Event::Kernel->new(...);

Choose the resource that corresponds to the kernel facility or lifecycle you need.

Use:

Linux::Event::Kernel::Timer

for scheduled time.

Use:

Linux::Event::Kernel::Signal

for Unix signal delivery.

Use:

Linux::Event::Kernel::Event

for explicit eventfd-backed notification.

Use:

Linux::Event::Kernel::Inotify

for filesystem observation.

Use:

Linux::Event::Kernel::Process

for subprocess or PID lifecycle management.

SEE ALSO

Linux::Event, Linux::Event::Loop, Linux::Event::IO, Linux::Event::Kernel::Timer, Linux::Event::Kernel::Signal, Linux::Event::Kernel::Event, Linux::Event::Kernel::Inotify, Linux::Event::Kernel::Inotify::Watch, Linux::Event::Kernel::Inotify::Event, Linux::Event::Kernel::Process.