NAME
UV - Perl interface to libuv
SYNOPSIS
#!/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);DESCRIPTION
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!
CONSTANTS
VERSION CONSTANTS
UV_VERSION_MAJOR
UV_VERSION_MINOR
UV_VERSION_PATCH
UV_VERSION_IS_RELEASE
UV_VERSION_SUFFIX
UV_VERSION_HEX
ERROR CONSTANTS
UV_E2BIG
Argument list too long
UV_EACCES
Permission denied
UV_EADDRINUSE
Address already in use
UV_EADDRNOTAVAIL
Address not available
UV_EAFNOSUPPORT
Address family not supported
UV_EAGAIN
Resource temporarily unavailable
UV_EAI_ADDRFAMILY
Address family not supported
UV_EAI_AGAIN
Temporary failure
UV_EAI_BADFLAGS
Bad ai_flags value
UV_EAI_BADHINTS
Invalid value for hints
UV_EAI_CANCELED
Request canceled
UV_EAI_FAIL
Permanent failure
UV_EAI_FAMILY
ai_family not supported
UV_EAI_MEMORY
Out of memory
UV_EAI_NODATA
No address
UV_EAI_NONAME
Unknown node or service
UV_EAI_OVERFLOW
Argument buffer overflow
UV_EAI_PROTOCOL
Resolved protocol is unknown
UV_EAI_SERVICE
Service not available for socket type
UV_EAI_SOCKTYPE
Socket type not supported
UV_EALREADY
Connection already in progress
UV_EBADF
Bad file descriptor
UV_EBUSY
Resource busy or locked
UV_ECANCELED
Operation canceled
UV_ECHARSET
Invalid Unicode character
UV_ECONNABORTED
Software caused connection abort
UV_ECONNREFUSED
Connection refused
UV_ECONNRESET
Connection reset by peer
UV_EDESTADDRREQ
Destination address required
UV_EEXIST
File already exists
UV_EFAULT
Bad address in system call argument
UV_EFBIG
File too large
UV_EHOSTUNREACH
Host is unreachable
UV_EINTR
Interrupted system call
UV_EINVAL
Invalid argument
UV_EIO
i/o error
UV_EISCONN
Socket is already connected
UV_EISDIR
Illegal operation on a directory
UV_ELOOP
Too many symbolic links encountered
UV_EMFILE
Too many open files
UV_EMLINK
Too many links
UV_EMSGSIZE
Message too long
UV_ENAMETOOLONG
Name too long
UV_ENETDOWN
Network is down
UV_ENETUNREACH
Network is unreachable
UV_ENFILE
File table overflow
UV_ENOBUFS
No buffer space available
UV_ENODEV
No such device
UV_ENOENT
No such file or directory
UV_ENOMEM
Not enough memory
UV_ENONET
Machine is not on the network
UV_ENOPROTOOPT
Protocol not available
UV_ENOSPC
No space left on device
UV_ENOSYS
Function not implemented
UV_ENOTCONN
Socket is not connected
UV_ENOTDIR
Not a directory
UV_ENOTEMPTY
Directory not empty
UV_ENOTSOCK
Socket operation on non-socket
UV_ENOTSUP
Operation not supported on socket
UV_ENXIO
No such device or address
UV_EOF
End of file
UV_EPERM
Operation not permitted
UV_EPIPE
Broken pipe
UV_EPROTO
Protocol error
UV_EPROTONOSUPPORT
Protocol not supported
UV_EPROTOTYPE
Protocol wrong type for socket
UV_ERANGE
Result too large
UV_EROFS
Read-only file system
UV_ESHUTDOWN
Cannot send after transport endpoint shutdown
UV_ESPIPE
Invalid seek
UV_ESRCH
No such process
UV_ETIMEDOUT
Connection timed out
UV_ETXTBSY
Text file is busy
UV_EXDEV
Cross-device link not permitted
UV_UNKNOWN
Unknown error
FUNCTIONS
The following functions are available:
check
my $handle = UV::check(); # uses the default loop
my $handle = UV::check(loop => $some_other_loop); # non-default loopReturns a new UV::Check Handle object.
default_loop
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 (which is a singleton object). This module already creates the default loop and you get access to it with this method.
err_name
my $error_name = UV::err_name(UV::UV_EAI_BADFLAGS);
say $error_name; # EAI_BADFLAGSThe 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.
hrtime
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.
idle
my $handle = UV::idle(); # uses the default loop
my $handle = UV::idle(loop => $some_other_loop); # non-default loopReturns a new UV::Idle Handle object.
loop
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();Returns the default loop (which is a singleton object). This module already creates the default loop and you get access to it with this method.
poll
my $handle = UV::poll(); # uses the default loop
my $handle = UV::poll(loop => $some_other_loop); # non-default loopReturns a new UV::Poll Handle object.
prepare
my $handle = UV::prepare(); # uses the default loop
my $handle = UV::prepare(loop => $some_other_loop); # non-default loopReturns a new UV::Prepare Handle object.
signal
my $handle = UV::signal(POSIX::SIGHUP); # uses the default loop
my $handle = UV::signal(loop => $some_other_loop, signal => POSIX::SIGHUP);
# non-default loopReturns a new UV::Signal Handle object.
strerror
my $error = UV::strerror(UV::UV_EAI_BADFLAGS);
say $error; # bad ai_flags valueThe 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.
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.
tcp
my $tcp = UV::tcp();Returns a new UV::TCP object.
timer
my $timer = UV::timer(); # uses the default loop
my $timer = UV::timer(loop => $some_other_loop); # non-default loopReturns a new UV::Timer object.
tty
my $tty = UV::tty(fd => 0);Returns a new UV::TTY object.
udp
my $udp = UV::udp();Returns a new UV::UDP object.
version
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.
version_string
say UV::version_string();
# 1.13.1The version_string function returns the libuv version number as a string. For non-release versions the version suffix is included.
EXCEPTIONS
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.
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.
try { ... }
catch my $e {
if(blessed $e and $e->isa("UV::Exception::ECANCELED") {
# ignore
}
else ...
}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.