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!

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

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

    Copyright 2012, Daisuke Murase.

    This library is free software; you can redistribute it and/or modify it
    under the same terms as Perl itself.