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

AUTHOR

Paul Evans leonerd@leonerd.org.uk

AUTHORS EMERITUS

Daisuke Murase <typester@cpan.org>, Chase Whitener <capoeirab@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.