NAME

UniEvent::Poll - poll sockets or files for readability or writeability

SYNOPSIS

    use UniEvent::Poll;

    my $h = UniEvent::Poll->new($fd);
    close($fd); # it is safe to close, UniEvent::Poll duplicates it
    
    $h->start(READABLE | WRITABLE, sub {
        my ($handle, $events, $error) = @_;
        die "error: $error" if $error;
        say "can read" if $events & READABLE;
        say "can write" if $events & WRITABLE;
    });
    
    UE::Loop->default->run;
    
    $h->stop;

DESCRIPTION

The Poll handle polls sockets or files for readability or writeability. It was designed for intergration of raw sockets with third-party libraries that signal about socket status change. Using the Poll handle for other purposes is discouraged as it is not very efficient on certain systems. It is better to use UniEvent::Tcp, UniEvent::Pipe, etc... capabilities.

Beware that only one Poll handle should be per one file descriptor, otherwise undefined behaviour might happen.

The Poll handle is inherited from UniEvent::Handle.

METHODS

All methods of UniEvent::Handle also apply.

create($fd, $events, $callback, [$loop = default])

    my $handle = UniEvent::Poll->create($fd, $events, sub { say "hi" });

Creates and starts a poll handle. Alias for new($fd, $loop) + start($events, $callback).

new($fd, [$loop = default])

Constructs new Poll handle for the specified file descriptor $fd and binds it to the specified event loop.

The descriptor $fd is duplicated so you can close it via Perl's close() to forget about further descriptor management.

start($events, [$callback])

Starts the poll handle to watch the supplied $events. Optionally it adds the $callback as ->event->add($callback).

$events is a bitmask of the following constants (in UE::Poll::*):

READABLE

Event when socket is readable

WRITABLE

Event when socket is writeable

PRIORITIZED

Event is used to watch for sysfs interrupts or TCP out-of-band messages

DISCONNECT

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.

May return error

stop()

Stops the poll handle, i.e. makes it inactive for the next event loop iteration.

May return error

callback($callback)

event()

Callback signature:

    my ($handle, $events, $error) = @_;

Where $handle is the Poll handle object itself.

The $events parameter is an ORed mask of events constants (see start()).

The $err parameter will be an XS::ErrorCode object if any.

See "EVENT CALLBACKS" in UniEvent

event_listener($delegate, [$weak])

Method on_poll will be called.

See "EVENT LISTENER" in UniEvent

call_now($events, [$error])

Immediately ivokes assigned callbacks and listeners passing $events and $error to them.

CAVEATS

On *nix any file descriptor (including sockets) can be polled.

On Windows only socket can be polled.

cpanm UniEvent

perl -MCPAN -e shell
install UniEvent