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 <http://libuv.org>. We will
    try to document things here as best as we can, but we also suggest you
    look at the libuv docs <http://docs.libuv.org> 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 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 <http://docs.libuv.org/en/v1.x/errors.html#c.uv_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 <http://docs.libuv.org/en/v1.x/errors.html#c.uv_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 <http://docs.libuv.org/en/v1.x/version.html#c.uv_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
    <http://docs.libuv.org/en/v1.x/version.html#c.uv_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.