NAME

UV::Loop - Looping with libuv

SYNOPSIS

#!/usr/bin/env perl
use strict;
use warnings;

use UV::Loop ();

# A new, non-default loop
my $loop = UV::Loop->new();

# A new default loop instance (Singleton)
$loop = UV::Loop->default_loop(); # singleton constructor
$loop = UV::Loop->default(); # singleton constructor

# run a loop with one of three options:
# UV_RUN_DEFAULT, UV_RUN_ONCE, UV_RUN_NOWAIT
$loop->run(); # runs with UV_RUN_DEFAULT
$loop->run(UV::Loop::UV_RUN_DEFAULT); # explicitly state UV_RUN_DEFAULT
$loop->run(UV::Loop::UV_RUN_ONCE);
$loop->run(UV::Loop::UV_RUN_NOWAIT);

DESCRIPTION

This module provides an interface to libuv's loop. 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.

Event loops that work properly on all platforms. YAY!

CONSTANTS

RUN MODE CONSTANTS

UV_RUN_DEFAULT

UV_RUN_NOWAIT

UV_RUN_ONCE

CONFIGURE CONSTANTS

SIGPROF

UV_LOOP_BLOCK_SIGNAL

METHODS

UV::Loop makes the following methods available.

new

my $loop = UV::Loop->new();
my $default_loop = UV::Loop->default_loop();
my $default_loop = UV::Loop->default();

This constructor either returns the default loop (singleton object), or creates a new event loop and initializes it.

Please look at the documentation from libuv.

alive

my $int = $loop->alive();

The alive method returns a non-zero value if there are active handles or requests in the loop.

backend_fd

my $int = $loop->backend_fd();

The backend_fd method returns the backend file descriptor. Only kqueue, epoll and event ports are supported.

This can be used in conjunction with "run" in UV::Loop and UV_RUN_NOWAIT to poll in one thread and run the event loop's callbacks in another.

* Note: Embedding a kqueue fd in another kqueue pollset doesn't work on all platforms. It's not an error to add the fd but it never generates events.

backend_timeout

my $int = $loop->backend_timeout();

The backend_timeout method returns the poll timeout. The return value is in milliseconds, or -1 for no timeout.

configure

my $int = $loop->configure();

The configure method sets additional loop options. You should normally call this before the first call to "run" in UV::Loop unless mentioned otherwise.

Supported options:

UV_LOOP_BLOCK_SIGNAL: Block a signal when polling for new events. The second argument to $loop->configure is the signal number.

This operation is currently only implemented for SIGPROF signals, to suppress unnecessary wakeups when using a sampling profiler. Requesting other signals will fail with UV::UV_EINVAL.

default

# this is a singleton constructor. you'll get the same instance each time
my $default_loop = UV::Loop->default();

A singleton method to get the default loop instance.

default_loop

# this is a singleton constructor. you'll get the same instance each time
my $default_loop = UV::Loop->default_loop();

A singleton method to get the default loop instance.

is_default

# lets us know if this loop is the default loop for this context
my $bool = $loop->is_default();

A read-only method to let us know if we're dealing with the default loop.

now

my $uint64_t = $loop->now();

The now method returns the current timestamp in milliseconds. The timestamp is cached at the start of the event loop tick, see "update_loop" in UV::Loop for details and rationale.

The timestamp increases monotonically from some arbitrary point in time. Don't make assumptions about the starting point, you will only get disappointed.

* Note: Use "hrtime" in UV if you need sub-millisecond granularity.

run

# use UV_RUN_DEFAULT by default
my $int = $loop->run();
# or, explicitly use it:
my $int = $loop->run(UV::Loop::UV_RUN_DEFAULT);
# run in UV_RUN_NOWAIT mode
my $int = $loop->run(UV::Loop::UV_RUN_NOWAIT);
# run in UV_RUN_ONCE mode
my $int = $loop->run(UV::Loop::UV_RUN_ONCE);

The run method runs the event loop. It will act differently depending on the specified mode:

UV_RUN_DEFAULT Runs the event loop until there are no more active and referenced handles or requests. Returns non-zero if "stop" in UV::Loop was called and there are still active handles or requests. Returns zero in all other cases.
UV_RUN_NOWAIT Poll for i/o once but don't block if there are no pending callbacks. Returns zero if done (no active handles or requests left), or non-zero if more callbacks are expected (meaning you should run the event loop again sometime in the future).
UV_RUN_ONCE Poll for i/o once. Note that this function blocks if there are no pending callbacks. Returns zero when done (no active handles or requests left), or non-zero if more callbacks are expected (meaning you should run the event loop again sometime in the future).

stop

$loop->stop();

The stop method stops the event loop, causing "run" in UV::Loop to end as soon as possible. This will happen not sooner than the next loop iteration. If this function was called before blocking for i/o, the loop won't block for i/o on this iteration.

update_time

$loop->update_time();

The update_time method updates the event loop's concept of "now" in UV::Loop. Libuv caches the current time at the start of the event loop tick in order to reduce the number of time-related system calls.

You won't normally need to call this method unless you have callbacks that block the event loop for longer periods of time, where "longer" is somewhat subjective but probably on the order of a millisecond or more.

walk

The walk method is currently not implemented. See also

https://github.com/p5-UV/p5-UV/issues/33

getaddrinfo

$req = $loop->getaddrinfo($args, $callback);

    $callback->($status, @results)

The getaddrinfo method performs an asynchronous name lookup, turning a hostname and/or service name into a set of socket addresses suitable for connect() or bind().

The arguments passed by hash reference must include at least one of node and service, giving names of the entity to be looked up. Optional numerical parameters flags, family, socktype and protocol will be passed as hints if given.

The method returns a UV::Req instance representing the pending request. The caller does not need to hold a reference to it, but it may be used to cancel the request if so.

When complete, the callback will be invoked with a status code indicating success or failure, and a list of result objects. Each value in the result list will have methods family, socktype and protocol returning integers, and addr and canonname returning a string.

$result->family
$result->socktype
$result->protocol
$result->addr
$result->canonname

The canonname field will only be set on the first result, and only if the AI_CANONNAME flag was included in the request.

getnameinfo

$req = $loop->getnameinfo($addr, $flags, $callback)

    $callback->($status, $hostname, $service)

The getnameinfo method performs an asynchronous reverse name lookup, turning a socket address into a human-readable host and service name.