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(fileno($handle));

  # Use a different loop
  my $loop = UV::Loop->new(); # non-default loop
  my $poll = UV::Poll->new(fileno($handle), $loop);

  # 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(prepare => 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

    my $poll = UV::Poll->new(fileno($some_handle));
    # Or tell it what loop to initialize against
    my $poll = UV::Poll->new(fileno($some_handle), $loop);

This constructor method creates a new UV::Poll object and initializes the handle with the given UV::Loop to poll for a file descriptor. If no UV::Loop is provided, then the "default_loop" in UV::Loop is assumed.

* Note: As of libuv v1.2.2: the file descriptor is set to non-blocking mode.

new_socket

    use IO::Socket::INET;
    use UV;
    use UV::Poll qw(UV_READABLE UV_WRITABLE);

    my $socket = IO::Socket::INET->new(Type => SOCK_STREAM);

    my $poll = UV::Poll->new_socket(fileno($socket));
    my $poll = UV::Poll->new_socket(fileno($socket), $some_loop); # or another loop

    $poll->run(UV_READABLE | UV_WRITABLE, sub { ... });

This constructor method creates a new UV::Poll object and initializes the handle with the given UV::Loop to poll for a socket handle. If no UV::Loop is provided, then the "default_loop" in UV::Loop is assumed.

* Note: As of libuv v1.2.2: the file socket 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 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.

cpanm UV

perl -MCPAN -e shell
install UV