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 <leonerd@leonerd.org.uk>

AUTHORS EMERITUS

Daisuke Murase <typester@cpan.org>, Chase Whitener <capoeirab@cpan.org>

COPYRIGHT AND LICENSE

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.

	Global
`s`	Focus search bar
`?`	Bring up this help dialog

	GitHub
`g` `p`	Go to pull requests
`g` `i`	go to github issues (only if github is preferred repository)

	POD
`g` `a`	Go to author
`g` `c`	Go to changes
`g` `i`	Go to issues
`g` `d`	Go to dist
`g` `r`	Go to repository/SCM
`g` `s`	Go to source
`g` `b`	Go to file browse

	Search terms
module: (e.g. module:Plugin)
distribution: (e.g. distribution:Dancer auth)
author: (e.g. author:SONGMU Redis)
version: (e.g. version:1.00)