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.

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.

set_handle¶

   $handle->set_handles( %params );

Sets new reading or writing filehandles. Equivalent to calling the "configure" method with the same parameters.

set_handle¶

   $handle->set_handle( $fh );

Shortcut for

   $handle->configure( handle => $fh );

close¶

   $handle->close;

This method calls "close" on the underlying IO handles. This method will then remove the handle from its containing loop.

close_read¶

close_write¶

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

new_close_future¶

   await $handle->new_close_future;

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.

read_handle¶

write_handle¶

   $handle = $handle->read_handle;
   $handle = $handle->write_handle;

These accessors return the underlying IO handles.

read_fileno¶

write_fileno¶

   $fileno = $handle->read_fileno;
   $fileno = $handle->write_fileno;

These accessors return the file descriptor numbers of the underlying IO handles.

want_readready¶

want_writeready¶

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

socket¶

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

bind¶

   $handle = await $handle->bind( %args );

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

bind (1 argument)¶

   $handle = await $handle->bind( $ai );

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.

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

The returned future returns the handle object itself for convenience.

connect¶

   $handle = await $handle->connect( %args );

A convenient wrapper for calling the "connect" method on the underlying IO::Async::Loop object.