.\" Automatically generated by Pod::Man 4.14 (Pod::Simple 3.43) .\" .\" Standard preamble: .\" ======================================================================== .de Sp \" Vertical space (when we can't use .PP) .if t .sp .5v .if n .sp .. .de Vb \" Begin verbatim text .ft CW .nf .ne \\$1 .. .de Ve \" End verbatim text .ft R .fi .. .\" Set up some character translations and predefined strings. \*(-- will .\" give an unbreakable dash, \*(PI will give pi, \*(L" will give a left .\" double quote, and \*(R" will give a right double quote. \*(C+ will .\" give a nicer C++. Capital omega is used to do unbreakable dashes and .\" therefore won't be available. \*(C` and \*(C' expand to `' in nroff, .\" nothing in troff, for use with C<>. .tr \(*W- .ds C+ C\v'-.1v'\h'-1p'\s-2+\h'-1p'+\s0\v'.1v'\h'-1p' .ie n \{\ . ds -- \(*W- . ds PI pi . if (\n(.H=4u)&(1m=24u) .ds -- \(*W\h'-12u'\(*W\h'-12u'-\" diablo 10 pitch . if (\n(.H=4u)&(1m=20u) .ds -- \(*W\h'-12u'\(*W\h'-8u'-\" diablo 12 pitch . ds L" "" . ds R" "" . ds C` "" . ds C' "" 'br\} .el\{\ . ds -- \|\(em\| . ds PI \(*p . ds L" `` . ds R" '' . ds C` . ds C' 'br\} .\" .\" Escape single quotes in literal strings from groff's Unicode transform. .ie \n(.g .ds Aq \(aq .el .ds Aq ' .\" .\" If the F register is >0, we'll generate index entries on stderr for .\" titles (.TH), headers (.SH), subsections (.SS), items (.Ip), and index .\" entries marked with X<> in POD. Of course, you'll have to process the .\" output yourself in some meaningful fashion. .\" .\" Avoid warning from groff about undefined register 'F'. .de IX .. .nr rF 0 .if \n(.g .if rF .nr rF 1 .if (\n(rF:(\n(.g==0)) \{\ . if \nF \{\ . de IX . tm Index:\\$1\t\\n%\t"\\$2" .. . if !\nF==2 \{\ . nr % 0 . nr F 2 . \} . \} .\} .rr rF .\" .\" Accent mark definitions (@(#)ms.acc 1.5 88/02/08 SMI; from UCB 4.2). .\" Fear. Run. Save yourself. No user-serviceable parts. . \" fudge factors for nroff and troff .if n \{\ . ds #H 0 . ds #V .8m . ds #F .3m . ds #[ \f1 . ds #] \fP .\} .if t \{\ . ds #H ((1u-(\\\\n(.fu%2u))*.13m) . ds #V .6m . ds #F 0 . ds #[ \& . ds #] \& .\} . \" simple accents for nroff and troff .if n \{\ . ds ' \& . ds ` \& . ds ^ \& . ds , \& . ds ~ ~ . ds / .\} .if t \{\ . ds ' \\k:\h'-(\\n(.wu*8/10-\*(#H)'\'\h"|\\n:u" . ds ` \\k:\h'-(\\n(.wu*8/10-\*(#H)'\`\h'|\\n:u' . ds ^ \\k:\h'-(\\n(.wu*10/11-\*(#H)'^\h'|\\n:u' . ds , \\k:\h'-(\\n(.wu*8/10)',\h'|\\n:u' . ds ~ \\k:\h'-(\\n(.wu-\*(#H-.1m)'~\h'|\\n:u' . ds / \\k:\h'-(\\n(.wu*8/10-\*(#H)'\z\(sl\h'|\\n:u' .\} . \" troff and (daisy-wheel) nroff accents .ds : \\k:\h'-(\\n(.wu*8/10-\*(#H+.1m+\*(#F)'\v'-\*(#V'\z.\h'.2m+\*(#F'.\h'|\\n:u'\v'\*(#V' .ds 8 \h'\*(#H'\(*b\h'-\*(#H' .ds o \\k:\h'-(\\n(.wu+\w'\(de'u-\*(#H)/2u'\v'-.3n'\*(#[\z\(de\v'.3n'\h'|\\n:u'\*(#] .ds d- \h'\*(#H'\(pd\h'-\w'~'u'\v'-.25m'\f2\(hy\fP\v'.25m'\h'-\*(#H' .ds D- D\\k:\h'-\w'D'u'\v'-.11m'\z\(hy\v'.11m'\h'|\\n:u' .ds th \*(#[\v'.3m'\s+1I\s-1\v'-.3m'\h'-(\w'I'u*2/3)'\s-1o\s+1\*(#] .ds Th \*(#[\s+2I\s-2\h'-\w'I'u*3/5'\v'-.3m'o\v'.3m'\*(#] .ds ae a\h'-(\w'a'u*4/10)'e .ds Ae A\h'-(\w'A'u*4/10)'E . \" corrections for vroff .if v .ds ~ \\k:\h'-(\\n(.wu*9/10-\*(#H)'\s-2\u~\d\s+2\h'|\\n:u' .if v .ds ^ \\k:\h'-(\\n(.wu*10/11-\*(#H)'\v'-.4m'^\v'.4m'\h'|\\n:u' . \" for low resolution devices (crt and lpr) .if \n(.H>23 .if \n(.V>19 \ \{\ . ds : e . ds 8 ss . ds o a . ds d- d\h'-1'\(ga . ds D- D\h'-1'\(hy . ds th \o'bp' . ds Th \o'LP' . ds ae ae . ds Ae AE .\} .rm #[ #] #H #V #F C .\" ======================================================================== .\" .IX Title "Future::IO 3pm" .TH Future::IO 3pm "2023-02-21" "perl v5.36.0" "User Contributed Perl Documentation" .\" For nroff, turn off justification. Always turn off hyphenation; it makes .\" way too many mistakes in technical documents. .if n .ad l .nh .SH "NAME" "Future::IO" \- Future\-returning IO methods .SH "SYNOPSIS" .IX Header "SYNOPSIS" .Vb 1 \& use Future::IO; \& \& my $delay = Future::IO\->sleep( 5 ); \& # $delay will become done in 5 seconds time \& \& my $input = Future::IO\->sysread( \e*STDIN, 4096 ); \& # $input will yield some input from the STDIN IO handle .Ve .SH "DESCRIPTION" .IX Header "DESCRIPTION" This package provides a few basic methods that behave similarly to the same-named core perl functions relating to \s-1IO\s0 operations, but yield their results asynchronously via Future instances. .PP This is provided primarily as a decoupling mechanism, to allow modules to be written that perform \s-1IO\s0 in an asynchronous manner to depend directly on this, while allowing asynchronous event systems to provide an implementation of these operations. .SS "Default Implementation" .IX Subsection "Default Implementation" If the \f(CW\*(C`override_impl\*(C'\fR method is not invoked, a default implementation of these operations is provided. This implementation allows a single queue of \&\f(CW\*(C`sysread\*(C'\fR or \f(CW\*(C`syswrite\*(C'\fR calls on a single filehandle only, combined with \&\f(CW\*(C`sleep\*(C'\fR calls. It does not support \f(CW\*(C`waitpid\*(C'\fR. .PP It is provided for the simple cases where modules only need one filehandle (most likely a single network socket or hardware device handle), allowing such modules to work without needing a better event system. .PP If there are both read/write and \f(CW\*(C`sleep\*(C'\fR futures pending, the implementation will use \f(CW\*(C`select()\*(C'\fR to wait for either. This may be problematic on MSWin32, depending on what type of filehandle is involved. .PP For cases where multiple filehandles are required, or for doing more involved \&\s-1IO\s0 operations, a real implementation based on an actual event loop should be provided. The following are known to exist; \s-1CPAN\s0 may provide others: .IP "\(bu" 4 Future::IO::Impl::Glib .IP "\(bu" 4 Future::IO::Impl::IOAsync .IP "\(bu" 4 Future::IO::Impl::UV .SS "Unit Testing" .IX Subsection "Unit Testing" The replaceable implementation is also useful for writing unit test scripts. If the implementation is set to an instance of some sort of test fixture or mocking object, a unit test can check that the appropriate \s-1IO\s0 operations happen as part of the test. .PP A testing module which does this is provided by Test::Future::IO. .SH "METHODS" .IX Header "METHODS" .SS "accept" .IX Subsection "accept" .Vb 1 \& $socketfh = await Future::IO\->accept( $fh ); .Ve .PP \&\fISince version 0.11.\fR .PP Returns a Future that will become done when a new connection has been accepted on the given filehandle, which should represent a listen-mode socket. The returned future will yield the newly-accepted client socket filehandle. .SS "alarm" .IX Subsection "alarm" .Vb 1 \& await Future::IO\->alarm( $epoch ); .Ve .PP \&\fISince version 0.08.\fR .PP Returns a Future that will become done at a fixed point in the future, given as an epoch timestamp (such as returned by \f(CW\*(C`time()\*(C'\fR). This value may be fractional. .SS "connect" .IX Subsection "connect" .Vb 1 \& await Future::IO\->connect( $fh, $name ); .Ve .PP \&\fISince version 0.11.\fR .PP Returns a Future that will become done when a \f(CW\*(C`connect()\*(C'\fR has succeeded on the given filehandle to the given sockname address. .SS "sleep" .IX Subsection "sleep" .Vb 1 \& await Future::IO\->sleep( $secs ); .Ve .PP Returns a Future that will become done a fixed delay from now, given in seconds. This value may be fractional. .SS "sysread" .IX Subsection "sysread" .Vb 1 \& $bytes = await Future::IO\->sysread( $fh, $length ); .Ve .PP Returns a Future that will become done when at least one byte can be read from the given filehandle. It may return up to \f(CW$length\fR bytes. On \s-1EOF,\s0 the returned future will yield an empty list (or \f(CW\*(C`undef\*(C'\fR in scalar context). On any error (other than \f(CW\*(C`EAGAIN\*(C'\fR / \f(CW\*(C`EWOULDBLOCK\*(C'\fR which are ignored), the future fails with a suitable error message. .PP Note specifically this may perform only a single \f(CW\*(C`sysread()\*(C'\fR call, and thus is not guaranteed to actually return the full length. .SS "sysread_exactly" .IX Subsection "sysread_exactly" .Vb 1 \& $bytes = await Future::IO\->sysread_exactly( $fh, $length ); .Ve .PP \&\fISince version 0.03.\fR .PP Returns a Future that will become done when exactly the given number of bytes have been read from the given filehandle. It returns exactly \f(CW$length\fR bytes. On \s-1EOF,\s0 the returned future will yield an empty list (or \f(CW\*(C`undef\*(C'\fR in scalar context), even if fewer bytes have already been obtained. These bytes will be lost. On any error (other than \f(CW\*(C`EAGAIN\*(C'\fR / \f(CW\*(C`EWOULDBLOCK\*(C'\fR which are ignored), the future fails with a suitable error message. .PP This may make more than one \f(CW\*(C`sysread()\*(C'\fR call. .SS "sysread_until_eof" .IX Subsection "sysread_until_eof" .Vb 1 \& $f = Future::IO\->sysread_until_eof( $fh ) .Ve .PP \&\fISince version 0.12.\fR .PP Returns a Future that will become done when the given filehandle reaches the \s-1EOF\s0 condition. The returned future will yield all of the bytes read up until that point. .SS "syswrite" .IX Subsection "syswrite" .Vb 1 \& $written_len = await Future::IO\->syswrite( $fh, $bytes ); .Ve .PP \&\fISince version 0.04.\fR .PP Returns a Future that will become done when at least one byte has been written to the given filehandle. It may write up to all of the bytes. On any error (other than \f(CW\*(C`EAGAIN\*(C'\fR / \f(CW\*(C`EWOULDBLOCK\*(C'\fR which are ignored) the future fails with a suitable error message. .PP Note specifically this may perform only a single \f(CW\*(C`syswrite()\*(C'\fR call, and thus is not guaranteed to actually return the full length. .SS "syswrite_exactly" .IX Subsection "syswrite_exactly" .Vb 1 \& $written_len = await Future::IO\->syswrite_exactly( $fh, $bytes ); .Ve .PP \&\fISince version 0.04.\fR .PP Returns a Future that will become done when exactly the given bytes have been written to the given filehandle. On any error (other than \f(CW\*(C`EAGAIN\*(C'\fR / \&\f(CW\*(C`EWOULDBLOCK\*(C'\fR which are ignored) the future fails with a suitable error message. .PP This may make more than one \f(CW\*(C`syswrite()\*(C'\fR call. .SS "waitpid" .IX Subsection "waitpid" .Vb 1 \& $wstatus = await Future::IO\->waitpid( $pid ); .Ve .PP \&\fISince version 0.09.\fR .PP Returns a Future that will become done when the given child process terminates. The future will yield the wait status of the child process. This can be inspected by the usual bitshifting operations as per \f(CW$?\fR: .PP .Vb 7 \& if( my $termsig = ($wstatus & 0x7f) ) { \& say "Terminated with signal $termsig"; \& } \& else { \& my $exitcode = ($wstatus >> 8); \& say "Terminated with exit code $exitcode"; \& } .Ve .SS "override_impl" .IX Subsection "override_impl" .Vb 1 \& Future::IO\->override_impl( $impl ); .Ve .PP Sets a new implementation for \f(CW\*(C`Future::IO\*(C'\fR, replacing the minimal default internal implementation. This can either be a package name or an object instance reference, but must provide the methods named above. .PP This method is intended to be called by event loops and other similar places, to provide a better integration. Another way, which doesn't involve directly depending on \f(CW\*(C`Future::IO\*(C'\fR or loading it, is to use the \f(CW$IMPL\fR variable; see below. .PP Can only be called once, and only if the default implementation is not in use, therefore a module that wishes to override this ought to invoke it as soon as possible on program startup, before any of the main \f(CW\*(C`Future::IO\*(C'\fR methods may have been called. .SS "\s-1HAVE_MULTIPLE_FILEHANDLES\s0" .IX Subsection "HAVE_MULTIPLE_FILEHANDLES" .Vb 1 \& $has = Future::IO\->HAVE_MULTIPLE_FILEHANDLES; .Ve .PP \&\fISince version 0.11.\fR .PP Returns true if the underlying \s-1IO\s0 implementation actually supports multiple filehandles. Most real support modules will return true here, but this returns false for the internal minimal implementation. .SS "await" .IX Subsection "await" .Vb 1 \& $f = $f\->await; .Ve .PP \&\fISince version 0.07.\fR .PP Blocks until this future is ready (either by success or failure). Does not throw an exception if failed. .ie n .SH "THE $IMPL VARIABLE" .el .SH "THE \f(CW$IMPL\fP VARIABLE" .IX Header "THE $IMPL VARIABLE" \&\fISince version 0.02.\fR .PP As an alternative to setting an implementation by using override_impl, a package variable is also available that allows modules such as event systems to opportunistically provide an implementation without needing to depend on the module, or loading it \f(CW\*(C`require\*(C'\fR. Simply directly set that package variable to the name of an implementing package or an object instance. .PP Additionally, implementors may use a name within the \f(CW\*(C`Future::IO::Impl::\*(C'\fR namespace, suffixed by the name of their event system. .PP For example, something like the following code arrangement is recommended. .PP .Vb 1 \& package Future::IO::Impl::BananaLoop; \& \& { \& no warnings \*(Aqonce\*(Aq; \& ( $Future::IO::IMPL //= _\|_PACKAGE_\|_ ) eq _\|_PACKAGE_\|_ or \& warn "Unable to set Future::IO implementation to " . _\|_PACKAGE_\|_ . \& " as it is already $Future::IO::IMPL\en"; \& } \& \& sub sleep \& { \& ... \& } \& \& sub sysread \& { \& ... \& } \& \& sub syswrite \& { \& ... \& } \& \& sub waitpid \& { \& ... \& } .Ve .PP Optionally, you can also implement \*(L"sysread_exactly\*(R" and \&\*(L"syswrite_exactly\*(R": .PP .Vb 4 \& sub sysread_exactly \& { \& ... \& } \& \& sub syswrite_exactly \& { \& ... \& } .Ve .PP If not, they will be emulated by \f(CW\*(C`Future::IO\*(C'\fR itself, making multiple calls to the non\-\f(CW\*(C`_exactly\*(C'\fR versions. .SH "AUTHOR" .IX Header "AUTHOR" Paul Evans