1Future::IO(3) User Contributed Perl Documentation Future::IO(3)
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 $f = 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.
71 alarm
73 $f = Future::IO->alarm( $epoch )
74 Since version 0.08.
76 Returns a Future that will become done at a fixed point in the future,
78 given as an epoch timestamp (such as returned by "time()"). This value
79 may be fractional.
80 connect
82 $f = Future::IO->connect( $fh, $name )
83 Since version 0.11.
85 Returns a Future that will become done when a "connect()" has succeeded
87 on the given filehandle to the given sockname address.
88 sleep
90 $f = Future::IO->sleep( $secs )
91 Returns a Future that will become done a fixed delay from now, given in
93 seconds. This value may be fractional.
94 sysread
96 $f = Future::IO->sysread( $fh, $length )
97 $bytes = $f->get
99 Returns a Future that will become done when at least one byte can be
101 read from the given filehandle. It may return up to $length bytes. On
102 EOF, the returned future will yield an empty list (or "undef" in scalar
103 context). On any error (other than "EAGAIN" / "EWOULDBLOCK" which are
104 ignored), the future fails with a suitable error message.
105 Note specifically this may perform only a single "sysread()" call, and
107 thus is not guaranteed to actually return the full length.
108 sysread_exactly
110 $f = Future::IO->sysread_exactly( $fh, $length )
111 $bytes = $f->get
113 Since version 0.03.
115 Returns a Future that will become done when exactly the given number of
117 bytes have been read from the given filehandle. It returns exactly
118 $length bytes. On EOF, the returned future will yield an empty list (or
119 "undef" in scalar context), even if fewer bytes have already been
120 obtained. These bytes will be lost. On any error (other than "EAGAIN" /
121 "EWOULDBLOCK" which are ignored), the future fails with a suitable
122 error message.
123 This may make more than one "sysread()" call.
125 syswrite
127 $f = Future::IO->syswrite( $fh, $bytes )
128 $written_len = $f->get
130 Since version 0.04.
132 Returns a Future that will become done when at least one byte has been
134 written to the given filehandle. It may write up to all of the bytes.
135 On any error (other than "EAGAIN" / "EWOULDBLOCK" which are ignored)
136 the future fails with a suitable error message.
137 Note specifically this may perform only a single "syswrite()" call, and
139 thus is not guaranteed to actually return the full length.
140 syswrite_exactly
142 $f = Future::IO->syswrite_exactly( $fh, $bytes )
143 $written_len = $f->get
145 Since version 0.04.
147 Returns a Future that will become done when exactly the given bytes
149 have been written to the given filehandle. On any error (other than
150 "EAGAIN" / "EWOULDBLOCK" which are ignored) the future fails with a
151 suitable error message.
152 This may make more than one "syswrite()" call.
154 waitpid
156 $f = Future::IO->waitpid( $pid )
157 $wstatus = $f->get
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.36.0 2022-07-22 Future::IO(3)