NAME

Future::XS - experimental XS implementation of Future

SYNOPSIS

my $future = Future::XS->new;

perform_some_operation(
   on_complete => sub {
      $future->done( @_ );
   }
);

$future->on_ready( sub {
   say "The operation is complete";
} );

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 Future distribution and load it automatically in favour of the pureperl implementation on supported systems.

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 Future implementation (regardless of whether or not the perl interpreter is actually built to support threads).

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.

Attempts to access a future instance created in one thread from another thread will raise an exception:

Future::XS instance IO::Async::Future=SCALAR(0x...) is not available in this thread at ...

As a special case for process cleanup activities, the ->cancel method does not throw this exception, but simply returns silently. This is because cleanup code such as DESTROY methods or defer blocks often attempt to call this on existing instances.

AUTHOR

Paul Evans <leonerd@leonerd.org.uk>