1Future::IO(3)         User Contributed Perl Documentation        Future::IO(3)
2
3
4

NAME

6       "Future::IO" - Future-returning IO methods
7

SYNOPSIS

9          use Future::IO;
10
11          my $delay = Future::IO->sleep( 5 );
12          # $delay will become done in 5 seconds time
13
14          my $input = Future::IO->sysread( \*STDIN, 4096 );
15          # $input will yield some input from the STDIN IO handle
16

DESCRIPTION

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
22       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
27   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 is provided for the simple cases where
32       modules only need one filehandle (most likely a single network socket
33       or hardware device handle), allowing such modules to work without
34       needing a better event system.
35
36       If there are both read/write and "sleep" futures pending, the
37       implementation will use "select()" to wait for either. This may be
38       problematic on MSWin32, depending on what type of filehandle is
39       involved.
40
41       For cases where multiple filehandles are required, or for doing more
42       involved IO operations, a real implementation based on an actual event
43       loop should be provided.
44
45   Unit Testing
46       The replaceable implementation is also useful for writing unit test
47       scripts.  If the implementation is set to an instance of some sort of
48       test fixture or mocking object, a unit test can check that the
49       appropriate IO operations happen as part of the test.
50

METHODS

52   alarm
53          $f = Future::IO->alarm( $epoch )
54
55       Since version 0.08.
56
57       Returns a Future that will become at a fixed point in the future, given
58       as an epoch timestamp (such as returned by "time()"). This value may be
59       fractional.
60
61   sleep
62          $f = Future::IO->sleep( $secs )
63
64       Returns a Future that will become done a fixed delay from now, given in
65       seconds. This value may be fractional.
66
67   sysread
68          $f = Future::IO->sysread( $fh, $length )
69             $bytes = $f->get
70
71       Returns a Future that will become done when at least one byte can be
72       read from the given filehandle. It may return up to $length bytes. On
73       EOF, the returned future will yield an empty list (or "undef" in scalar
74       context). On any error (other than "EAGAIN" / "EWOULDBLOCK" which are
75       ignored), the future fails with a suitable error message.
76
77       Note specifically this may perform only a single "sysread()" call, and
78       thus is not guaranteed to actually return the full length.
79
80   sysread_exactly
81          $f = Future::IO->sysread_exactly( $fh, $length )
82             $bytes = $f->get
83
84       Since version 0.03.
85
86       Returns a Future that will become done when exactly the given number of
87       bytes have been read from the given filehandle. It returns exactly
88       $length bytes. On EOF, the returned future will yield an empty list (or
89       "undef" in scalar context), even if fewer bytes have already been
90       obtained. These bytes will be lost. On any error (other than "EAGAIN" /
91       "EWOULDBLOCK" which are ignored), the future fails with a suitable
92       error message.
93
94       This may make more than one "sysread()" call.
95
96   syswrite
97          $f = Future::IO->syswrite( $fh, $bytes )
98             $written_len = $f->get
99
100       Since version 0.04.
101
102       Returns a Future that will become done when at least one byte has been
103       written to the given filehandle. It may write up to all of the bytes.
104       On any error (other than "EAGAIN" / "EWOULDBLOCK" which are ignored)
105       the future fails with a suitable error message.
106
107       Note specifically this may perform only a single "syswrite()" call, and
108       thus is not guaranteed to actually return the full length.
109
110   syswrite_exactly
111          $f = Future::IO->syswrite_exactly( $fh, $bytes )
112             $written_len = $f->get;
113
114       Since version 0.04.
115
116       Returns a Future that will become done when exactly the given bytes
117       have been written to the given filehandle. On any error (other than
118       "EAGAIN" / "EWOULDBLOCK" which are ignored) the future fails with a
119       suitable error message.
120
121       This may make more than one "syswrite()" call.
122
123   override_impl
124          Future::IO->override_impl( $impl )
125
126       Sets a new implementation for "Future::IO", replacing the minimal
127       default internal implementation. This can either be a package name or
128       an object instance reference, but must provide the methods named above.
129
130       This method is intended to be called by event loops and other similar
131       places, to provide a better integration. Another way, which doesn't
132       involve directly depending on "Future::IO" or loading it, is to use the
133       $IMPL variable; see below.
134
135       Can only be called once, and only if the default implementation is not
136       in use, therefore a module that wishes to override this ought to invoke
137       it as soon as possible on program startup, before any of the main
138       "Future::IO" methods may have been called.
139
140   await
141          $f = $f->await
142
143       Since version 0.07.
144
145       Blocks until this future is ready (either by success or failure). Does
146       not throw an exception if failed.
147

THE $IMPL VARIABLE

149       Since version 0.02.
150
151       As an alternative to setting an implementation by using override_impl,
152       a package variable is also available that allows modules such as event
153       systems to opportunistically provide an implementation without needing
154       to depend on the module, or loading it "require". Simply directly set
155       that package variable to the name of an implementing package or an
156       object instance.
157
158       Additionally, implementors may use a name within the
159       "Future::IO::Impl::" namespace, suffixed by the name of their event
160       system.
161
162       For example, something like the following code arrangement is
163       recommended.
164
165          package Future::IO::Impl::BananaLoop;
166
167          {
168             no warnings 'once';
169             ( $Future::IO::IMPL //= __PACKAGE__ ) eq __PACKAGE__ or
170                warn "Unable to set Future::IO implementation to " . __PACKAGE__ .
171                   " as it is already $Future::IO::IMPL\n";
172          }
173
174          sub sleep
175          {
176             ...
177          }
178
179          sub sysread
180          {
181             ...
182          }
183
184          sub syswrite
185          {
186             ...
187          }
188
189       Optionally, you can also implement "sysread_exactly" and
190       "syswrite_exactly":
191
192          sub sysread_exactly
193          {
194             ...
195          }
196
197          sub syswrite_exactly
198          {
199             ...
200          }
201
202       If not, they will be emulated by "Future::IO" itself, making multiple
203       calls to the non-"_exactly" versions.
204

AUTHOR

206       Paul Evans <leonerd@leonerd.org.uk>
207
208
209
210perl v5.34.0                      2021-07-22                     Future::IO(3)