UV - Perl interface to libuv
#!/usr/bin/env perl use strict; use warnings; use UV; use UV::Loop; # hi-resolution time my $hi_res_time = UV::hrtime(); # A new loop my $loop = UV::Loop->new(); # default loop my $loop = UV::Loop->default_loop(); # convenience singleton constructor my $loop = UV::Loop->default(); # convenience 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. 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!
The following functions are available:
my $handle = UV::check(); # uses the default loop my $handle = UV::check(loop => $some_other_loop); # non-default loop
Returns a new UV::Check Handle object.
my $loop = UV::default_loop(); # You can also get it with the UV::Loop methods below: my $loop = UV::Loop->default_loop(); my $loop = UV::Loop->default(); # Passing a true value as the first arg to the UV::Loop constructor # will also return the default loop my $loop = UV::Loop->new(1);
Returns the default loop as a UV::Loop instance (which is a singleton object). This module already creates the default loop and you get access to it with this method.
my $error_name = UV::err_name(UV::UV_EAI_BADFLAGS); say $error_name; # EAI_BADFLAGS
The err_name function returns the error name for the given error code. Leaks a few bytes of memory when you call it with an unknown error code.
In libuv errors are negative numbered constants. As a rule of thumb, whenever there is a status parameter, or an API functions returns an integer, a negative number will imply an error.
When a function which takes a callback returns an error, the callback will never be called.
my $uint64_t = UV::hrtime();
Get the current Hi-Res time; a value given in nanoseconds since some arbitrary point in the past. On 64bit-capable perls this will be represented by an integer with full precision. On perls unable to represent a 64bit integer this will be given as a floating-point value so may lose some precision if the value is large enough.
my $handle = UV::idle(); # uses the default loop my $handle = UV::idle(loop => $some_other_loop); # non-default loop
Returns a new UV::Idle Handle object.
my $loop = UV::loop(); # You can also get it with the UV::Loop methods below: my $loop = UV::Loop->default_loop(); my $loop = UV::Loop->default();
my $handle = UV::poll(); # uses the default loop my $handle = UV::poll(loop => $some_other_loop); # non-default loop
Returns a new UV::Poll Handle object.
my $handle = UV::prepare(); # uses the default loop my $handle = UV::prepare(loop => $some_other_loop); # non-default loop
Returns a new UV::Prepare Handle object.
my $handle = UV::signal(POSIX::SIGHUP); # uses the default loop my $handle = UV::signal(loop => $some_other_loop, signal => POSIX::SIGHUP); # non-default loop
Returns a new UV::Signal Handle object.
my $error = UV::strerror(UV::UV_EAI_BADFLAGS); say $error; # bad ai_flags value
The strerror function returns the error message for the given error code. Leaks a few bytes of memory when you call it with an unknown error code.
my $tcp = UV::tcp();
Returns a new UV::TCP object.
my $timer = UV::timer(); # uses the default loop my $timer = UV::timer(loop => $some_other_loop); # non-default loop
Returns a new UV::Timer object.
my $tty = UV::tty(fd => 0);
Returns a new UV::TTY object.
my $udp = UV::udp();
Returns a new UV::UDP object.
my $int = UV::version();
The version function returns UV::UV_VERSION_HEX, the libuv version packed into a single integer. 8 bits are used for each component, with the patch number stored in the 8 least significant bits. E.g. for libuv 1.2.3 this would be 0x010203.
UV::UV_VERSION_HEX
0x010203
say UV::version_string(); # 1.13.1
The version_string function returns the libuv version number as a string. For non-release versions the version suffix is included.
If any call to libuv fails, an exception will be thrown. The exception will be a blessed object having a code method which returns the numerical error code (which can be compared to one of the UV::UV_E* error constants), and a message method which returns a human-readable string describing the failure.
code
UV::UV_E*
message
try { ... } catch my $e { if(blessed $e and $e->isa("UV::Exception")) { print "The failure was ", $e->message, " of code ", $e->code; } }
The exception class provides stringify overload to call the message method, so the normal Perl behaviour of just printing the exception will print the message from it, as expected.
Exceptions are blessed into a subclass of UV::Exception named after the type of the failure code. This allows type-based testing of error types.
UV::Exception
try { ... } catch my $e { if(blessed $e and $e->isa("UV::Exception::ECANCELED") { # ignore } else ... }
Argument list too long
Permission denied
Address already in use
Address not available
Address family not supported
Resource temporarily unavailable
Temporary failure
Bad ai_flags value
Invalid value for hints
Request canceled
Permanent failure
ai_family not supported
Out of memory
No address
Unknown node or service
Argument buffer overflow
Resolved protocol is unknown
Service not available for socket type
Socket type not supported
Connection already in progress
Bad file descriptor
Resource busy or locked
Operation canceled
Invalid Unicode character
Software caused connection abort
Connection refused
Connection reset by peer
Destination address required
File already exists
Bad address in system call argument
File too large
Host is unreachable
Interrupted system call
Invalid argument
i/o error
Socket is already connected
Illegal operation on a directory
Too many symbolic links encountered
Too many open files
Too many links
Message too long
Name too long
Network is down
Network is unreachable
File table overflow
No buffer space available
No such device
No such file or directory
Not enough memory
Machine is not on the network
Protocol not available
No space left on device
Function not implemented
Socket is not connected
Not a directory
Directory not empty
Socket operation on non-socket
Operation not supported on socket
No such device or address
End of file
Operation not permitted
Broken pipe
Protocol error
Protocol not supported
Protocol wrong type for socket
Result too large
Read-only file system
Cannot send after transport endpoint shutdown
Invalid seek
No such process
Connection timed out
Text file is busy
Cross-device link not permitted
Unknown error
The following features of libuv are not currently wrapped by this module, but may be possible in some future version:
Filesystem requests listed in http://docs.libuv.org/en/v1.x/fs.html.
Thread pools listed in http://docs.libuv.org/en/v1.x/threadpool.html.
Many of the misc utilities listed in http://docs.libuv.org/en/v1.x/misc.html.
UV::Process stdio stream arguments given at http://docs.libuv.org/en/v1.x/process.html#c.uv_stdio_flags.
Paul Evans <leonerd@leonerd.org.uk>
Daisuke Murase <typester@cpan.org>, Chase Whitener <capoeirab@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.