NAME
UV::Poll - Poll handles in libuv
SYNOPSIS
#!/usr/bin/env perl
use strict;
use warnings;
use UV;
# assume we have a file/IO handle from somewhere
# A new handle will be initialized against the default loop
my $poll = UV::Poll->new(fd => fileno($handle));
# Use a different loop
my $loop = UV::Loop->new(); # non-default loop
my $poll = UV::Poll->new(
fd => fileno($handle),
loop => $loop,
on_close => sub {say "close!"},
on_poll => sub {say "poll!"},
);
# Create a new poll on a socket handle
my $socket = IO::Socket::INET->new(Type => SOCK_STREAM);
my $poll = UV::Poll->new(
socket => 1,
fd => fileno($socket),
on_close => sub {say "close!"},
on_poll => sub {say "poll!"},
);
# setup the handle's callback:
$poll->on(poll => sub {"We're prepared!!!"});
# start the handle
$poll->start(UV::Poll::UV_READABLE);
# or, with an explicit callback defined
$poll->start(UV::Poll::UV_READABLE, sub {
my ($invocant, $status, $events) = @_;
say "override any other callback we already have";
});
# stop the handle
$poll->stop();DESCRIPTION
This module provides an interface to libuv's prepare handle.
Poll handles are used to watch file descriptors for readability, writability and disconnection similar to the purpose of poll(2).
The purpose of poll handles is to signal us about socket status changes. Using UV::Poll for any other purpose is not recommended; UV::TCP, UV::UDP, etc. provide an implementation that is faster and more scalable than what can be achieved with UV::Poll, especially on Windows.
It is possible that UV::Poll handles occasionally signal that a file descriptor is readable or writable even when it isn't. The user should therefore always be prepared to handle EAGAIN or equivalent when it attempts to read from or write to the fd.
It is not okay to have multiple active UV::Poll handles for the same socket, this can cause libuv to busyloop or otherwise malfunction.
The user should not close a file descriptor while it is being polled by an active UV::Poll handle. This can cause the handle to report an error, but it might also start polling another socket. However the fd can be safely closed immediately after a call to "stop" in UV::Poll or "close" in UV::Handle.
* Note: On Windows, only sockets can be polled with UV::Poll handles. On Unix, any file descriptor that would be accepted by poll(2) can be used.
* Note: On AIX, watching for disconnection is not supported.
CONSTANTS
POLL EVENT CONSTANTS
UV_READABLE
UV_WRITABLE
UV_DISCONNECT
UV_PRIORITIZED
EVENTS
UV::Poll inherits all events from UV::Handle and also makes the following extra events available.
poll
$poll->on(poll => sub {
my ($invocant, $status, $events) = @_;
say "We are here!";
});
my $count = 0;
$poll->on(poll => sub {
my $invocant = shift; # the handle instance this event fired on
if (++$count > 2) {
say "We've been called twice. stopping!";
$invocant->stop();
}
});When the event loop runs and the handle is ready, this event will be fired. UV::Poll handles will run the given callback once per loop iteration, right before polling for i/o.
METHODS
UV::Poll inherits all methods from UV::Handle and also makes the following extra methods available.
new
use IO::Socket::INET;
use UV ();
use UV::Loop ();
use UV::Poll qw(UV_READABLE UV_WRITABLE);
my $poll = UV::Poll->new(fd => fileno($some_handle));
# Or tell it what loop to initialize against
my $poll = UV::Poll->new(fd => fileno($some_handle), loop => $loop);
my $socket = IO::Socket::INET->new(Type => SOCK_STREAM);
my $poll = UV::Poll->new(socket => $socket);
# or another loop
my $poll = UV::Poll->new(
socket => $socket,
loop => $some_loop,
on_close => sub {say "close!"},
on_poll => sub {say "poll!"},
);
$poll->run(UV_READABLE | UV_WRITABLE, sub { ... });This constructor method creates a new UV::Poll object instance. It initializes the handle with either the given UV::Loop or the default loop.
Then initialization happens with init or init_socket.
A handle specified by the socket argument is initialised via uv_poll_init_socket, a distinction which matters to MSWin32. Code which wishes to be portable should remember to use this form so it will work correctly on that OS, even if the code works fine on others without it.
* Note: As of libuv v1.2.2: the file descriptor is set to non-blocking mode.
start
# Start the handle. By default, we'll:
# use the UV_READABLE events mask
# use whatever callback was supplied with ->on(poll => sub {...})
$poll->start();
# Pass events
$poll->start(UV_READABLE | UV_WRITABLE);
# pass a callback for the "idle" event
$poll->start(UV_READABLE, sub {say "yay"});
# providing the callback above completely overrides any callback previously
# set in the ->on() method. It's equivalent to:
$poll->on(idle => sub {say "yay"});
$poll->start(UV_READABLE);The start method starts polling the file descriptor. events is a bitmask made up of UV_READABLE, UV_WRITABLE, UV_PRIORITIZED and UV_DISCONNECT. As soon as an event is detected, the callback will be called with $status set to 0, and the detected events set on the $events field.
The UV_PRIORITIZED (added in libuv v1.14.0) event is used to watch for sysfs interrupts or TCP out-of-band messages.
The UV_DISCONNECT (added in libuv v1.9.0) event is optional in the sense that it may not be reported and the user is free to ignore it, but it can help optimize the shutdown path because an extra read or write call might be avoided.
If an error happens while polling, $status will be < 0 and correspond with one of the UV::UV_E* error codes. The user should not close the socket while the handle is active. If the user does that anyway, the callback may be called reporting an error status, but this is not guaranteed.
* Note: Calling $poll->start() on a handle that is already active is fine. Doing so will update the events mask that is being watched for.
* Note: Though UV_DISCONNECT can be set, it is unsupported on AIX and as such will not be set on the $events field in the callback.
stop
$poll->stop();The stop method stops polling the file descriptor. The callback will no longer be called.
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.