1Handle(3)             User Contributed Perl Documentation            Handle(3)
2
3
4

NAME

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

SYNOPSIS

9        use Coro::Handle;
10

DESCRIPTION

12       This module is an AnyEvent user, you need to make sure that you use and
13       run a supported event loop.
14
15       This module implements IO-handles in a coroutine-compatible way, that
16       is, other coroutines can run while reads or writes block on the handle.
17
18       It does so by using AnyEvent to wait for readable/writable data,
19       allowing other coroutines to run while one coroutine waits for I/O.
20
21       Coro::Handle does NOT inherit from IO::Handle but uses tied objects.
22
23       If at all possible, you should always prefer method calls on the handle
24       object over invoking tied methods, i.e.:
25
26          $fh->print ($str);         # NOT print $fh $str;
27          my $line = $fh->readline;  # NOT my $line = <$fh>;
28
29       The reason is that perl recurses within the interpreter when invoking
30       tie magic, forcing the (temporary) allocation of a (big) stack. If you
31       have lots of socket connections and they happen to wait in e.g. <$fh>,
32       then they would all have a costly C coroutine associated with them.
33
34       $fh = new_from_fh Coro::Handle $fhandle [, arg => value...]
35           Create a new non-blocking io-handle using the given perl-
36           filehandle. Returns "undef" if no filehandle is given. The only
37           other supported argument is "timeout", which sets a timeout for
38           each operation.
39
40       $fh = unblock $fh
41           This is a convenience function that just calls "new_from_fh" on the
42           given filehandle. Use it to replace a normal perl filehandle by a
43           non-(coroutine-)blocking equivalent.
44
45       $fh->writable, $fh->readable
46           Wait until the filehandle is readable or writable (and return true)
47           or until an error condition happens (and return false).
48
49       $fh->readline ([$terminator])
50           Similar to the builtin of the same name, but allows you to specify
51           the input record separator in a coroutine-safe manner (i.e. not
52           using a global variable). Paragraph mode is not supported, use
53           "\n\n" to achieve the same effect.
54
55       $fh->autoflush ([...])
56           Always returns true, arguments are being ignored (exists for
57           compatibility only). Might change in the future.
58
59       $fh->fileno, $fh->close, $fh->read, $fh->sysread, $fh->syswrite,
60       $fh->print, $fh->printf
61           Work like their function equivalents (except read, which works like
62           sysread. You should not use the read function with Coro::Handle's,
63           it will work but it's not efficient).
64
65       connect, listen, bind, getsockopt, setsockopt, send, recv, peername,
66       sockname, shutdown, peerport, peerhost
67           Do the same thing as the perl builtins or IO::Socket methods (but
68           return true on EINPROGRESS). Remember that these must be method
69           calls.
70
71       peeraddr, peerhost, peerport
72           Return the peer host (as numericla IP address) and peer port (as
73           integer).
74
75       ($fh, $peername) = $listen_fh->accept
76           In scalar context, returns the newly accepted socket (or undef) and
77           in list context return the ($fh, $peername) pair (or nothing).
78
79       $fh->timeout ([...])
80           The optional argument sets the new timeout (in seconds) for this
81           handle. Returns the current (new) value.
82
83           0 is a valid timeout, use "undef" to disable the timeout.
84
85       $fh->fh
86           Returns the "real" (non-blocking) filehandle. Use this if you want
87           to do operations on the file handle you cannot do using the
88           Coro::Handle interface.
89
90       $fh->rbuf
91           Returns the current contents of the read buffer (this is an lvalue,
92           so you can change the read buffer if you like).
93
94           You can use this function to implement your own optimized reader
95           when neither readline nor sysread are viable candidates, like this:
96
97             # first get the _real_ non-blocking filehandle
98             # and fetch a reference to the read buffer
99             my $nb_fh = $fh->fh;
100             my $buf = \$fh->rbuf;
101
102             while () {
103                # now use buffer contents, modifying
104                # if necessary to reflect the removed data
105
106                last if $$buf ne ""; # we have leftover data
107
108                # read another buffer full of data
109                $fh->readable or die "end of file";
110                sysread $nb_fh, $$buf, 8192;
111             }
112

BUGS

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

AUTHOR/SUPPORT/CONTACT

117          Marc A. Lehmann <schmorp@schmorp.de>
118          http://software.schmorp.de/pkg/Coro.html
119
120
121
122perl v5.34.0                      2022-01-21                         Handle(3)
Impressum