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>