/ 
UV-1.903
River stage one • 3 direct dependents • 3 total dependents
/ UV

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

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 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 (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 (uint64_t).

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 (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 ...
}

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.