NAME
UV::Timer - Timers in libuv
SYNOPSIS
#!/usr/bin/env perl
use strict;
use warnings;
use UV;
# A new handle will be initialized against the default loop
my $timer = UV::Timer->new();
# Use a different loop
my $loop = UV::Loop->new(); # non-default loop
my $timer = UV::Timer->new($loop);
# setup the timer callback:
$timer->on("timer", sub {say "We're TIMING!!!"});
# start the timer
$timer->start(); # same as ->start(0, 0);
$timer->start(1, 0);
$timer->start(1, 0, sub {say "override any TIMER callback we already have"});
# stop the timer
$timer->stop();DESCRIPTION
This module provides an interface to libuv's timer. We will try to document things here as best as we can, but we also suggest you look at the libuv docs directly for more details on how things work.
EVENTS
UV::Timer inherits all events from UV::Handle and also makes the following extra events available.
timer
$timer->on("timer", sub { my $invocant = shift; say "We are timing!"});
my $count = 0;
$timer->on("timer", sub {
my $invocant = shift; # the timer instance this event fired on
if (++$count > 2) {
say "We've timed twice. stopping!";
$invocant->stop();
}
});When the event loop runs and the timer is ready, this event will be fired.
METHODS
UV::Timer inherits all methods from UV::Handle and also makes the following extra methods available.
new
my $timer = UV::Timer->new();
# Or tell it what loop to initialize against
my $timer = UV::Timer->new($loop);This constructor method creates a new UV::Timer object and initializes the timer with the given UV::Loop. If no UV::Loop is provided, then the "default_loop" in UV::Loop is assumed.
again
my $int = $timer->again();The again method stops the timer, and if it is repeating, restarts it using the repeat value as the timeout. If the timer has never been started, it returns UV::UV_EINVAL.
get_repeat
my $uint64_t = $timer->get_repeat();The get_repeat method returns the timer's repeat value.
set_repeat
$timer->set_repeat(12345);The set repeat method sets the repeat interval in milliseconds. The timer will be scheduled to run on the given interval, regardless of the callback execution duration, and will follow normal timer semantics in the case of a time-slice overrun.
For example, if a 50ms repeating timer first runs for 17ms, it will be scheduled to run again 33ms later. If other tasks consume more than the 33ms following the first timer callback, then the callback will run as soon as possible.
* Note: If the repeat value is set from a timer callback it does not immediately take effect. If the timer was non-repeating before, it will have been stopped. If it was repeating, then the old repeat value will have been used to schedule the next timeout.
start
# assume no timeout or repeat values
$timer->start();
# explicitly state timeout and repeat values
my $timeout = 0;
my $repeat = 0;
$timer->start($timeout, $repeat);
# pass a callback for the "timer" event
$timer->start(0, 0, sub {say "yay"});
# providing the callback above completely overrides any callback previously
# set in the ->on() method. It's equivalent to:
$timer->on(timer => sub {say "yay"});
$timer->start(0, 0);The start method starts the timer. The timeout and repeat values are in milliseconds.
If timeout is zero, the callback fires on the next event loop iteration. If repeat is non-zero, the callback fires first after timeout milliseconds and then repeatedly after repeat milliseconds.
* Note: Does not update the event loop's concept of "now" in UV::Loop. See "update_time" in UV::Loop for more information.
stop
$timer->stop();The stop method stops the timer, and if it is repeating, restarts it using the repeat value as the timeout. If the timer has never been started before it returns UV_EINVAL.
AUTHOR
Chase Whitener <capoeirab@cpan.org>
AUTHOR EMERITUS
Daisuke Murase <typester@cpan.org>
COPYRIGHT AND LICENSE
Copyright 2012, Daisuke Murase.
This library is free software; you can redistribute it and/or modify it under the same terms as Perl itself.