NAME

IO::Async::Notifier - a class which implements event callbacks for a non-blocking file descriptor

SYNOPSIS

 use IO::Socket::INET;
 use IO::Async::Notifier;

 my $socket = IO::Socket::INET->new( LocalPort => 1234, Listen => 1 );

 my $notifier = IO::Async::Notifer->new(
    handle => $socket,

    on_read_ready  => sub {
       my $new_client = $socket->accept(); 
       ...
    },
 );

 my $set = IO::Async::Set::...
 $set->add( $notifier );

For most other uses with sockets, pipes or other filehandles that carry a byte stream, the IO::Async::Buffer class is likely to be more suitable.

DESCRIPTION

This module provides a base class for implementing non-blocking IO on file descriptors. The object provides ways to integrate with existing asynchronous IO handling code, by way of the various IO::Async::Set::* collection classes.

This object may be used in one of two ways; with callback functions, or as a base class.

Callbacks

If the on_read_ready or on_write_ready keys are supplied in the constructor, they should contain CODE references to callback functions to be called when the underlying IO handle becomes readable or writable:

 $on_read_ready->( $self )

 $on_write_ready->( $self )

Optionally, an on_closed key can also be specified, which will be called when the handle_closed method is invoked. This is intended for subclasses.

 $on_closed->( $self )

Base Class

If a subclass is built, then it can override the on_read_ready or on_write_ready methods of the base to perform its work. In this case, it should not call the SUPER:: versions of those methods.

 $self->on_read_ready()

 $self->on_write_ready()

If either of the readyness methods calls the handle_closed() method, then the handle is internally marked as closed within the object.

CONSTRUCTOR

$notifier = IO::Async::Notifier->new( %params )

This function returns a new instance of a IO::Async::Notifier object. The %params hash takes the following keys:

read_handle => IO

write_handle => IO

The reading and writing IO handles. Each must implement the fileno method. read_handle must be defined, write_handle is allowed to be undef. Primarily used for passing STDIN / STDOUT; see the SYNOPSIS section of IO::Async::Buffer for an example.

handle => IO

The IO handle for both reading and writing; instead of passing each separately as above. Must implement fileno method in way that IO::Handle does.

on_read_ready => CODE

on_write_ready => CODE

CODE references to handlers for when the handle becomes read-ready or write-ready. If these are not supplied, subclass methods will be called instead.

on_closed => CODE

CODE reference to the handler for when the handle becomes closed.

It is required that either a on_read_ready callback reference is passed, or that the object is actually a subclass that overrides the on_read_ready method. It is optional whether either is true for on_write_ready; if neither is supplied then write-readiness notifications will be ignored.

METHODS

$handle = $notifier->read_handle

$handle = $notifier->write_handle

These accessors return the underlying IO handles.

$fileno = $notifier->read_fileno

$fileno = $notifier->write_fileno

These accessors return the file descriptor numbers of the underlying IO handles.

$value = $notifier->want_writeready

$oldvalue = $notifier->want_writeready( $newvalue )

This is the accessor for the want_writeready property, which defines whether the object will register interest in the write-ready bitvector in a select() call, or whether to register the POLLOUT bit in a IO::Poll mask.

$notifier->handle_closed()

This method marks that the handle has been closed. After this has been called, the object will no longer mark any bits in the pre_select() call, nor respond to any set bits in the post_select() call.

CHILD NOTIFIERS

During the execution of a program, it may be the case that certain IO handles cause other handles to be created; for example, new sockets that have been accept()ed from a listening socket. To facilitate these, a notifier may contain child notifier objects, that are automatically added to or removed from the IO::Async::Set that manages their parent.

$parent = $notifier->parent()

Returns the parent of the notifier, or undef if does not have one.

@children = $notifier->children()

Returns a list of the child notifiers contained within this one.

$notifier->add_child( $child )

Adds a child notifier. This notifier will be added to the containing set, if the parent has one. Only a notifier that does not currently have a parent and is not currently a member of any set may be added as a child. If the child itself has grandchildren, these will be recursively added to the containing set.

$notifier->remove_child( $child )

Removes a child notifier. The child will be removed from the containing set, if the parent has one. If the child itself has grandchildren, these will be recurively removed from the set.

SEE ALSO

• IO::Handle - Supply object methods for I/O handles

AUTHOR

Paul Evans <leonerd@leonerd.org.uk>

cpanm IO::Async::Set

perl -MCPAN -e shell
install IO::Async::Set