| 1 | # You may distribute under the terms of either the GNU General Public License | ||
| 2 | # or the Artistic License (the same terms as Perl itself) | ||
| 3 | # | ||
| 4 | # (C) Paul Evans, 2022-2024 -- leonerd@leonerd.org.uk | ||
| 5 | |||
| 6 | package Future::XS 0.16; | ||
| 7 | |||
| 8 | 3 | ▶ | use v5.24; |
|
Subroutine
BEGIN: called CC=1 SCAR=0.0
| |||
| 9 | 3 | ▶ | use warnings; |
|
Subroutine
BEGIN: called CC=1 SCAR=0.0
| |||
| 10 | |||
| 11 | 3 | ▶ | use Carp; |
|
Subroutine
BEGIN: called CC=1 SCAR=0.0
| |||
| 12 | |||
| 13 | 3 | require XSLoader; | |
| 14 | 3 | XSLoader::load( __PACKAGE__, our $VERSION ); | |
| 15 | |||
| 16 | 3 | ▶ | use Time::HiRes qw( tv_interval ); |
|
Subroutine
BEGIN: called CC=1 SCAR=0.0
| |||
| 17 | |||
| 18 | # Future::_base is provided in Future.pm itself | ||
| 19 | 3 | require Future; | |
| 20 | 3 | our @ISA = qw( Future::_base ); | |
| 21 | |||
| 22 | 3 | our @CARP_NOT = qw( Future Future::_base ); | |
| 23 | |||
| 24 | 3 | require Future::Exception; | |
| 25 | |||
| 26 | =head1 NAME | ||
| 27 | |||
| 28 | C<Future::XS> - experimental XS implementation of C<Future> | ||
| 29 | |||
| 30 | =head1 SYNOPSIS | ||
| 31 | |||
| 32 | =for highlighter language=perl | ||
| 33 | |||
| 34 | my $future = Future::XS->new; | ||
| 35 | |||
| 36 | perform_some_operation( | ||
| 37 | on_complete => sub { | ||
| 38 | $future->done( @_ ); | ||
| 39 | } | ||
| 40 | ); | ||
| 41 | |||
| 42 | $future->on_ready( sub { | ||
| 43 | say "The operation is complete"; | ||
| 44 | } ); | ||
| 45 | |||
| 46 | =head1 DESCRIPTION | ||
| 47 | |||
| 48 | This module provides an XS-based implementation of the L<Future> class. It is | ||
| 49 | currently experimental and shipped in its own distribution for testing | ||
| 50 | purposes, though once it seems stable the plan is to move it into the main | ||
| 51 | C<Future> distribution and load it automatically in favour of the pureperl | ||
| 52 | implementation on supported systems. | ||
| 53 | |||
| 54 | =head2 Future::XS and threads | ||
| 55 | |||
| 56 | In a program not involving multiple threads, this module behaves entirely as | ||
| 57 | expected, following the behaviour of the regular pure-perl C<Future> | ||
| 58 | implementation (regardless of whether or not the perl interpreter is actually | ||
| 59 | built to support threads). | ||
| 60 | |||
| 61 | When multiple threads are created, previous versions of this module would most | ||
| 62 | likely crash. The current version (0.10) fixes enough of the logic, that | ||
| 63 | future instances that are only ever accessed from one thread (either the | ||
| 64 | initial main thread, or any additional sidecar threads) will work fine. | ||
| 65 | However, future instances cannot currently cross the boundary between threads. | ||
| 66 | Any instances that were created before a new thread is made will no longer be | ||
| 67 | accessible within that thread, and instances may not be returned as the result | ||
| 68 | of the thread exit value. Some of these restrictions may be relaxed in later | ||
| 69 | versions. | ||
| 70 | |||
| 71 | Attempts to access a future instance created in one thread from another thread | ||
| 72 | will raise an exception: | ||
| 73 | |||
| 74 | =for highlighter | ||
| 75 | |||
| 76 | Future::XS instance IO::Async::Future=SCALAR(0x...) is not available in this thread at ... | ||
| 77 | |||
| 78 | As a special case for process cleanup activities, the C<< ->cancel >> method | ||
| 79 | does not throw this exception, but simply returns silently. This is because | ||
| 80 | cleanup code such as C<DESTROY> methods or C<defer> blocks often attempt to | ||
| 81 | call this on existing instances. | ||
| 82 | |||
| 83 | =cut | ||
| 84 | |||
| 85 | =head1 AUTHOR | ||
| 86 | |||
| 87 | Paul Evans <leonerd@leonerd.org.uk> | ||
| 88 | |||
| 89 | =cut | ||
| 90 | |||
| 91 | 3 | 0x55AA; | |