blib/lib/Future/XS.pm

filter: Statementstmt 100% 18 / 18 Branchbran n/a Conditioncond n/a MC/DCmcdc n/a Subroutinesub 100% 4 / 4 Podpod n/a totaltotal 100% 22 / 22 CC 1 SCAR 0.0
CC
1
Cov
100%
BEGIN
1.0
BEGIN
1.0
BEGIN
1.0
CRAP 1.0
« src/future.c ↑ Summary
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;
« src/future.c ↑ Summary