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