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! 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 loop Returns 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 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. err_name 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. 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 loop Returns 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 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. poll 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. prepare 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. signal 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. strerror 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. 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 loop Returns 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.1 The 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 ... } 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 TODO 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. AUTHOR Paul Evans AUTHORS EMERITUS Daisuke Murase , Chase Whitener 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.