/ 
IO-Async-0.01
River stage three • 151 direct dependents • 200 total dependents
/ IO::Async::Notifier

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,

   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 read_ready or 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.

Base Class

If a subclass is built, then it can override the read_ready or 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.

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.

read_ready => CODE
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 read_ready callback reference is passed, or that the object is actually a subclass that overrides the read_ready method. It is optional whether either is true for 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.

SEE ALSO

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

AUTHOR

Paul Evans <leonerd@leonerd.org.uk>