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

FreeBSD Manual Pages


home | help
Handle(3)	      User Contributed Perl Documentation	     Handle(3)

       Coro::Handle - non-blocking I/O with a blocking interface.

	use Coro::Handle;

       This module is an AnyEvent user,	you need to make sure that you use and
       run a supported event loop.

       This module implements IO-handles in a coroutine-compatible way,	that
       is, other coroutines can	run while reads	or writes block	on the handle.

       It does so by using AnyEvent to wait for	readable/writable data,
       allowing	other coroutines to run	while one coroutine waits for I/O.

       Coro::Handle does NOT inherit from IO::Handle but uses tied objects.

       If at all possible, you should always prefer method calls on the	handle
       object over invoking tied methods, i.e.:

	  $fh->print ($str);	     # NOT print $fh $str;
	  my $line = $fh->readline;  # NOT my $line = <$fh>;

       The reason is that perl recurses	within the interpreter when invoking
       tie magic, forcing the (temporary) allocation of	a (big)	stack. If you
       have lots of socket connections and they	happen to wait in e.g. <$fh>,
       then they would all have	a costly C coroutine associated	with them.

       $fh = new_from_fh Coro::Handle $fhandle [, arg => value...]
	   Create a new	non-blocking io-handle using the given perl-
	   filehandle. Returns "undef" if no filehandle	is given. The only
	   other supported argument is "timeout", which	sets a timeout for
	   each	operation.

       $fh = unblock $fh
	   This	is a convenience function that just calls "new_from_fh"	on the
	   given filehandle. Use it to replace a normal	perl filehandle	by a
	   non-(coroutine-)blocking equivalent.

       $fh->writable, $fh->readable
	   Wait	until the filehandle is	readable or writable (and return true)
	   or until an error condition happens (and return false).

       $fh->readline ([$terminator])
	   Similar to the builtin of the same name, but	allows you to specify
	   the input record separator in a coroutine-safe manner (i.e. not
	   using a global variable). Paragraph mode is not supported, use
	   "\n\n" to achieve the same effect.

       $fh->autoflush ([...])
	   Always returns true,	arguments are being ignored (exists for
	   compatibility only).	Might change in	the future.

       $fh->fileno, $fh->close,	$fh->read, $fh->sysread, $fh->syswrite,
       $fh->print, $fh->printf
	   Work	like their function equivalents	(except	read, which works like
	   sysread. You	should not use the read	function with Coro::Handle's,
	   it will work	but it's not efficient).

       connect,	listen,	bind, getsockopt, setsockopt, send, recv, peername,
       sockname, shutdown, peerport, peerhost
	   Do the same thing as	the perl builtins or IO::Socket	methods	(but
	   return true on EINPROGRESS).	Remember that these must be method

       peeraddr, peerhost, peerport
	   Return the peer host	(as numericla IP address) and peer port	(as

       ($fh, $peername)	= $listen_fh->accept
	   In scalar context, returns the newly	accepted socket	(or undef) and
	   in list context return the ($fh, $peername) pair (or	nothing).

       $fh->timeout ([...])
	   The optional	argument sets the new timeout (in seconds) for this
	   handle. Returns the current (new) value.

	   0 is	a valid	timeout, use "undef" to	disable	the timeout.

	   Returns the "real" (non-blocking) filehandle. Use this if you want
	   to do operations on the file	handle you cannot do using the
	   Coro::Handle	interface.

	   Returns the current contents	of the read buffer (this is an lvalue,
	   so you can change the read buffer if	you like).

	   You can use this function to	implement your own optimized reader
	   when	neither	readline nor sysread are viable	candidates, like this:

	     # first get the _real_ non-blocking filehandle
	     # and fetch a reference to	the read buffer
	     my	$nb_fh = $fh->fh;
	     my	$buf = \$fh->rbuf;

	     while () {
		# now use buffer contents, modifying
		# if necessary to reflect the removed data

		last if	$$buf ne ""; # we have leftover	data

		# read another buffer full of data
		$fh->readable or die "end of file";
		sysread	$nb_fh,	$$buf, 8192;

	- Perl's IO-Handle model is THE	bug.

	  Marc A. Lehmann <>

perl v5.32.0			  2020-07-29			     Handle(3)


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

home | help