++ed by:

15 PAUSE users
10 non-PAUSE users.

Paul Evans
and 1 contributors


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


 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.


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.


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



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


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

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.


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


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.


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.


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


Paul Evans <leonerd@leonerd.org.uk>