1Future::IO(3pm) User Contributed Perl Documentation Future::IO(3pm)
2
6 "Future::IO" - Future-returning IO methods
7
9 use Future::IO;
10 my $delay = Future::IO->sleep( 5 );
12 # $delay will become done in 5 seconds time
13 my $input = Future::IO->sysread( \*STDIN, 4096 );
15 # $input will yield some input from the STDIN IO handle
16
18 This package provides a few basic methods that behave similarly to the
19 same-named core perl functions relating to IO operations, but yield
20 their results asynchronously via Future instances.
21 This is provided primarily as a decoupling mechanism, to allow modules
23 to be written that perform IO in an asynchronous manner to depend
24 directly on this, while allowing asynchronous event systems to provide
25 an implementation of these operations.
26 Default Implementation
28 If the "override_impl" method is not invoked, a default implementation
29 of these operations is provided. This implementation allows a single
30 queue of "sysread" or "syswrite" calls on a single filehandle only,
31 combined with "sleep" calls. It does not support "waitpid".
32 It is provided for the simple cases where modules only need one
34 filehandle (most likely a single network socket or hardware device
35 handle), allowing such modules to work without needing a better event
36 system.
37 If there are both read/write and "sleep" futures pending, the
39 implementation will use select() to wait for either. This may be
40 problematic on MSWin32, depending on what type of filehandle is
41 involved.
42 For cases where multiple filehandles are required, or for doing more
44 involved IO operations, a real implementation based on an actual event
45 loop should be provided. The following are known to exist; CPAN may
46 provide others:
47 • Future::IO::Impl::Glib
49 • Future::IO::Impl::IOAsync
51 • Future::IO::Impl::UV
53 Unit Testing
55 The replaceable implementation is also useful for writing unit test
56 scripts. If the implementation is set to an instance of some sort of
57 test fixture or mocking object, a unit test can check that the
58 appropriate IO operations happen as part of the test.
59 A testing module which does this is provided by Test::Future::IO.
61
63 accept
64 $socketfh = await Future::IO->accept( $fh );
65 Since version 0.11.
67 Returns a Future that will become done when a new connection has been
69 accepted on the given filehandle, which should represent a listen-mode
70 socket. The returned future will yield the newly-accepted client
71 socket filehandle.
72 alarm
74 await Future::IO->alarm( $epoch );
75 Since version 0.08.
77 Returns a Future that will become done at a fixed point in the future,
79 given as an epoch timestamp (such as returned by time()). This value
80 may be fractional.
81 connect
83 await Future::IO->connect( $fh, $name );
84 Since version 0.11.
86 Returns a Future that will become done when a connect() has succeeded
88 on the given filehandle to the given sockname address.
89 sleep
91 await Future::IO->sleep( $secs );
92 Returns a Future that will become done a fixed delay from now, given in
94 seconds. This value may be fractional.
95 sysread
97 $bytes = await Future::IO->sysread( $fh, $length );
98 Returns a Future that will become done when at least one byte can be
100 read from the given filehandle. It may return up to $length bytes. On
101 EOF, the returned future will yield an empty list (or "undef" in scalar
102 context). On any error (other than "EAGAIN" / "EWOULDBLOCK" which are
103 ignored), the future fails with a suitable error message.
104 Note specifically this may perform only a single sysread() call, and
106 thus is not guaranteed to actually return the full length.
107 sysread_exactly
109 $bytes = await Future::IO->sysread_exactly( $fh, $length );
110 Since version 0.03.
112 Returns a Future that will become done when exactly the given number of
114 bytes have been read from the given filehandle. It returns exactly
115 $length bytes. On EOF, the returned future will yield an empty list (or
116 "undef" in scalar context), even if fewer bytes have already been
117 obtained. These bytes will be lost. On any error (other than "EAGAIN" /
118 "EWOULDBLOCK" which are ignored), the future fails with a suitable
119 error message.
120 This may make more than one sysread() call.
122 sysread_until_eof
124 $f = Future::IO->sysread_until_eof( $fh )
125 Since version 0.12.
127 Returns a Future that will become done when the given filehandle
129 reaches the EOF condition. The returned future will yield all of the
130 bytes read up until that point.
131 syswrite
133 $written_len = await Future::IO->syswrite( $fh, $bytes );
134 Since version 0.04.
136 Returns a Future that will become done when at least one byte has been
138 written to the given filehandle. It may write up to all of the bytes.
139 On any error (other than "EAGAIN" / "EWOULDBLOCK" which are ignored)
140 the future fails with a suitable error message.
141 Note specifically this may perform only a single syswrite() call, and
143 thus is not guaranteed to actually return the full length.
144 syswrite_exactly
146 $written_len = await Future::IO->syswrite_exactly( $fh, $bytes );
147 Since version 0.04.
149 Returns a Future that will become done when exactly the given bytes
151 have been written to the given filehandle. On any error (other than
152 "EAGAIN" / "EWOULDBLOCK" which are ignored) the future fails with a
153 suitable error message.
154 This may make more than one syswrite() call.
156 waitpid
158 $wstatus = await Future::IO->waitpid( $pid );
159 Since version 0.09.
161 Returns a Future that will become done when the given child process
163 terminates. The future will yield the wait status of the child process.
164 This can be inspected by the usual bitshifting operations as per $?:
165 if( my $termsig = ($wstatus & 0x7f) ) {
167 say "Terminated with signal $termsig";
168 }
169 else {
170 my $exitcode = ($wstatus >> 8);
171 say "Terminated with exit code $exitcode";
172 }
173 override_impl
175 Future::IO->override_impl( $impl );
176 Sets a new implementation for "Future::IO", replacing the minimal
178 default internal implementation. This can either be a package name or
179 an object instance reference, but must provide the methods named above.
180 This method is intended to be called by event loops and other similar
182 places, to provide a better integration. Another way, which doesn't
183 involve directly depending on "Future::IO" or loading it, is to use the
184 $IMPL variable; see below.
185 Can only be called once, and only if the default implementation is not
187 in use, therefore a module that wishes to override this ought to invoke
188 it as soon as possible on program startup, before any of the main
189 "Future::IO" methods may have been called.
190 HAVE_MULTIPLE_FILEHANDLES
192 $has = Future::IO->HAVE_MULTIPLE_FILEHANDLES;
193 Since version 0.11.
195 Returns true if the underlying IO implementation actually supports
197 multiple filehandles. Most real support modules will return true here,
198 but this returns false for the internal minimal implementation.
199 await
201 $f = $f->await;
202 Since version 0.07.
204 Blocks until this future is ready (either by success or failure). Does
206 not throw an exception if failed.
207
209 Since version 0.02.
210 As an alternative to setting an implementation by using override_impl,
212 a package variable is also available that allows modules such as event
213 systems to opportunistically provide an implementation without needing
214 to depend on the module, or loading it "require". Simply directly set
215 that package variable to the name of an implementing package or an
216 object instance.
217 Additionally, implementors may use a name within the
219 "Future::IO::Impl::" namespace, suffixed by the name of their event
220 system.
221 For example, something like the following code arrangement is
223 recommended.
224 package Future::IO::Impl::BananaLoop;
226 {
228 no warnings 'once';
229 ( $Future::IO::IMPL //= __PACKAGE__ ) eq __PACKAGE__ or
230 warn "Unable to set Future::IO implementation to " . __PACKAGE__ .
231 " as it is already $Future::IO::IMPL\n";
232 }
233 sub sleep
235 {
236 ...
237 }
238 sub sysread
240 {
241 ...
242 }
243 sub syswrite
245 {
246 ...
247 }
248 sub waitpid
250 {
251 ...
252 }
253 Optionally, you can also implement "sysread_exactly" and
255 "syswrite_exactly":
256 sub sysread_exactly
258 {
259 ...
260 }
261 sub syswrite_exactly
263 {
264 ...
265 }
266 If not, they will be emulated by "Future::IO" itself, making multiple
268 calls to the non-"_exactly" versions.
269
271 Paul Evans <leonerd@leonerd.org.uk>
272perl v5.38.0 2023-07-20 Future::IO(3pm)