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 => $loop,
  on_alloc => sub {say "alloc!"},
  on_close => sub {say "close!"},
  on_timer => sub {say "timer!"},
);

# 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 => $loop,
    on_alloc => sub {say "alloc!"},
    on_close => sub {say "close!"},
    on_timer => sub {say "timer!"},
);

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.

repeat

my $uint64_t = $timer->repeat();
$timer = $timer->repeat(12345); # method chaining

The repeat method returns the timer's repeat value via: get_repeat or sets the timer's repeat value via set repeat.

The repeat value is set 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.

cpanm UV

perl -MCPAN -e shell
install UV