Acme-Sort-Sleep
view release on metacpan or search on metacpan
local/lib/perl5/Future.pm view on Meta::CPAN
$future = $orig->new
Returns a new C<Future> instance to represent a leaf future. It will be marked
as ready by any of the C<done>, C<fail>, or C<cancel> methods. It can be
called either as a class method, or as an instance method. Called on an
instance it will construct another in the same class, and is useful for
subclassing.
This constructor would primarily be used by implementations of asynchronous
interfaces.
=cut
# Callback flags
use constant {
CB_DONE => 1<<0, # Execute callback on done
CB_FAIL => 1<<1, # Execute callback on fail
CB_CANCEL => 1<<2, # Execute callback on cancellation
CB_SELF => 1<<3, # Pass $self as first argument
CB_RESULT => 1<<4, # Pass result/failure as a list
CB_SEQ_ONDONE => 1<<5, # Sequencing on success (->then)
CB_SEQ_ONFAIL => 1<<6, # Sequencing on failure (->else)
CB_SEQ_IMDONE => 1<<7, # $code is in fact immediate ->done result
CB_SEQ_IMFAIL => 1<<8, # $code is in fact immediate ->fail result
};
use constant CB_ALWAYS => CB_DONE|CB_FAIL|CB_CANCEL;
# Useful for identifying CODE references
sub CvNAME_FILE_LINE
{
my ( $code ) = @_;
my $cv = svref_2object( $code );
my $name = join "::", $cv->STASH->NAME, $cv->GV->NAME;
return $name unless $cv->GV->NAME eq "__ANON__";
# $cv->GV->LINE isn't reliable, as outside of perl -d mode all anon CODE
# in the same file actually shares the same GV. :(
# Walk the optree looking for the first COP
my $cop = $cv->START;
$cop = $cop->next while $cop and ref $cop ne "B::COP";
sprintf "%s(%s line %d)", $cv->GV->NAME, $cop->file, $cop->line;
}
sub _callable
{
my ( $cb ) = @_;
defined $cb and ( reftype($cb) eq 'CODE' || overload::Method($cb, '&{}') );
}
sub new
{
my $proto = shift;
return bless {
ready => 0,
callbacks => [], # [] = [$type, ...]
( DEBUG ?
( do { my $at = Carp::shortmess( "constructed" );
chomp $at; $at =~ s/\.$//;
constructed_at => $at } )
: () ),
( $TIMES ?
( btime => [ gettimeofday ] )
: () ),
}, ( ref $proto || $proto );
}
my $GLOBAL_END;
END { $GLOBAL_END = 1; }
sub DESTROY_debug {
my $self = shift;
return if $GLOBAL_END;
return if $self->{ready} and ( $self->{reported} or !$self->{failure} );
my $lost_at = join " line ", (caller)[1,2];
# We can't actually know the real line where the last reference was lost;
# a variable set to 'undef' or close of scope, because caller can't see it;
# the current op has already been updated. The best we can do is indicate
# 'near'.
if( $self->{ready} and $self->{failure} ) {
warn "${\$self->__selfstr} was $self->{constructed_at} and was lost near $lost_at with an unreported failure of: " .
$self->{failure}[0] . "\n";
}
elsif( !$self->{ready} ) {
warn "${\$self->__selfstr} was $self->{constructed_at} and was lost near $lost_at before it was ready.\n";
}
}
*DESTROY = \&DESTROY_debug if DEBUG;
=head2 done I<(class method)>
=head2 fail I<(class method)>
$future = Future->done( @values )
$future = Future->fail( $exception, @details )
I<Since version 0.26.>
Shortcut wrappers around creating a new C<Future> then immediately marking it
as done or failed.
=head2 wrap
$future = Future->wrap( @values )
I<Since version 0.14.>
If given a single argument which is already a C<Future> reference, this will
be returned unmodified. Otherwise, returns a new C<Future> instance that is
already complete, and will yield the given values.
This will ensure that an incoming argument is definitely a C<Future>, and may
be useful in such cases as adapting synchronous code to fit asynchronous
local/lib/perl5/Future.pm view on Meta::CPAN
{
my $class = shift;
my @values = @_;
if( @values == 1 and blessed $values[0] and $values[0]->isa( __PACKAGE__ ) ) {
return $values[0];
}
else {
return $class->done( @values );
}
}
=head2 call
$future = Future->call( \&code, @args )
I<Since version 0.15.>
A convenient wrapper for calling a C<CODE> reference that is expected to
return a future. In normal circumstances is equivalent to
$future = $code->( @args )
except that if the code throws an exception, it is wrapped in a new immediate
fail future. If the return value from the code is not a blessed C<Future>
reference, an immediate fail future is returned instead to complain about this
fact.
=cut
sub call
{
my $class = shift;
my ( $code, @args ) = @_;
my $f;
eval { $f = $code->( @args ); 1 } or $f = $class->fail( $@ );
blessed $f and $f->isa( "Future" ) or $f = $class->fail( "Expected " . CvNAME_FILE_LINE($code) . " to return a Future" );
return $f;
}
sub _shortmess
{
my $at = Carp::shortmess( $_[0] );
chomp $at; $at =~ s/\.$//;
return $at;
}
sub _mark_ready
{
my $self = shift;
$self->{ready} = 1;
$self->{ready_at} = _shortmess $_[0] if DEBUG;
if( $TIMES ) {
$self->{rtime} = [ gettimeofday ];
}
delete $self->{on_cancel};
my $callbacks = delete $self->{callbacks} or return;
my $cancelled = $self->{cancelled};
my $fail = defined $self->{failure};
my $done = !$fail && !$cancelled;
my @result = $done ? $self->get :
$fail ? $self->failure :
();
foreach my $cb ( @$callbacks ) {
my ( $flags, $code ) = @$cb;
my $is_future = blessed( $code ) && $code->isa( "Future" );
next if $done and not( $flags & CB_DONE );
next if $fail and not( $flags & CB_FAIL );
next if $cancelled and not( $flags & CB_CANCEL );
$self->{reported} = 1 if $fail;
if( $is_future ) {
$done ? $code->done( @result ) :
$fail ? $code->fail( @result ) :
$code->cancel;
}
elsif( $flags & (CB_SEQ_ONDONE|CB_SEQ_ONFAIL) ) {
my ( undef, undef, $fseq ) = @$cb;
if( !$fseq ) { # weaken()ed; it might be gone now
# This warning should always be printed, even not in DEBUG mode.
# It's always an indication of a bug
Carp::carp +(DEBUG ? "${\$self->__selfstr} ($self->{constructed_at})"
: "${\$self->__selfstr} $self" ) .
" lost a sequence Future";
next;
}
my $f2;
if( $done and $flags & CB_SEQ_ONDONE or
$fail and $flags & CB_SEQ_ONFAIL ) {
if( $flags & CB_SEQ_IMDONE ) {
$fseq->done( @$code );
next;
}
elsif( $flags & CB_SEQ_IMFAIL ) {
$fseq->fail( @$code );
next;
}
my @args = (
( $flags & CB_SELF ? $self : () ),
( $flags & CB_RESULT ? @result : () ),
);
unless( eval { $f2 = $code->( @args ); 1 } ) {
$fseq->fail( $@ );
next;
}
unless( blessed $f2 and $f2->isa( "Future" ) ) {
$fseq->fail( "Expected " . CvNAME_FILE_LINE($code) . " to return a Future" );
next;
}
$fseq->on_cancel( $f2 );
}
else {
$f2 = $self;
}
if( $f2->is_ready ) {
$f2->on_ready( $fseq ) if !$f2->{cancelled};
}
else {
push @{ $f2->{callbacks} }, [ CB_DONE|CB_FAIL, $fseq ];
weaken( $f2->{callbacks}[-1][1] );
}
}
else {
$code->(
( $flags & CB_SELF ? $self : () ),
( $flags & CB_RESULT ? @result : () ),
);
}
}
}
sub _state
{
my $self = shift;
return !$self->{ready} ? "pending" :
DEBUG ? $self->{ready_at} :
$self->{failure} ? "failed" :
$self->{cancelled} ? "cancelled" :
"done";
}
=head1 IMPLEMENTATION METHODS
These methods would primarily be used by implementations of asynchronous
interfaces.
=cut
=head2 done
$future->done( @result )
Marks that the leaf future is now ready, and provides a list of values as a
result. (The empty list is allowed, and still indicates the future as ready).
Cannot be called on a convergent future.
If the future is already cancelled, this request is ignored. If the future is
already complete with a result or a failure, an exception is thrown.
=cut
sub done
{
my $self = shift;
if( ref $self ) {
$self->{cancelled} and return $self;
$self->{ready} and Carp::croak "${\$self->__selfstr} is already ".$self->_state." and cannot be ->done";
$self->{subs} and Carp::croak "${\$self->__selfstr} is not a leaf Future, cannot be ->done";
$self->{result} = [ @_ ];
$self->_mark_ready( "done" );
}
else {
$self = $self->new;
$self->{ready} = 1;
$self->{ready_at} = _shortmess "done" if DEBUG;
$self->{result} = [ @_ ];
}
return $self;
local/lib/perl5/Future.pm view on Meta::CPAN
$self->{subs} and Carp::croak "${\$self->__selfstr} is not a leaf Future, cannot be ->fail'ed";
$self->{failure} = [ $exception, @details ];
$self->_mark_ready( "fail" );
}
else {
$self = $self->new;
$self->{ready} = 1;
$self->{ready_at} = _shortmess "fail" if DEBUG;
$self->{failure} = [ $exception, @details ];
}
if( DEBUG ) {
my $at = Carp::shortmess( "failed" );
chomp $at; $at =~ s/\.$//;
$self->{ready_at} = $at;
}
return $self;
}
sub fail_cb
{
my $self = shift;
return sub { $self->fail( @_ ) };
}
=head2 die
$future->die( $message, @details )
I<Since version 0.09.>
A convenient wrapper around C<fail>. If the exception is a non-reference that
does not end in a linefeed, its value will be extended by the file and line
number of the caller, similar to the logic that C<die> uses.
Returns the C<$future>.
=cut
sub die :method
{
my $self = shift;
my ( $exception, @details ) = @_;
if( !ref $exception and $exception !~ m/\n$/ ) {
$exception .= sprintf " at %s line %d\n", (caller)[1,2];
}
$self->fail( $exception, @details );
}
=head2 on_cancel
$future->on_cancel( $code )
If the future is not yet ready, adds a callback to be invoked if the future is
cancelled by the C<cancel> method. If the future is already ready, throws an
exception.
If the future is cancelled, the callbacks will be invoked in the reverse order
to that in which they were registered.
$on_cancel->( $future )
If passed another C<Future> instance, the passed instance will be cancelled
when the original future is cancelled. This method does nothing if the future
is already complete.
=cut
sub on_cancel
{
my $self = shift;
my ( $code ) = @_;
my $is_future = blessed( $code ) && $code->isa( "Future" );
$is_future or _callable( $code ) or
Carp::croak "Expected \$code to be callable or a Future in ->on_cancel";
$self->{ready} and return $self;
push @{ $self->{on_cancel} }, $code;
return $self;
}
=head2 is_cancelled
$cancelled = $future->is_cancelled
Returns true if the future has been cancelled by C<cancel>.
=cut
sub is_cancelled
{
my $self = shift;
return $self->{cancelled};
}
=head1 USER METHODS
These methods would primarily be used by users of asynchronous interfaces, on
objects returned by such an interface.
=cut
=head2 is_ready
$ready = $future->is_ready
Returns true on a leaf future if a result has been provided to the C<done>
method, failed using the C<fail> method, or cancelled using the C<cancel>
method.
Returns true on a convergent future if it is ready to yield a result,
depending on its component futures.
=cut
sub is_ready
{
my $self = shift;
return $self->{ready};
}
=head2 on_ready
$future->on_ready( $code )
If the future is not yet ready, adds a callback to be invoked when the future
is ready. If the future is already ready, invokes it immediately.
In either case, the callback will be passed the future object itself. The
invoked code can then obtain the list of results by calling the C<get> method.
$on_ready->( $future )
If passed another C<Future> instance, the passed instance will have its
C<done>, C<fail> or C<cancel> methods invoked when the original future
completes successfully, fails, or is cancelled respectively.
Returns the C<$future>.
=cut
sub on_ready
{
my $self = shift;
my ( $code ) = @_;
my $is_future = blessed( $code ) && $code->isa( "Future" );
$is_future or _callable( $code ) or
Carp::croak "Expected \$code to be callable or a Future in ->on_ready";
if( $self->{ready} ) {
my $fail = defined $self->{failure};
my $done = !$fail && !$self->{cancelled};
$self->{reported} = 1 if $fail;
$is_future ? ( $done ? $code->done( $self->get ) :
$fail ? $code->fail( $self->failure ) :
$code->cancel )
: $code->( $self );
}
else {
push @{ $self->{callbacks} }, [ CB_ALWAYS|CB_SELF, $self->wrap_cb( on_ready => $code ) ];
}
return $self;
}
=head2 is_done
$done = $future->is_done
Returns true on a future if it is ready and completed successfully. Returns
false if it is still pending, failed, or was cancelled.
=cut
sub is_done
{
my $self = shift;
return $self->{ready} && !$self->{failure} && !$self->{cancelled};
}
=head2 get
@result = $future->get
$result = $future->get
If the future is ready and completed successfully, returns the list of
results that had earlier been given to the C<done> method on a leaf future,
or the list of component futures it was waiting for on a convergent future. In
scalar context it returns just the first result value.
If the future is ready but failed, this method raises as an exception the
failure string or object that was given to the C<fail> method.
If the future was cancelled an exception is thrown.
If it is not yet ready and is not of a subclass that provides an C<await>
method an exception is thrown. If it is subclassed to provide an C<await>
method then this is used to wait for the future to be ready, before returning
the result or propagating its failure exception.
=cut
sub await
{
my $self = shift;
Carp::croak "$self is not yet complete and does not provide ->await";
}
sub get
{
my $self = shift;
$self->await until $self->{ready};
if( $self->{failure} ) {
$self->{reported} = 1;
my $exception = $self->{failure}->[0];
!ref $exception && $exception =~ m/\n$/ ? CORE::die $exception : Carp::croak $exception;
}
$self->{cancelled} and Carp::croak "${\$self->__selfstr} was cancelled";
return $self->{result}->[0] unless wantarray;
local/lib/perl5/Future.pm view on Meta::CPAN
values directly in list context, or the first value in scalar. Since it
involves an implicit C<await>, this method can only be used on immediate
futures or subclasses that implement C<await>.
This will ensure that an outgoing argument is definitely not a C<Future>, and
may be useful in such cases as adapting synchronous code to fit asynchronous
libraries that return C<Future> instances.
=cut
sub unwrap
{
shift; # $class
my @values = @_;
if( @values == 1 and blessed $values[0] and $values[0]->isa( __PACKAGE__ ) ) {
return $values[0]->get;
}
else {
return $values[0] if !wantarray;
return @values;
}
}
=head2 on_done
$future->on_done( $code )
If the future is not yet ready, adds a callback to be invoked when the future
is ready, if it completes successfully. If the future completed successfully,
invokes it immediately. If it failed or was cancelled, it is not invoked at
all.
The callback will be passed the result passed to the C<done> method.
$on_done->( @result )
If passed another C<Future> instance, the passed instance will have its
C<done> method invoked when the original future completes successfully.
Returns the C<$future>.
=cut
sub on_done
{
my $self = shift;
my ( $code ) = @_;
my $is_future = blessed( $code ) && $code->isa( "Future" );
$is_future or _callable( $code ) or
Carp::croak "Expected \$code to be callable or a Future in ->on_done";
if( $self->{ready} ) {
return $self if $self->{failure} or $self->{cancelled};
$is_future ? $code->done( $self->get )
: $code->( $self->get );
}
else {
push @{ $self->{callbacks} }, [ CB_DONE|CB_RESULT, $self->wrap_cb( on_done => $code ) ];
}
return $self;
}
=head2 is_failed
$failed = $future->is_failed
I<Since version 0.26.>
Returns true on a future if it is ready and it failed. Returns false if it is
still pending, completed successfully, or was cancelled.
=cut
sub is_failed
{
my $self = shift;
return $self->{ready} && !!$self->{failure}; # boolify
}
=head2 failure
$exception = $future->failure
$exception, @details = $future->failure
Returns the exception passed to the C<fail> method, C<undef> if the future
completed successfully via the C<done> method, or raises an exception if
called on a future that is not yet ready.
If called in list context, will additionally yield a list of the details
provided to the C<fail> method.
Because the exception value must be true, this can be used in a simple C<if>
statement:
if( my $exception = $future->failure ) {
...
}
else {
my @result = $future->get;
...
}
=cut
sub failure
{
my $self = shift;
$self->await until $self->{ready};
return unless $self->{failure};
$self->{reported} = 1;
return $self->{failure}->[0] if !wantarray;
return @{ $self->{failure} };
}
=head2 on_fail
$future->on_fail( $code )
If the future is not yet ready, adds a callback to be invoked when the future
is ready, if it fails. If the future has already failed, invokes it
immediately. If it completed successfully or was cancelled, it is not invoked
at all.
The callback will be passed the exception and details passed to the C<fail>
method.
$on_fail->( $exception, @details )
If passed another C<Future> instance, the passed instance will have its
C<fail> method invoked when the original future fails.
To invoke a C<done> method on a future when another one fails, use a CODE
reference:
$future->on_fail( sub { $f->done( @_ ) } );
Returns the C<$future>.
=cut
sub on_fail
{
my $self = shift;
my ( $code ) = @_;
my $is_future = blessed( $code ) && $code->isa( "Future" );
$is_future or _callable( $code ) or
Carp::croak "Expected \$code to be callable or a Future in ->on_fail";
if( $self->{ready} ) {
return $self if not $self->{failure};
$self->{reported} = 1;
$is_future ? $code->fail( $self->failure )
: $code->( $self->failure );
}
else {
push @{ $self->{callbacks} }, [ CB_FAIL|CB_RESULT, $self->wrap_cb( on_fail => $code ) ];
}
return $self;
}
=head2 cancel
$future->cancel
Requests that the future be cancelled, immediately marking it as ready. This
will invoke all of the code blocks registered by C<on_cancel>, in the reverse
order. When called on a convergent future, all its component futures are also
cancelled. It is not an error to attempt to cancel a future that is already
complete or cancelled; it simply has no effect.
Returns the C<$future>.
=cut
sub cancel
{
my $self = shift;
return $self if $self->{ready};
$self->{cancelled}++;
foreach my $code ( reverse @{ $self->{on_cancel} || [] } ) {
my $is_future = blessed( $code ) && $code->isa( "Future" );
$is_future ? $code->cancel
: $code->( $self );
}
$self->_mark_ready( "cancel" );
return $self;
}
sub cancel_cb
{
my $self = shift;
return sub { $self->cancel };
}
=head1 SEQUENCING METHODS
The following methods all return a new future to represent the combination of
its invocant followed by another action given by a code reference. The
combined activity waits for the first future to be ready, then may invoke the
code depending on the success or failure of the first, or may run it
regardless. The returned sequence future represents the entire combination of
activity.
In some cases the code should return a future; in some it should return an
immediate result. If a future is returned, the combined future will then wait
for the result of this second one. If the combinined future is cancelled, it
will cancel either the first future or the second, depending whether the first
had completed. If the code block throws an exception instead of returning a
value, the sequence future will fail with that exception as its message and no
further values.
As it is always a mistake to call these sequencing methods in void context and lose the
reference to the returned future (because exception/error handling would be
silently dropped), this method warns in void context.
=cut
sub _sequence
{
my $f1 = shift;
my ( $code, $flags ) = @_;
# For later, we might want to know where we were called from
my $func = (caller 1)[3];
$func =~ s/^.*:://;
$flags & (CB_SEQ_IMDONE|CB_SEQ_IMFAIL) or _callable( $code ) or
Carp::croak "Expected \$code to be callable in ->$func";
if( !defined wantarray ) {
Carp::carp "Calling ->$func in void context";
}
if( $f1->is_ready ) {
# Take a shortcut
return $f1 if $f1->is_done and not( $flags & CB_SEQ_ONDONE ) or
$f1->failure and not( $flags & CB_SEQ_ONFAIL );
if( $flags & CB_SEQ_IMDONE ) {
return Future->done( @$code );
}
elsif( $flags & CB_SEQ_IMFAIL ) {
return Future->fail( @$code );
}
my @args = (
( $flags & CB_SELF ? $f1 : () ),
( $flags & CB_RESULT ? $f1->is_done ? $f1->get :
$f1->failure ? $f1->failure :
() : () ),
);
my $fseq;
unless( eval { $fseq = $code->( @args ); 1 } ) {
return Future->fail( $@ );
}
unless( blessed $fseq and $fseq->isa( "Future" ) ) {
return Future->fail( "Expected " . CvNAME_FILE_LINE($code) . " to return a Future" );
}
return $fseq;
}
my $fseq = $f1->new;
$fseq->on_cancel( $f1 );
# TODO: if anyone cares about the op name, we might have to synthesize it
# from $flags
$code = $f1->wrap_cb( sequence => $code ) unless $flags & (CB_SEQ_IMDONE|CB_SEQ_IMFAIL);
push @{ $f1->{callbacks} }, [ CB_DONE|CB_FAIL|$flags, $code, $fseq ];
weaken( $f1->{callbacks}[-1][2] );
return $fseq;
}
=head2 then
$future = $f1->then( \&done_code )
I<Since version 0.13.>
Returns a new sequencing C<Future> that runs the code if the first succeeds.
Once C<$f1> succeeds the code reference will be invoked and is passed the list
of results. It should return a future, C<$f2>. Once C<$f2> completes the
sequence future will then be marked as complete with whatever result C<$f2>
gave. If C<$f1> fails then the sequence future will immediately fail with the
same failure and the code will not be invoked.
$f2 = $done_code->( @result )
=head2 else
$future = $f1->else( \&fail_code )
I<Since version 0.13.>
Returns a new sequencing C<Future> that runs the code if the first fails. Once
C<$f1> fails the code reference will be invoked and is passed the failure and
details. It should return a future, C<$f2>. Once C<$f2> completes the sequence
future will then be marked as complete with whatever result C<$f2> gave. If
C<$f1> succeeds then the sequence future will immediately succeed with the
same result and the code will not be invoked.
$f2 = $fail_code->( $exception, @details )
=head2 then I<(2 arguments)>
$future = $f1->then( \&done_code, \&fail_code )
The C<then> method can also be passed the C<$fail_code> block as well, giving
a combination of C<then> and C<else> behaviour.
This operation is designed to be compatible with the semantics of other future
systems, such as Javascript's Q or Promises/A libraries.
=cut
my $make_donecatchfail_sub = sub {
my ( $with_f, $done_code, $fail_code, @catch_list ) = @_;
my $func = (caller 1)[3];
$func =~ s/^.*:://;
!$done_code or _callable( $done_code ) or
Carp::croak "Expected \$done_code to be callable in ->$func";
!$fail_code or _callable( $fail_code ) or
Carp::croak "Expected \$fail_code to be callable in ->$func";
my %catch_handlers = @catch_list;
_callable( $catch_handlers{$_} ) or
Carp::croak "Expected catch handler for '$_' to be callable in ->$func"
local/lib/perl5/Future.pm view on Meta::CPAN
In order for these times to be captured, they have to be enabled by setting
C<$Future::TIMES> to a true value. This is initialised true at the time the
module is loaded if either C<PERL_FUTURE_DEBUG> or C<PERL_FUTURE_TIMES> are
set in the environment.
=cut
sub btime
{
my $self = shift;
return $self->{btime};
}
sub rtime
{
my $self = shift;
return $self->{rtime};
}
=head2 elapsed
$sec = $future->elapsed
I<Since version 0.28.>
If both tracing timestamps are defined, returns the number of seconds of
elapsed time between them as a floating-point number. If not, returns
C<undef>.
=cut
sub elapsed
{
my $self = shift;
return undef unless defined $self->{btime} and defined $self->{rtime};
return $self->{elapsed} ||= tv_interval( $self->{btime}, $self->{rtime} );
}
=head2 wrap_cb
$cb = $future->wrap_cb( $operation_name, $cb )
I<Since version 0.31.>
I<Note: This method is experimental and may be changed or removed in a later
version.>
This method is invoked internally by various methods that are about to save a
callback CODE reference supplied by the user, to be invoked later. The default
implementation simply returns the callback agument as-is; the method is
provided to allow users to provide extra behaviour. This can be done by
applying a method modifier of the C<around> kind, so in effect add a chain of
wrappers. Each wrapper can then perform its own wrapping logic of the
callback. C<$operation_name> is a string giving the reason for which the
callback is being saved; currently one of C<on_ready>, C<on_done>, C<on_fail>
or C<sequence>; the latter being used for all the sequence-returning methods.
This method is intentionally invoked only for CODE references that are being
saved on a pending C<Future> instance to be invoked at some later point. It
does not run for callbacks to be invoked on an already-complete instance. This
is for performance reasons, where the intended behaviour is that the wrapper
can provide some amount of context save and restore, to return the operating
environment for the callback back to what it was at the time it was saved.
For example, the following wrapper saves the value of a package variable at
the time the callback was saved, and restores that value at invocation time
later on. This could be useful for preserving context during logging in a
Future-based program.
our $LOGGING_CTX;
no warnings 'redefine';
my $orig = Future->can( "wrap_cb" );
*Future::wrap_cb = sub {
my $cb = $orig->( @_ );
my $saved_logging_ctx = $LOGGING_CTX;
return sub {
local $LOGGING_CTX = $saved_logging_ctx;
$cb->( @_ );
};
};
At this point, any code deferred into a C<Future> by any of its callbacks will
observe the C<$LOGGING_CTX> variable as having the value it held at the time
the callback was saved, even if it is invoked later on when that value is
different.
Remember when writing such a wrapper, that it still needs to invoke the
previous version of the method, so that it plays nicely in combination with
others (see the C<< $orig->( @_ ) >> part).
=cut
sub wrap_cb
{
my $self = shift;
my ( $op, $cb ) = @_;
return $cb;
}
=head1 EXAMPLES
The following examples all demonstrate possible uses of a C<Future>
object to provide a fictional asynchronous API.
For more examples, comparing the use of C<Future> with regular call/return
style Perl code, see also L<Future::Phrasebook>.
=head2 Providing Results
By returning a new C<Future> object each time the asynchronous function is
called, it provides a placeholder for its eventual result, and a way to
indicate when it is complete.
sub foperation
{
my %args = @_;
my $future = Future->new;
do_something_async(
foo => $args{foo},
on_done => sub { $future->done( @_ ); },
);
return $future;
}
In most cases, the C<done> method will simply be invoked with the entire
result list as its arguments. In that case, it is convenient to use the
L<curry> module to form a C<CODE> reference that would invoke the C<done>
method.
my $future = Future->new;
do_something_async(
foo => $args{foo},
on_done => $future->curry::done,
);
The caller may then use this future to wait for a result using the C<on_ready>
method, and obtain the result using C<get>.
( run in 0.939 second using v1.01-cache-2.11-cpan-cdf2f3d4e48 )