=head1 NAME

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



=head1 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;



=head1 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 L<UniEvent::Tcp>, L<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 L<UniEvent::Handle>.



=head1 METHODS

All methods of L<UniEvent::Handle> also apply.

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

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

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


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

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

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


=head2 start($events, [$callback])

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

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

=over

=item READABLE

Event when socket is readable

=item WRITABLE

Event when socket is writeable

=item PRIORITIZED

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

=item 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.

=back

L<May return error|UniEvent/"OPTIONAL ERRORS">


=head2 stop()

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

L<May return error|UniEvent/"OPTIONAL ERRORS">


=head2 callback($callback)

=head2 event()

Callback signature:

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

Where C<$handle> is the Poll handle object itself.

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

The C<$err> parameter will be an L<XS::ErrorCode> object if any.

See L<UniEvent/"EVENT CALLBACKS">


=head2 event_listener($delegate, [$weak])

Method C<on_poll> will be called.

See L<UniEvent/"EVENT LISTENER">


=head2 call_now($events, [$error])

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



=head1 CAVEATS

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

On Windows only socket can be polled.

=cut
