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.

read_fileno => INT

write_fileno => INT

File descriptor numbers for reading and writing. If these are given as an alternative to read_handle or write_handle then a new IO::Handle instance will be constructed around each.

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

The following methods documented with a trailing call to ->get return Future instances.

$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->new_close_future->get

Returns a new IO::Async::Future object which will become done when the handle is closed. Cancelling the $future will remove this notification ability but will not otherwise affect the $handle.

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

$handle->socket( $ai )

Convenient shortcut to creating a socket handle, as given by an addrinfo structure, and setting it as the read and write handle for the object.

$ai may be either a HASH or ARRAY reference of the same form as given to IO::Async::OS's extract_addrinfo method.

This method returns nothing if it succeeds, or throws an exception if it fails.

$handle = $handle->bind( %args )->get

Performs a getaddrinfo resolver operation with the passive flag set, and then attempts to bind a socket handle of any of the return values.

$handle = $handle->bind( $ai )->get

When invoked with a single argument, this method is a convenient shortcut to creating a socket handle and bind()ing it to the address as given by an addrinfo structure, and setting it as the read and write handle for the object.