NAME
    UV - perl interface to libuv

SYNOPSIS
        use UV;
    
        # TIMERS
        my $timer = UV::timer_init();
        UV::timer_start($timer, 2000, 0, sub {
            warn "is called after 2000ms";
        });
    
        my $timer = UV::timer_init();
        UV::timer_start($timer, 2000, 2000, sub {
            warn "is called roughly every 2s (repeat = 2)";
        });
    
        UV::timer_stop($timer); # stop timer
        UV::close($timer); # destroy timer object
    
        # IO (Simple tcp echo server)
        my $server = UV::tcp_init();
        UV::tcp_bind($server, '0.0.0.0', 5000)
            && die 'bind error: ', UV::strerror(UV::last_error());
    
        UV::listen($server, 10, sub {
            my $client = UV::tcp_init();
            UV::accept($server, $client) && die 'accept failed: ', UV::strerror(UV::last_error());
    
            UV::read_start($client, sub {
                my ($nread, $buf) = @_;
    
                if ($nread < 0) {
                    my $err = UV::last_error();
                    if ($err != UV::EOF) {
                        warn 'client read error: ', UV::strerror($err);
                    }
                    UV::close($client);
                }
                elsif ($nread == 0) {
                    # nothing to read
                }
                else {
                    UV::write($client, $buf, sub {
                        my ($status) = @_;
    
                        if ($status) {
                            warn 'client write error: ', UV::strerror(UV::last_error());
                            UV::close($client);
                        }
                    });
                }
            });
    
        }) && die 'listen error: ', UV::strerror(UV::last_error());
    
        # MAINLOOP
        UV::run()

DESCRIPTION
    UV provides low-level interface to libuv,
    https://github.com/joyent/libuv, platform layer for node.js.

    Low-level means this module's functions maps to libuv functions
    directry. "uv_listen" maps to "UV::listen", "uv_tcp_connect" to
    "UV::tcp_connect", and so on.

    This is because I'm using this module to make some prototypes for native
    C application which uses libuv. Perl codes using this module can be
    easily converted to C programs.

CAUTION
    Currently this module is in early development stage. The APIs are still
    fluid, and may change.

THERE IS SOME LIMITATIONS AT THIS TIME
    No file-system apis, no threads apis at this time, it's not nessesary
    for my prototyping purpose now.

    But patches always welcome :)

FUNCTIONS
    List of currently supported functions. Descriptions after function name
    are copied and pasted from uv.h

  my $loop = UV::default_loop()
    Get default loop handle. In p5-UV, this default_loop is only loop that
    is supported. Other functions that depends loop handle uses this
    default_loop implicitly.

    Currently this $loop object contains only active_handles information.
    You can get active_handles count by doing following:

        my $count = $loop->active_handles;

  UV::run()
    This function starts the event loop. It blocks until the reference count
    of the loop drops to zero. Always returns zero.

  UV::run_once()
    Poll for new events once. Note that this function blocks if there are no
    pending events. Returns zero when done (no active handles or requests
    left), or non-zero if more events are expected (meaning you should call
    uv_run_once() again sometime in the future).

  my $err = UV::last_error()
  my $str_error = UV::strerror($err)
  my $err_name = UV::err_name($err)
    Most functions return boolean: 0 for success and -1 for failure. On
    error the user should then call uv_last_error() to determine the error
    code.

  UV::shutdown($handle, $cb)
    Shutdown the outgoing (write) side of a duplex stream. It waits for
    pending write requests to complete. The handle should refer to a
    initialized stream. req should be an uninitialized shutdown request
    struct. The cb is called after shutdown is complete.

  UV::is_active($handle)
    Returns 1 if the prepare/check/idle/timer handle has been started, 0
    otherwise. For other handle types this always returns 1.

  UV::walk($walk_cb)
    Walk the list of open handles.

  UV::close($handle)
    Request handle to be closed. This MUST be called on each handle before
    memory is released.

    In-progress requests, like "UV::connect" or "UV::write", are cancelled
    and have their callbacks called asynchronously with status=-1 and the
    error code set to "UV::ECANCELED".

  UV::listen($stream, $backlog, $connection_cb)
  UV::accept($server_stream, $client_stream)
    This call is used in conjunction with `UV::listen` to accept incoming
    connections. Call `UV::accept` after receiving a $connection_cb to
    accept the connection. Before calling "UV::accept" use "UV::*_init()"
    must be called on the client. Non-zero return value indicates an error.

    When the $connection_cb is called it is guaranteed that "UV::accept"
    will complete successfully the first time. If you attempt to use it more
    than once, it may fail. It is suggested to only call uv_accept once per
    uv_connection_cb call.

  UV::read_start($stream, $read_cb)
  UV::read_stop($stream)
    Read data from an incoming stream. The callback will be made several
    several times until there is no more data to read or uv_read_stop is
    called. When we've reached EOF nread will be set to -1 and the error is
    set to UV_EOF. When nread == -1 the buf parameter might not point to a
    valid buffer; in that case buf.len and buf.base are both set to 0. Note
    that nread might also be 0, which does *not* indicate an error or eof;
    it happens when libuv requested a buffer through the alloc callback but
    then decided that it didn't need that buffer.

  UV::read2_start($stream, $read2_cb)
    Extended read methods for receiving handles over a pipe. The pipe must
    be initialized with ipc == 1.

  UV::write($stream, $buf)
  UV::write($stream, $buf, $write_cb)
    Write $buf to stream.

  UV::write2($stream, $buf, $send_stream)
  UV::write2($stream, $buf, $send_stream, $write_cb)
    Extended write function for sending handles over a pipe. The pipe must
    be initialized with ipc == 1. send_handle must be a TCP socket or pipe,
    which is a server or a connection (listening or connected state). Bound
    sockets or pipes will be assumed to be servers.

  UV::is_readable($stream)
  UV::is_writeable($stream)
    Used to determine whether a stream is readable or writable.

  UV::is_closing($handle)
    Used to determine whether a stream is closing or closed.

    N.B. is only valid between the initialization of the handle and the
    arrival of the close callback, and cannot be used to validate the
    handle.

  my $tcp_stream = UV::tcp_init()
    Initialize tcp_stream object.

  UV::tcp_nodelay($handle, $enable = 1)
    Enable/disable Nagle's algorithm.

  UV::tcp_keepalive($handle, $enable, $delay)
    Enable/disable TCP keep-alive.

    `ms` is the initial delay in seconds, ignored when `enable` is zero.

  UV::tcp_simultaneous_accepts($handle, $enable)
    This setting applies to Windows only. Enable/disable simultaneous
    asynchronous accept requests that are queued by the operating system
    when listening for new tcp connections. This setting is used to tune a
    tcp server for the desired performance. Having simultaneous accepts can
    significantly improve the rate of accepting connections (which is why it
    is enabled by default).

  UV::tcp_bind($handle, $ip, $port)
  UV::tcp_bind6($handle, $ip, $port)
    Bind tcp handles to $ip:$port

  my ($ip, $port) = UV::tcp_getsockname($handle)
  my ($ip, $port) = UV::tcp_getpeername($handle)
    get tcp sockname or peername and return it as array.

  UV::tcp_connect($handle, $ip, $port, $connect_cb)
  UV::tcp_connect6($handle, $ip, $port, $connect_cb)
    uv_tcp_connect, uv_tcp_connect6 These functions establish IPv4 and IPv6
    TCP connections. Provide an initialized TCP handle and an uninitialized
    uv_connect_t*. The callback will be made when the connection is
    established.

  my $udp = UV::udp_init()
    Initialize a new UDP handle. The actual socket is created lazily.
    Returns 0 on success.

  UV::udp_bind($handle, $ip, $port, $flags = 0)
  UV::udp_bind6($handle, $ip, $port, $flags = 0)
    Bind to a IPv4/IPv6 address and port.

    Arguments: handle UDP handle. Should have been initialized with
    `uv_udp_init`. addr struct sockaddr_in with the address and port to bind
    to. flags Unused.

    Returns: 0 on success, -1 on error.

  my ($ip, $port) = UV::udp_getsockname($handle)
    get udp sockname and return it as array

  UV::udp_set_membership($handle, $multicast_addr, $interface_addr, $membership)
    Set membership for a multicast address

    Arguments: handle UDP handle. Should have been initialized with
    `uv_udp_init`. multicast_addr multicast address to set membership for
    interface_addr interface address membership Should be UV_JOIN_GROUP or
    UV_LEAVE_GROUP

    Returns: 0 on success, -1 on error.

  UV::set_multicast_loop($handle, $on)
    Set IP multicast loop flag. Makes multicast packets loop back to local
    sockets.

    Arguments: handle UDP handle. Should have been initialized with
    `uv_udp_init`. on 1 for on, 0 for off

    Returns: 0 on success, -1 on error.

  UV::set_multicast_ttl($handle, $ttl)
    Set the multicast ttl

    Arguments: handle UDP handle. Should have been initialized with
    `uv_udp_init`. ttl 1 through 255

    Returns: 0 on success, -1 on error.

  UV::udp_set_broadcast($handle, $on)
    Set broadcast on or off

    Arguments: handle UDP handle. Should have been initialized with
    `uv_udp_init`. on 1 for on, 0 for off

    Returns: 0 on success, -1 on error.

  UV::udp_set_ttl($handle, $ttl)
    Set the time to live

    Arguments: handle UDP handle. Should have been initialized with
    `uv_udp_init`. ttl 1 through 255

    Returns: 0 on success, -1 on error.

  UV::udp_send($handle, $buf, $ip, $port, $send_cb)
  UV::udp_send6($handle, $buf, $ip, $port, $send_cb)
    Send data. If the socket has not previously been bound with
    `uv_udp_bind` or `uv_udp_bind6`, it is bound to 0.0.0.0 / ::0 (the "all
    interfaces" address) and a random port number.

    Arguments: handle UDP handle. Should have been initialized with
    `uv_udp_init`. buf buffer to send. ip target ip port target port send_cb
    Callback to invoke when the data has been sent out.

    Returns: 0 on success, -1 on error.

  UV::udp_recv_start($handle, $recv_cb)
    Receive data. If the socket has not previously been bound with
    `uv_udp_bind` or `uv_udp_bind6`, it is bound to 0.0.0.0 (the "all
    interfaces" address) and a random port number.

    Arguments: handle UDP handle. Should have been initialized with
    `uv_udp_init`. recv_cb Callback to invoke with received data.

    Returns: 0 on success, -1 on error.

  UV::udp_recv_stop($handle)
    Stop listening for incoming datagrams.

    Arguments: handle UDP handle. Should have been initialized with
    `uv_udp_init`.

    Returns: 0 on success, -1 on error.

  my $tty = UV::tty_init($fd, $readable)
    Initialize a new TTY stream with the given file descriptor. Usually the
    file descriptor will be 0 = stdin 1 = stdout 2 = stderr The last
    argument, readable, specifies if you plan on calling uv_read_start with
    this stream. stdin is readable, stdout is not.

    TTY streams which are not readable have blocking writes.

  UV::tty_set_mode($tty, $mode)
    Set mode. 0 for normal, 1 for raw.

  UV::tty_reset_mode()
    To be called when the program exits. Resets TTY settings to default
    values for the next process to take over.

  my ($width, $height) = UV::tty_get_winsize($tty)
    Gets the current Window size as array.

  my $poll = UV::poll_init($fd)
    Initialize the poll watcher using a file descriptor.

  UV::poll_start($handle, $events, $poll_cb)
    Starts polling the file descriptor. `events` is a bitmask consisting
    made up of UV_READABLE and UV_WRITABLE. As soon as an event is detected
    the callback will be called with `status` set to 0, and the detected
    events set en the `events` field.

    If an error happens while polling status may be set to -1 and the error
    code can be retrieved with uv_last_error. The user should not close the
    socket while uv_poll is active. If the user does that anyway, the
    callback *may* be called reporting an error status, but this is not
    guaranteed.

    Calling uv_poll_start on an uv_poll watcher that is already active is
    fine. Doing so will update the events mask that is being watched for.

  UV::poll_stop($handle)
    Stops polling the file descriptor.

  UV::guess_handle($fd)
    Used to detect what type of stream should be used with a given file
    descriptor. Usually this will be used during initialization to guess the
    type of the stdio streams. For isatty() functionality use this function
    and test for UV_TTY.

  my $pipe = UV::pipe_init()
    Initialize a pipe. The last argument is a boolean to indicate if this
    pipe will be used for handle passing between processes.

  UV::pipe_open($handle, $fd)
  UV::pipd_bind($handle, $name)
  UV::pipe_connect($handle, $name, $connect_cb)
    Opens an existing file descriptor or HANDLE as a pipe.

  my $prepare = UV::prepare_init()
  UV::prepare_start($prepare, $prepare_cb)
  UV::prepare_stop($prepare)
    libev wrapper. Every active prepare handle gets its callback called
    exactly once per loop iteration, just before the system blocks to wait
    for completed i/o.

  my $check = UV::check_init()
  UV::check_start($check, $check_cb)
  UV::check_stop($check)
    libev wrapper. Every active check handle gets its callback called
    exactly once per loop iteration, just after the system returns from
    blocking.

  my $idle = UV::idle_init()
  UV::idle_start($idle, $idle_cb)
  UV::idle_stop($idle)
    libev wrapper. Every active idle handle gets its callback called
    repeatedly until it is stopped. This happens after all other types of
    callbacks are processed. When there are multiple "idle" handles active,
    their callbacks are called in turn.

  my $async = UV::async_init()
  UV::async_send($async)
    libev wrapper. uv_async_send wakes up the event loop and calls the async
    handle's callback There is no guarantee that every uv_async_send call
    leads to exactly one invocation of the callback; The only guarantee is
    that the callback function is called at least once after the call to
    async_send. Unlike all other libuv functions, uv_async_send can be
    called from another thread.

  my $timer = UV::timer_init()
    Create timer handle

  UV::timer_start($timer, $timeout, $repeat, $timer_cb)
  UV::timer_stop($timer)
    Start the timer. `timeout` and `repeat` are in milliseconds.

    If timeout is zero, the callback fires on the next tick of the event
    loop.

    If repeat is non-zero, the callback fires first after timeout
    milliseconds and then repeatedly after repeat milliseconds.

    timeout and repeat are signed integers but that will change in a future
    version of libuv. Don't pass in negative values, you'll get a nasty
    surprise when that change becomes effective.

  UV::timer_again($timer)
    Stop the timer, and if it is repeating restart it using the repeat value
    as the timeout. If the timer has never been started before it returns -1
    and sets the error to UV_EINVAL.

  UV::timer_set_repeat($timer, $repeat)
  UV::timer_get_repeat($timer)
    Set the repeat value in milliseconds. Note that if the repeat value is
    set from a timer callback it does not immediately take effect. If the
    timer was non-repeating before, it will have been stopped. If it was
    repeating, then the old repeat value will have been used to schedule the
    next timeout.

  UV::getaddrinfo($node, $service, $getaddrinfo_cb, $hint = 0)
    Asynchronous getaddrinfo(3).

    Either node or service may be NULL but not both.

    hints is a pointer to a struct addrinfo with additional address type
    constraints, or NULL. Consult `man -s 3 getaddrinfo` for details.

    Returns 0 on success, -1 on error. Call uv_last_error() to get the
    error.

    If successful, your callback gets called sometime in the future with the
    lookup result, which is either:

     a) status == 0, the res argument points to a valid struct addrinfo, or
     b) status == -1, the res argument is NULL.

    On NXDOMAIN, the status code is -1 and uv_last_error() returns
    UV_ENOENT.

    Call uv_freeaddrinfo() to free the addrinfo structure.

AUTHOR
    Daisuke Murase <typester@cpan.org>

    TAGOMORI Satoshi