NAME

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

SYNOPSIS

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

sub on_timer ($timer) {
    $timer->data->send('ping');
}

package main;
my $timer = $loop->add(Heartbeat->new(
    every => 15,
    data  => $connection,
));

DESCRIPTION

Linux::Event::Kernel::Timer is the public timer leaf. Applications create a subclass with one named on_timer callback. 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.

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) { ... }

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.

The callback is cached per subclass. 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.