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

THE $IMPL VARIABLE

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

AUTHOR

197       Paul Evans <leonerd@leonerd.org.uk>
198
199
200
201perl v5.32.0                      2020-07-28                     Future::IO(3)