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

THE $IMPL VARIABLE

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

AUTHOR

189       Paul Evans <leonerd@leonerd.org.uk>
190
191
192
193perl v5.30.0                      2019-07-26                     Future::IO(3)