Skip site navigation (1)Skip section navigation (2)

FreeBSD Manual Pages


home | help
IO::Async::Handle(3)  User Contributed Perl Documentation IO::Async::Handle(3)

       "IO::Async::Handle" - event callbacks for a non-blocking	file

       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.

       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.

       The following events are	invoked, either	using subclass methods or CODE
       references in parameters:

       Invoked when the	read handle becomes ready for reading.

       Invoked when the	write handle becomes ready for writing.

       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.

       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.

       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 )


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



       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.


       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

	  $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

       $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

   bind	(1 argument)
	  $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.

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

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

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

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

       Paul Evans <>

perl v5.32.0			  2020-08-30		  IO::Async::Handle(3)


Want to link to this manual page? Use this URL:

home | help