.\" -*- mode: troff; coding: utf-8 -*-
.\" Automatically generated by Pod::Man 5.01 (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
..
.\" \*(C` and \*(C' are quotes in nroff, nothing in troff, for use with C<>.
.ie n \{\
.    ds C` ""
.    ds C' ""
'br\}
.el\{\
.    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
.\" ========================================================================
.\"
.IX Title "Future::XS 3pm"
.TH Future::XS 3pm 2024-03-07 "perl v5.38.2" "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::XS" \- experimental XS implementation of "Future"
.SH SYNOPSIS
.IX Header "SYNOPSIS"
.Vb 1
\&   my $future = Future::XS\->new;
\&
\&   perform_some_operation(
\&      on_complete => sub {
\&         $future\->done( @_ );
\&      }
\&   );
\&
\&   $future\->on_ready( sub {
\&      say "The operation is complete";
\&   } );
.Ve
.SH DESCRIPTION
.IX Header "DESCRIPTION"
This module provides an XS-based implementation of the Future class. It is
currently experimental and shipped in its own distribution for testing
purposes, though once it seems stable the plan is to move it into the main
\&\f(CW\*(C`Future\*(C'\fR distribution and load it automatically in favour of the pureperl
implementation on supported systems.
.SS "Future::XS and threads"
.IX Subsection "Future::XS and threads"
In a program not involving multiple threads, this module behaves entirely as
expected, following the behaviour of the regular pure-perl \f(CW\*(C`Future\*(C'\fR
implementation (regardless of whether or not the perl interpreter is actually
built to support threads).
.PP
When multiple threads are created, previous versions of this module would most
likely crash. The current version (0.10) fixes enough of the logic, that
future instances that are only ever accessed from one thread (either the
initial main thread, or any additional sidecar threads) will work fine.
However, future instances cannot currently cross the boundary between threads.
Any instances that were created before a new thread is made will no longer be
accessible within that thread, and instances may not be returned as the result
of the thread exit value. Some of these restrictions may be relaxed in later
versions.
.PP
Attempts to access a future instance created in one thread from another thread
will raise an exception:
.PP
.Vb 1
\&   Future::XS instance IO::Async::Future=SCALAR(0x...) is not available in this thread at ...
.Ve
.PP
As a special case for process cleanup activities, the \f(CW\*(C`\->cancel\*(C'\fR method
does not throw this exception, but simply returns silently. This is because
cleanup code such as \f(CW\*(C`DESTROY\*(C'\fR methods or \f(CW\*(C`defer\*(C'\fR blocks often attempt to
call this on existing instances.
.SH AUTHOR
.IX Header "AUTHOR"
Paul Evans <leonerd@leonerd.org.uk>