/ 
Linux-Event-Clock-0.011
/ Linux::Event::Clock

NAME

Linux::Event::Clock - Cached monotonic time and deadline math for Linux::Event schedulers

SYNOPSIS

use Linux::Event::Clock;

my $clock = Linux::Event::Clock->new;

while (1) {
    $clock->tick;              # one syscall per loop iteration/batch
    my $now = $clock->now_ns;  # cached, no syscall

    if ($deadline_ns <= $now) {
        # due
    }

    my $deadline2 = $clock->deadline_after_ms(50); # absolute ns, 50ms from cached now
}

DESCRIPTION

Linux::Event::Clock provides a monotonic clock with an explicit cache refresh via tick. A scheduler can refresh the cache once per loop iteration (or once per batch) and then perform thousands of deadline comparisons using cached nanosecond integers without additional syscalls.

This module is intended to be the time/deadline math companion to a Linux-only event framework that uses primitives like timerfd and epoll.

CONSTRUCTOR

new

my $clock = Linux::Event::Clock->new(%opt);

Creates a new clock and primes the cached time by calling tick once.

Options:

  • clock => monotonic (default)

    Only monotonic is supported in v0.1.

METHODS

tick

my $now_ns = $clock->tick;

Refreshes the cached monotonic time (one syscall) and increments generation. Returns the cached time in nanoseconds.

generation

my $gen = $clock->generation;

Returns a monotonically increasing counter incremented by each tick. Useful for schedulers that cache derived state per tick.

now_ns

my $now_ns = $clock->now_ns;

Returns the cached monotonic time in nanoseconds. No syscall.

now_s

my $now_s = $clock->now_s;

Returns the cached monotonic time in seconds (floating point). Intended for logging/UI rather than tight scheduling comparisons.

monotonic_ns

my $ns = $clock->monotonic_ns;

Returns the current monotonic time in nanoseconds without using the cache (one syscall). Intended for debugging/profiling rather than the scheduler hot path.

deadline_after

my $deadline_ns = $clock->deadline_after($seconds);

Returns an absolute deadline in nanoseconds, computed from the cached time and a relative duration in seconds. Conversion happens once per call.

deadline_after_ms

my $deadline_ns = $clock->deadline_after_ms($ms);

Returns an absolute deadline in nanoseconds computed from cached now plus $ms milliseconds.

deadline_after_us

my $deadline_ns = $clock->deadline_after_us($us);

Returns an absolute deadline in nanoseconds computed from cached now plus $us microseconds.

deadline_in_ns

my $deadline_ns = $clock->deadline_in_ns($delta_ns);

Returns an absolute deadline in nanoseconds computed from cached now plus a nanosecond delta.

expired_ns

if ($clock->expired_ns($deadline_ns)) { ... }

Returns true if $deadline_ns is less than or equal to cached now_ns.

remaining_ns

my $rem_ns = $clock->remaining_ns($deadline_ns);

Returns remaining nanoseconds until the deadline, clamped at 0.

PERFORMANCE NOTES

For tight loops, refresh once and compare integers:

$clock->tick;
my $now = $clock->now_ns;
while ($next_deadline_ns <= $now) { ... }

deadline_after* helpers are intended for timer setup, not the hot compare loop.

SEE ALSO

Linux::Event::Timer, Time::HiRes

AUTHOR

Joshua Day

LICENSE

Same terms as Perl itself.