IO::Async::Handle(3) User Contributed Perl Documentation IO::Async::Handle(3)NAME
"IO::Async::Handle" - 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::Handle;
use IO::Async::Loop;
my $loop = IO::Async::Loop->new();
my $socket = IO::Socket::INET->new( LocalPort => 1234, Listen => 1 );
my $handle = IO::Async::Handle->new(
handle => $socket,
on_read_ready => sub {
my $new_client = $socket->accept();
...
},
);
$loop->add( $handle );
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 class of "IO::Async::Notifier" 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 )
This callback is invoked before the filehandles are closed and the
Handle removed from its containing Loop. The "get_loop" will still
return the containing Loop object.
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()
Optionally, an "on_closed" method may be provided, which will be
called when the "close" method is invoked.
$self->on_closed()
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.
PARAMETERS
The following named parameters may be passed to "new" or "configure":
read_handle => IO
write_handle => IO
The reading and writing IO handles. Each must implement the
"fileno" method. 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 Handle. 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
$handle->set_handles( %params )
Sets new reading or writing filehandles. Equivalent to calling the
"configure" method with the same parameters.
$handle->set_handle( $fh )
Shortcut for
$handle->configure( handle => $fh )
$handle->close
This method calls "close" on the underlying IO handles. This method
will then remove the handle from its containing loop.
$handle = $handle->read_handle
$handle = $handle->write_handle
These accessors return the underlying IO handles.
$fileno = $handle->read_fileno
$fileno = $handle->write_fileno
These accessors return the file descriptor numbers of the underlying IO
handles.
$value = $handle->want_readready
$oldvalue = $handle->want_readready( $newvalue )
$value = $handle->want_writeready
$oldvalue = $handle->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.
SEE ALSO
ยท IO::Handle - Supply object methods for I/O handles
AUTHOR
Paul Evans <leonerd@leonerd.org.uk>
perl v5.14.2 2010-06-09 IO::Async::Handle(3)
