NAME

Linux::Event::Kernel::Timer - monotonic one-shot and recurring Loop timers

SYNOPSIS

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

my $loop = Linux::Event::Loop->new;
my $timer = Linux::Event::Kernel::Timer->new(
    loop     => $loop,
    after    => 1,
    on_timer => sub ($timer) {
        say 'timer fired';
        $timer->loop->stop;
    },
);
$loop->run;

DESCRIPTION

Linux::Event::Kernel::Timer is the public timer leaf. All active timers on a Loop share the Loop's timerfd-backed native scheduler and indexed minimum heap; one Timer object does not mean one kernel timer descriptor.

CALLBACKS AND SUBCLASS POLICY

Pass on_timer => sub ($timer) { ... } to new when a timer should capture lexical application state. Subclassing remains useful for a reusable timer type with named, testable behavior:

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

sub on_timer ($timer) {
    $timer->data->write("ping\n");
}

A constructor callback overrides the subclass method for that object. The effective CV is resolved once at construction; recurring delivery does not repeat method lookup or branch between callback styles.

SCHEDULES

Construction accepts one schedule:

after => $seconds

Relative one-shot deadline.

at => $monotonic_seconds

Absolute one-shot deadline using the same monotonic clock returned by Linux::Event::Kernel::Timer->now.

every => $seconds

Fixed-rate recurrence. after or at may be combined with every to set a different first deadline.

after and at are mutually exclusive. Public durations are seconds and may be fractional. Zero-delay work is delivered on a later Loop turn rather than reentrantly from construction.

CALLBACK AND RECURRENCE

sub on_timer ($timer) { ... } # subclass form

or:

on_timer => sub ($timer) { ... } # constructor form

Recurring timers advance from the previous scheduled deadline rather than from callback completion. If the Loop is late, missed intervals are coalesced into one callback; expirations reports how many ticks that callback represents.

Method callbacks are cached per subclass and constructor callbacks per object. data holds arbitrary application state and loop returns the owning Loop while attached.

RESCHEDULING AND CANCELLATION

reschedule accepts the same schedule grammar as construction and returns the same object. It may be called while active or from on_timer.

cancel is idempotent and terminal. A completed one-shot timer is also terminal. Active timers are retained by the Loop even if the application drops its own reference; cancellation, final expiration, or Loop destruction releases that ownership safely.

ATTACHMENT

loop => $loop attaches during construction. Otherwise construct detached and use $loop->add($timer). Timer callbacks are ordinary Loop callbacks and may close I/O objects, schedule other timers, or stop the Loop.

SEE ALSO

Linux::Event::Loop, docs/TIMER-DESIGN.md, docs/ORDERED-BYTE-DEADLINES.md.