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. For
non-stream sockets, see IO::Async::Socket.
DESCRIPTION¶
This subclass of IO::Async::Notifier allows non-blocking IO on filehandles. It
provides event handlers for when the filehandle is read- or write-ready.
EVENTS¶
The following events are invoked, either using subclass methods or CODE
references in parameters:
on_read_ready¶
Invoked when the read handle becomes ready for reading.
on_write_ready¶
Invoked when the write handle becomes ready for writing.
on_closed¶
Optional. Invoked when the handle becomes closed.
This handler is invoked before the filehandles are closed and the Handle removed
from its containing Loop. The "loop" will still return the
containing Loop object.
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
- on_closed => CODE
- CODE references for event handlers.
- want_readready => BOOL
- want_writeready => BOOL
- If present, enable or disable read- or write-ready
notification as per the "want_readready" and
"want_writeready" methods.
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, or
by "configure". This may be useful when constructing an object to
represent a network connection, before the
connect(2) 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->close_read¶
$handle->close_write¶
Closes the underlying read or write handle, and deconfigures it from the object.
Neither of these methods will invoke the "on_closed" event, nor
remove the object from the Loop if there is still one open handle in the
object. Only when both handles are closed, will "on_closed" be
fired, and the object removed.
$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>