NAME

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

SYNOPSIS

This class is likely not to be used directly, because subclasses of it exist to handle more specific cases. Here is an example of how it would be used to watch a listening socket for new connections. In real code, it is likely that the Loop->listen() method would be used instead.

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

 use IO::Async::Loop;
 my $loop = IO::Async::Loop->new();

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

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

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

 $loop->add( $notifier );

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

DESCRIPTION

This module provides a base class for implementing non-blocking IO on file descriptors. The object interacts with the actual OS by being part of the IO::Async::Loop object it has been added to.

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 close method is invoked.

 $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 close() method, then the handle is internally marked as closed within the object and will be removed from its containing loop, if it is within one.

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. At most one of read_handle or write_handle is allowed to be undef. Primarily used for passing STDIN / STDOUT; see the SYNOPSIS section of IO::Async::Stream 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 callbacks 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 callback for when the handle becomes closed.

It is required that a matching on_read_ready or on_write_ready are available for any handle that is provided; either passed as a callback CODE reference or as an overridden the method. I.e. if only a read_handle is given, then on_write_ready can be absent. If handle is used as a shortcut, then both read and write-ready callbacks or methods are required.

If no IO handles are provided at construction time, the object is still created but will not yet be fully-functional as a Notifier. IO handles can be assigned later using the set_handle or set_handles methods. This may be useful when constructing an object to represent a network connection, before the connect() has actually been performed yet.

METHODS

$notifier->set_handles( %params )

This method stores new reading or writing handles in the object, as if they had been passed as the read_handle or write_handle arguments to the constructor. The %params hash takes the following keys:

read_handle => IO

A new IO handle for reading, or undef to remove the old one.

write_handle => IO

A new IO handle for writing, or undef to remove the old one.

$notifier->set_handle( $handle )

Shortcut for

 $notifier->set_handles( read_handle => $handle, write_handle => $handle )

$notifier->close

This method calls close on the underlying IO handles. This method will then remove the notifier from its containing loop.

$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.

$notifier->get_loop

This accessor returns the IO::Async::Loop object to which this notifier belongs.

$value = $notifier->want_readready

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

$value = $notifier->want_writeready

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

These are the accessor for the want_readready and want_writeready properties, which define whether the object is interested in knowing about read- or write-readiness on the underlying file handle.

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::Loop 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 loop, if the parent has one. Only a notifier that does not currently have a parent and is not currently a member of any loop may be added as a child. If the child itself has grandchildren, these will be recursively added to the containing loop.

$notifier->remove_child( $child )

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

SEE ALSO

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

AUTHOR

Paul Evans <leonerd@leonerd.org.uk>

cpanm IO::Async

perl -MCPAN -e shell
install IO::Async