++ed by:
2 non-PAUSE users
Author image Paul Evans


UV::Timer - Timers in libuv


  #!/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_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


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.


UV::Timer inherits all events from UV::Handle and also makes the following extra events available.


    $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!";

When the event loop runs and the timer is ready, this event will be fired.


UV::Timer inherits all methods from UV::Handle and also makes the following extra methods available.


    my $timer = UV::Timer->new();
    # Or tell it what loop to initialize against
    my $timer = UV::Timer->new(
        loop => $loop,
        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.


    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.


    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.


    # assume no timeout or repeat values

    # 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.

Returns the $timer instance itself.



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.


Chase Whitener <capoeirab@cpan.org>


Daisuke Murase <typester@cpan.org>


Copyright 2012, Daisuke Murase.

This library is free software; you can redistribute it and/or modify it under the same terms as Perl itself.