IO::Async::Handle man page on Alpinelinux

Man page or keyword search:  
man Server   18016 pages
apropos Keyword Search (all sections)
Output format
Alpinelinux logo
[printable version]

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

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

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

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

   $future = $handle->connect( %args )
       A convenient wrapper for calling the "connect" method on the underlying
       IO::Async::Loop object.

SEE ALSO
       ยท   IO::Handle - Supply object methods for I/O handles

AUTHOR
       Paul Evans <leonerd@leonerd.org.uk>

perl v5.18.2			  2014-05-14		  IO::Async::Handle(3)
[top]

List of man pages available for Alpinelinux

Copyright (c) for man pages and the logo by the respective OS vendor.

For those who want to learn more, the polarhome community provides shell access and support.

[legal] [privacy] [GNU] [policy] [cookies] [netiquette] [sponsors] [FAQ]
Tweet
Polarhome, production since 1999.
Member of Polarhome portal.
Based on Fawad Halim's script.
....................................................................
Vote for polarhome
Free Shell Accounts :: the biggest list on the net