/ 
Timer-Wheel-0.01
/ Timer::Wheel

NAME

Timer::Wheel - Lightweight timer/event scheduler

VERSION

Version 0.01

SYNOPSIS

use Timer::Wheel;

my $tw = new Timer::Wheel;

# Fire in 5 seconds from now
my $id = $tw->in(5, sub { say "5 seconds elapsed" });

# Fire at an absolute epoch time
$tw->at(time() + 10, sub { say "fires at epoch" });

# Recurring timer
$tw->every(1.0, sub { say "every second" });

# Cancel a timer
$tw->cancel($id);

# Run loop
while ($tw->pending) {
    if (defined(my $d = $tw->sleep_time)) {
        select(undef, undef, undef, $d) if $d > 0;
    }
    $tw->tick;
}

# IO::Async integration
use IO::Async::Loop;
use IO::Async::Timer::Periodic;

my $loop = IO::Async::Loop->new;
my $tw   = new Timer::Wheel;

$tw->every(5, sub { say "heartbeat" });
$tw->in(30, sub { say "timeout"; $tw->cancel_all; $loop->stop });

my $tick = IO::Async::Timer::Periodic->new(
    interval => 0.1,
    on_tick  => sub { $tw->tick },
);
$tick->start;
$loop->add($tick);
$loop->run;

DESCRIPTION

Timer::Wheel is a lightweight timer scheduler that uses Heap::PQ with key-path comparison for O(log n) insert and O(1) peek, and Object::Proto for fast object construction. Timers can be one-shot or recurring, grouped for bulk cancellation, and paused/resumed individually or globally.

METHODS

new

my $tw = new Timer::Wheel;

Create a new timer wheel.

at($epoch, \&callback, %opts)

my $id = $tw->at(time() + 5, sub { ... });
my $id = $tw->at($epoch, \&cb, group => 'network');

Schedule a callback to fire at an absolute epoch time. Returns a timer ID.

in($seconds, \&callback, %opts)

my $id = $tw->in(2.5, sub { ... });

Schedule a callback to fire in $seconds from now.

every($seconds, \&callback, %opts)

my $id = $tw->every(1.0, sub { ... });
my $id = $tw->every(1.0, \&cb, start => $epoch);

Schedule a recurring callback. First fire is after $seconds unless start is given.

tick([$now])

my $fired = $tw->tick;
my $fired = $tw->tick($epoch);

Fire all callbacks due at or before $now (defaults to time()). Returns the number of callbacks fired. Recurring timers are re-inserted.

drain

my $fired = $tw->drain;

Fire all pending callbacks regardless of time. Recurring timers fire once.

next

my $epoch = $tw->next;

Returns the epoch of the earliest pending timer, or undef.

sleep_time

my $delay = $tw->sleep_time;

Seconds until the next timer fires (from time()), or undef.

pending

my $n = $tw->pending;

Number of active timers.

is_empty

my $bool = $tw->is_empty;

True if no active timers remain.

cancel($id)

$tw->cancel($id);

Cancel a timer by ID. Returns 1 if found, 0 otherwise.

cancel_group($group)

$tw->cancel_group('network');

Cancel all active timers with the given group tag.

cancel_all

$tw->cancel_all;

Cancel all timers and clear the heap.

pause($id) / resume($id)

$tw->pause($id);
$tw->resume($id);

Pause or resume an individual timer.

pause_all / resume_all

$tw->pause_all;
$tw->resume_all;

Pause or resume the entire wheel.

AUTHOR

LNATION <email@lnation.org>

LICENSE AND COPYRIGHT

This software is Copyright (c) 2026 by LNATION <email@lnation.org>.

This is free software, licensed under:

The Artistic License 2.0 (GPL Compatible)