NAME

Reflex::Handle - Watch a filehandle for read- and/or writability.

VERSION

version 0.005

SYNOPSIS

        package Reflex::Listener;
        use Moose;
        extends 'Reflex::Handle';

        has '+rd' => ( default => 1 );

        sub on_handle_readable {
                my ($self, $args) = @_;

                my $peer = accept(my ($socket), $args->{handle});
                if ($peer) {
                        $self->emit(
                                event => "accepted",
                                args  => {
                                        peer    => $peer,
                                        socket  => $socket,
                                }
                        );
                        return;
                }

                $self->emit(
                        event => "failure",
                        args  => {
                                peer    => undef,
                                socket  => undef,
                                errnum  => ($!+0),
                                errstr  => "$!",
                                errfun  => "accept",
                        },
                );
        }

        1;

DESCRIPTION

Reflex::Handle watches a filehandle and emits events when it has data to be read, is ready to be written upon, or has some exceptional condition to be addressed.

As with most Reflex objects, Reflex::Handle may be composed by subclassing (is-a) or by containership (has-a).

Attributes

Reflex::Handle has a few attributes that control its behavior. These attributes may be specified during construction. They may also be changed while the object runs through methods of the same name.

handle

Reflex::Handle's "handle" should contain a Perl file handle to watch.

        my $socket = IO::Socket::INET->new(
                LocalAddr => '127.0.0.1',
                LocalPort => 12345,
                Listen    => 5,
                Reuse     => 1,
        );

        my $handle = Reflex::Handle->new( handle => $socket );

However a Reflex::Handle won't emit events without also enabling one or more of "rd", "wr", or "ex".

rd

The "rd" attribute is a Boolean that controls whether Reflex::Handle watches "handle" for readability. Reflex::Handle emits "readable" events when handles contain data ready to be received.

        my $handle = Reflex::Handle->new(
                handle      => $socket,
                rd          => 1,
                on_readable => cb_coderef(\&read_from_it),
        );

It may also be modified at run time to enable or disable readability watching as needed.

        $handle->rd(0);  # Done reading.

wr

The "wr" attribute enables or disables watching for writability on the "handle" attribute. Its semantics and usage are otherwise identical to those of "rd".

Reflex::Handle emits "writable" events when underlying file handles have buffer space for new output. For example, when a socket has successfully written data to the network and has capacity to buffer more data.

ex

The "wr" attribute enables or disables watching for exceptions on the "handle" attribute. Exceptions include errors and out-of-band notifications. Its semantics and usage are otherwise identical to those of "rd".

Reflex::Handle emits "exception" events when "ex" is enabled and some exceptional occurrence happens.

Methods

stop

Reflex::Handle's stop() method disables all watching and clears the file handle held within the object. stop() will be called implicitly if the Reflex::Handle object is destroyed.

If the program is holding no other reference to the watched file, then Perl will close the file after the Reflex::Handle object is stopped.

        sub on_handle_error {
                my $self = shift;
                $self->handle()->stop();
        }

EXAMPLES

Reflex::Listener extends Reflex::Handle to listen for connections on a server socket.

Reflex::Connector extends Reflex::Handle to wait for non-blocking client sockets to fully connect.

Reflex::Stream extends Reflex::Handle to read data when it's ready and write data when it can.

Reflex::Role::UdpPeer extends Reflex::Handle to read UDP packets when they arrive on a socket.

SEE ALSO

Moose::Manual::Concepts

Reflex

"ACKNOWLEDGEMENTS" in Reflex "ASSISTANCE" in Reflex "AUTHORS" in Reflex "BUGS" in Reflex "BUGS" in Reflex "CONTRIBUTORS" in Reflex "COPYRIGHT" in Reflex "LICENSE" in Reflex "TODO" in Reflex

cpanm Reflex

perl -MCPAN -e shell
install Reflex