UV::Loop - Looping with libuv
#!/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);
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!
UV::Loop makes the following methods available.
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.
my $int = $loop->alive();
The alive method returns a non-zero value if there are active handles or requests in the loop.
my $int = $loop->backend_fd();
The backend_fd method returns the backend file descriptor. Only kqueue, epoll and event ports are supported.
kqueue
epoll
event ports
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.
UV_RUN_NOWAIT
* 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.
kqueue fd
kqueue pollset
fd
my $int = $loop->backend_timeout();
The backend_timeout method returns the poll timeout. The return value is in milliseconds, or -1 for no timeout.
-1
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.
UV_LOOP_BLOCK_SIGNAL
$loop->configure
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.
SIGPROF
UV::UV_EINVAL
# 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.
# this is a singleton constructor. you'll get the same instance each time my $default_loop = UV::Loop->default_loop();
# 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.
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.
# 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_DEFAULT
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).
UV_RUN_ONCE
$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.
$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.
The walk method is currently not implemented. See also
https://github.com/p5-UV/p5-UV/issues/33
$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().
connect()
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.
node
service
flags
family
socktype
protocol
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.
addr
canonname
$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.
AI_CANONNAME
$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.
When complete, the callback will be invoked with a status code indicating success or failure, and the resolved host and service names.
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.
To install UV, copy and paste the appropriate command in to your terminal.
cpanm
cpanm UV
CPAN shell
perl -MCPAN -e shell install UV
For more information on module installation, please visit the detailed CPAN module installation guide.