A mutex object facilitates protection against data races and allows thread-safe
synchronization of data between threads. A thread obtains ownership of a
mutex object by calling one of the lock functions and relinquishes ownership
by calling the corresponding unlock function. Mutexes may be either recursive
or non-recursive, and may grant simultaneous ownership to one or many threads.
Boost.Thread supplies recursive and non-recursive
mutexes with exclusive ownership semantics, along with a shared ownership
(multiple-reader / single-writer) mutex.

The SharedLockable concept is a refinement
of the TimedLockable concept that allows
for shared ownership as well as exclusive
ownership. This is the standard multiple-reader / single-write
model: at most one thread can have exclusive ownership, and if any thread
does have exclusive ownership, no other threads can have shared or exclusive
ownership. Alternatively, many threads may have shared ownership.

Attempt to obtain shared ownership for the current thread. Blocks
until shared ownership can be obtained, or the specified time is
reached. If the specified time has already passed, behaves as
try_lock_shared().

Returns:

true if shared ownership
was acquired for the current thread, false
otherwise.

Postcondition:

If the call returns true,
the current thread has shared ownership of *this.

The UpgradeLockable concept is a refinement
of the SharedLockable concept that allows
for upgradable ownership as well as shared
ownership and exclusive ownership. This
is an extension to the multiple-reader / single-write model provided by
the SharedLockable concept: a single
thread may have upgradable ownership at the same time
as others have shared ownership. The thread with
upgradable ownership may at any time attempt to upgrade
that ownership to exclusive ownership. If no other
threads have shared ownership, the upgrade is completed immediately, and
the thread now has exclusive ownership, which must
be relinquished by a call to unlock(),
just as if it had been acquired by a call to lock().

If a thread with upgradable ownership tries to upgrade
whilst other threads have shared ownership, the attempt
will fail and the thread will block until exclusive ownership
can be acquired.

Ownership can also be downgraded as well as upgraded:
exclusive ownership of an implementation of the UpgradeLockable concept can be
downgraded to upgradable ownership or shared ownership, and upgradable
ownership can be downgraded to plain shared ownership.

Lock ownership acquired through a call to lock_upgrade()
must be released through a call to unlock_upgrade().
If the ownership type is changed through a call to one of the unlock_xxx_and_lock_yyy()
functions, ownership must be released through a call to the unlock function
corresponding to the new level of ownership.

Atomically releases upgrade ownership of *this by the current thread and acquires
exclusive ownership of *this. If any other threads have
shared ownership, blocks until exclusive ownership can be acquired.

boost::unique_lock is more complex than
boost::lock_guard:
not only does it provide for RAII-style locking, it also allows for deferring
acquiring the lock until the lock()
member function is called explicitly, or trying to acquire the lock in
a non-blocking fashion, or with a timeout. Consequently, unlock()
is only called in the destructor if the lock object has locked the Lockable object, or otherwise
adopted a lock on the Lockable object.

The member functions of boost::unique_lock are not thread-safe.
In particular, boost::unique_lock is intended to model
the ownership of a Lockable object by a particular
thread, and the member functions that release ownership of the lock state
(including the destructor) must be called by the same thread that acquired
ownership of the lock state.

The association between *this and the Lockable object is removed,
without affecting the lock state of the Lockable object. If owns_lock()
would have returned true,
it is the responsibility of the calling code to ensure that the
Lockable is correctly
unlocked.

Returns:

A pointer to the Lockable object associated
with *this
at the point of the call, or NULL
if there is no such object.

Like boost::unique_lock, not only does it
provide for RAII-style locking, it also allows for deferring acquiring
the lock until the lock()
member function is called explicitly, or trying to acquire the lock in
a non-blocking fashion, or with a timeout. Consequently, unlock()
is only called in the destructor if the lock object has locked the Lockable object, or otherwise
adopted a lock on the Lockable object.

The member functions of boost::shared_lock are not thread-safe.
In particular, boost::shared_lock is intended to model
the shared ownership of a Lockable object by a particular
thread, and the member functions that release ownership of the lock state
(including the destructor) must be called by the same thread that acquired
ownership of the lock state.

The association between *this and the Lockable object is removed,
without affecting the lock state of the Lockable object. If owns_lock()
would have returned true,
it is the responsibility of the calling code to ensure that the
Lockable is correctly
unlocked.

Returns:

A pointer to the Lockable object associated
with *this
at the point of the call, or NULL
if there is no such object.

Like boost::unique_lock, not only does it
provide for RAII-style locking, it also allows for deferring acquiring
the lock until the lock()
member function is called explicitly, or trying to acquire the lock in
a non-blocking fashion, or with a timeout. Consequently, unlock()
is only called in the destructor if the lock object has locked the Lockable object, or otherwise
adopted a lock on the Lockable object.

The member functions of boost::upgrade_lock are not thread-safe.
In particular, boost::upgrade_lock is intended to model
the upgrade ownership of a Lockable object by a particular
thread, and the member functions that release ownership of the lock state
(including the destructor) must be called by the same thread that acquired
ownership of the lock state.

The member typedef scoped_try_lock
is provided for each distinct MutexType
as a typedef to a class with the preceding definition. The semantics of
each constructor and member function are identical to those of boost::unique_lock<MutexType>
for the same MutexType,
except that the constructor that takes a single reference to a mutex will
call m.try_lock() rather than m.lock().

Locks the Lockable objects supplied
as arguments in an unspecified and indeterminate order in a way that
avoids deadlock. It is safe to call this function concurrently from
multiple threads with the same mutexes (or other lockable objects)
in different orders without risk of deadlock. If any of the lock()
or try_lock()
operations on the supplied Lockable objects throws
an exception any locks acquired by the function will be released
before the function exits.

Locks all the Lockable objects in the
supplied range in an unspecified and indeterminate order in a way
that avoids deadlock. It is safe to call this function concurrently
from multiple threads with the same mutexes (or other lockable objects)
in different orders without risk of deadlock. If any of the lock()
or try_lock()
operations on the Lockable objects in the
supplied range throws an exception any locks acquired by the function
will be released before the function exits.

Calls try_lock()
on each of the Lockable objects supplied
as arguments. If any of the calls to try_lock()
returns false then all
locks acquired are released and the zero-based index of the failed
lock is returned.

If any of the try_lock()
operations on the supplied Lockable objects throws
an exception any locks acquired by the function will be released
before the function exits.

Returns:

-1
if all the supplied Lockable objects are now
locked by the calling thread, the zero-based index of the object
which could not be locked otherwise.

Calls try_lock()
on each of the Lockable objects in the
supplied range. If any of the calls to try_lock()
returns false then all
locks acquired are released and an iterator referencing the failed
lock is returned.

If any of the try_lock()
operations on the supplied Lockable objects throws
an exception any locks acquired by the function will be released
before the function exits.

Returns:

end if all the supplied
Lockable objects are now
locked by the calling thread, an iterator referencing the object
which could not be locked otherwise.

Returns an instance of native_handle_type
that can be used with platform-specific APIs to manipulate the
underlying implementation. If no such instance exists, native_handle()
and native_handle_type
are not present.

Returns an instance of native_handle_type
that can be used with platform-specific APIs to manipulate the
underlying implementation. If no such instance exists, native_handle()
and native_handle_type
are not present.

Returns an instance of native_handle_type
that can be used with platform-specific APIs to manipulate the
underlying implementation. If no such instance exists, native_handle()
and native_handle_type
are not present.

Returns an instance of native_handle_type
that can be used with platform-specific APIs to manipulate the
underlying implementation. If no such instance exists, native_handle()
and native_handle_type
are not present.

The classes condition_variable
and condition_variable_any
provide a mechanism for one thread to wait for notification from another
thread that a particular condition has become true. The general usage pattern
is that one thread locks a mutex and then calls wait
on an instance of condition_variable
or condition_variable_any.
When the thread is woken from the wait, then it checks to see if the appropriate
condition is now true, and continues if so. If the condition is not true,
then the thread then calls wait
again to resume waiting. In the simplest case, this condition is just a boolean
variable:

Notice that the lock is passed
to wait: wait
will atomically add the thread to the set of threads waiting on the condition
variable, and unlock the mutex. When the thread is woken, the mutex will
be locked again before the call to wait
returns. This allows other threads to acquire the mutex in order to update
the shared data, and ensures that the data associated with the condition
is correctly synchronized.

In the mean time, another thread sets the condition to true,
and then calls either notify_one
or notify_all on the condition
variable to wake one waiting thread or all the waiting threads respectively.

Note that the same mutex is locked before the shared data is updated, but
that the mutex does not have to be locked across the call to notify_one.

This example uses an object of type condition_variable,
but would work just as well with an object of type condition_variable_any:
condition_variable_any is
more general, and will work with any kind of lock or mutex, whereas condition_variable requires that the lock
passed to wait is an instance
of boost::unique_lock<boost::mutex>.
This enables condition_variable
to make optimizations in some cases, based on the knowledge of the mutex
type; condition_variable_any
typically has a more complex implementation than condition_variable.

lock is locked
by the current thread, and either no other thread is currently
waiting on *this,
or the execution of the mutex() member function on the lock objects supplied in the
calls to wait or
timed_wait in all
the threads currently waiting on *this would return the same value
as lock->mutex()
for this call to wait.

Effects:

Atomically call lock.unlock() and blocks the current thread.
The thread will unblock when notified by a call to this->notify_one()
or this->notify_all(),
or spuriously. When the thread is unblocked (for whatever reason),
the lock is reacquired by invoking lock.lock() before the call to wait returns. The lock is also
reacquired by invoking lock.lock() if the function exits with an
exception.

Postcondition:

lock is locked
by the current thread.

Throws:

boost::thread_resource_error if an error
occurs. boost::thread_interrupted if the wait
was interrupted by a call to interrupt()
on the boost::thread object associated
with the current thread of execution.

lock is locked
by the current thread, and either no other thread is currently
waiting on *this,
or the execution of the mutex() member function on the lock objects supplied in the
calls to wait or
timed_wait in all
the threads currently waiting on *this would return the same value
as lock->mutex()
for this call to wait.

Effects:

Atomically call lock.unlock() and blocks the current thread.
The thread will unblock when notified by a call to this->notify_one()
or this->notify_all(),
when the time as reported by boost::get_system_time() would be equal to or later than
the specified abs_time,
or spuriously. When the thread is unblocked (for whatever reason),
the lock is reacquired by invoking lock.lock() before the call to wait returns. The lock is also
reacquired by invoking lock.lock() if the function exits with an
exception.

Returns:

false if the call
is returning because the time specified by abs_time
was reached, true
otherwise.

Postcondition:

lock is locked
by the current thread.

Throws:

boost::thread_resource_error if an error
occurs. boost::thread_interrupted if the wait
was interrupted by a call to interrupt()
on the boost::thread object associated
with the current thread of execution.

lock is locked
by the current thread, and either no other thread is currently
waiting on *this,
or the execution of the mutex() member function on the lock objects supplied in the
calls to wait or
timed_wait in all
the threads currently waiting on *this would return the same value
as lock->mutex()
for this call to wait.

Effects:

Atomically call lock.unlock() and blocks the current thread.
The thread will unblock when notified by a call to this->notify_one()
or this->notify_all(),
after the period of time indicated by the rel_time
argument has elapsed, or spuriously. When the thread is unblocked
(for whatever reason), the lock is reacquired by invoking lock.lock()
before the call to wait
returns. The lock is also reacquired by invoking lock.lock()
if the function exits with an exception.

Returns:

false if the call
is returning because the time period specified by rel_time has elapsed, true otherwise.

Postcondition:

lock is locked
by the current thread.

Throws:

boost::thread_resource_error if an error
occurs. boost::thread_interrupted if the wait
was interrupted by a call to interrupt()
on the boost::thread object associated
with the current thread of execution.

Note

The duration overload of timed_wait is difficult to use correctly.
The overload taking a predicate should be preferred in most cases.

Atomically call lock.unlock() and blocks the current thread.
The thread will unblock when notified by a call to this->notify_one()
or this->notify_all(),
or spuriously. When the thread is unblocked (for whatever reason),
the lock is reacquired by invoking lock.lock() before the call to wait returns. The lock is also
reacquired by invoking lock.lock() if the function exits with an
exception.

Postcondition:

lock is locked
by the current thread.

Throws:

boost::thread_resource_error if an error
occurs. boost::thread_interrupted if the wait
was interrupted by a call to interrupt()
on the boost::thread object associated
with the current thread of execution.

Atomically call lock.unlock() and blocks the current thread.
The thread will unblock when notified by a call to this->notify_one()
or this->notify_all(),
when the time as reported by boost::get_system_time() would be equal to or later than
the specified abs_time,
or spuriously. When the thread is unblocked (for whatever reason),
the lock is reacquired by invoking lock.lock() before the call to wait returns. The lock is also
reacquired by invoking lock.lock() if the function exits with an
exception.

Returns:

false if the call
is returning because the time specified by abs_time
was reached, true
otherwise.

Postcondition:

lock is locked
by the current thread.

Throws:

boost::thread_resource_error if an error
occurs. boost::thread_interrupted if the wait
was interrupted by a call to interrupt()
on the boost::thread object associated
with the current thread of execution.

Atomically call lock.unlock() and blocks the current thread.
The thread will unblock when notified by a call to this->notify_one()
or this->notify_all(),
after the period of time indicated by the rel_time
argument has elapsed, or spuriously. When the thread is unblocked
(for whatever reason), the lock is reacquired by invoking lock.lock()
before the call to wait
returns. The lock is also reacquired by invoking lock.lock()
if the function exits with an exception.

Returns:

false if the call
is returning because the time period specified by rel_time has elapsed, true otherwise.

Postcondition:

lock is locked
by the current thread.

Throws:

boost::thread_resource_error if an error
occurs. boost::thread_interrupted if the wait
was interrupted by a call to interrupt()
on the boost::thread object associated
with the current thread of execution.

Note

The duration overload of timed_wait is difficult to use correctly.
The overload taking a predicate should be preferred in most cases.

Callable is CopyConstructible. Copying func shall have no side effects,
and the effect of calling the copy shall be equivalent to calling
the original.

Effects:

Calls to call_once
on the same once_flag
object are serialized. If there has been no prior effective call_once on the same once_flag object, the argument
func (or a copy thereof)
is called as-if by invoking func(), and the invocation of call_once is effective if and only
if func()
returns without exception. If an exception is thrown, the exception
is propagated to the caller. If there has been a prior effective
call_once on the
same once_flag object,
the call_once returns
without invoking func.

Synchronization:

The completion of an effective call_once
invocation on a once_flag
object, synchronizes with all subsequent call_once
invocations on the same once_flag
object.

Throws:

thread_resource_error
when the effects cannot be achieved. or any exception propagated
from func.

Note:

The function passed to call_once
must not also call call_once
passing the same once_flag
object. This may cause deadlock, or invoking the passed function
a second time. The alternative is to allow the second call to return
immediately, but that assumes the code knows it has been called recursively,
and can proceed even though the call to call_once
didn't actually call the function, in which case it could also avoid
calling call_once
recursively.

voidcall_once(void(*func)(),once_flag&flag);

This second overload is provided for backwards compatibility. The effects
of call_once(func,flag)
shall be the same as those of call_once(flag,func).

A barrier is a simple concept. Also known as a rendezvous,
it is a synchronization point between multiple threads. The barrier is configured
for a particular number of threads (n),
and as threads reach the barrier they must wait until all n
threads have arrived. Once the n-th
thread has reached the barrier, all the waiting threads can proceed, and
the barrier is reset.

An instance of boost::unique_future holds the one and
only reference to a result. Ownership can be transferred between instances
using the move constructor or move-assignment operator, but at most one
instance holds a reference to a given asynchronous result. When the result
is ready, it is returned from boost::unique_future<R>::get()
by rvalue-reference to allow the result to be moved or copied as appropriate
for the type.

You can set the value in a future with either a boost::promise or a boost::packaged_task. A boost::packaged_task is a callable object
that wraps a function or callable object. When the packaged task is invoked,
it invokes the contained function in turn, and populates a future with
the return value. This is an answer to the perennial question: "how
do I return a value from a thread?": package the function you wish
to run as a boost::packaged_task and pass the packaged
task to the thread constructor. The future retrieved from the packaged
task can then be used to obtain the return value. If the function throws
an exception, that is stored in the future in place of the return value.

intcalculate_the_answer_to_life_the_universe_and_everything(){return42;}boost::packaged_task<int>pt(calculate_the_answer_to_life_the_universe_and_everything);boost::unique_future<int>fi=pt.get_future();boost::threadtask(boost::move(pt));// launch task on a threadfi.wait();// wait for it to finishassert(fi.is_ready());assert(fi.has_value());assert(!fi.has_exception());assert(fi.get_state()==boost::future_state::ready);assert(fi.get()==42);

A boost::promise is a bit more low level:
it just provides explicit functions to store a value or an exception in
the associated future. A promise can therefore be used where the value
may come from more than one possible source, or where a single operation
may produce multiple values.

This allows lazy futures where the result is not actually
computed until it is needed by some thread. In the example below, the call
to f.get()
invokes the callback invoke_lazy_task,
which runs the task to set the value. If you remove the call to f.get(), the task is not ever run.

template<typenameR>classunique_future{unique_future(unique_future&rhs);//=delete;unique_future&operator=(unique_future&rhs);//=delete;public:typedeffuture_state::statestate;unique_future();~unique_future();// move supportunique_future(unique_future&&other);unique_future&operator=(unique_future&&other);voidswap(unique_future&other);// retrieving the valueR&&get();// functions to check statestateget_state()const;boolis_ready()const;boolhas_exception()const;boolhas_value()const;// waiting for the result to be readyvoidwait()const;template<typenameDuration>booltimed_wait(Durationconst&rel_time)const;booltimed_wait_until(boost::system_timeconst&abs_time)const;};

Constructs a new future, and transfers ownership of the asynchronous
result associated with other
to *this.

Postconditions:

this->get_state()
returns the value of other->get_state() prior to the call. other->get_state()
returns boost::future_state::uninitialized. If other was associated with an
asynchronous result, that result is now associated with *this.
other is not
associated with any asynchronous result.

Throws:

Nothing.

Notes:

If the compiler does not support rvalue-references, this is implemented
using the boost.thread move emulation.

Transfers ownership of the asynchronous result associated with
other to *this.

Postconditions:

this->get_state()
returns the value of other->get_state() prior to the call. other->get_state()
returns boost::future_state::uninitialized. If other was associated with an
asynchronous result, that result is now associated with *this.
other is not
associated with any asynchronous result. If *this was associated with an asynchronous
result prior to the call, that result no longer has an associated
boost::unique_future instance.

Throws:

Nothing.

Notes:

If the compiler does not support rvalue-references, this is implemented
using the boost.thread move emulation.

Swaps ownership of the asynchronous results associated with
other and *this.

Postconditions:

this->get_state()
returns the value of other->get_state() prior to the call. other->get_state()
returns the value of this->get_state() prior to the call. If other was associated with an
asynchronous result, that result is now associated with *this,
otherwise *this
has no associated result. If *this was associated with an asynchronous
result, that result is now associated with other,
otherwise other
has no associated result.

If *this
is associated with an asynchronous result, waits until the result
is ready as-if by a call to boost::unique_future<R>::wait(),
and retrieves the result (whether that is a value or an exception).

Returns:

If the result type R
is a reference, returns the stored reference. If R is void,
there is no return value. Otherwise, returns an rvalue-reference
to the value stored in the asynchronous result.

boost::future_uninitialized if *this
is not associated with an asynchronous result. boost::thread_interrupted if the result
associated with *this is not ready at the point
of the call, and the current thread is interrupted. Any exception
stored in the asynchronous result in place of a value.

If *this
is associated with an asynchronous result, waits until the result
is ready. If the result is not ready on entry, and the result
has a wait callback set, that callback is
invoked prior to waiting.

Throws:

boost::future_uninitialized if *this
is not associated with an asynchronous result. boost::thread_interrupted if the result
associated with *this is not ready at the point
of the call, and the current thread is interrupted. Any exception
thrown by the wait callback if such a callback
is called.

If *this
is associated with an asynchronous result, waits until the result
is ready, or the time specified by wait_duration
has elapsed. If the result is not ready on entry, and the result
has a wait callback set, that callback is
invoked prior to waiting.

Returns:

true if *this
is associated with an asynchronous result, and that result is
ready before the specified time has elapsed, false
otherwise.

Throws:

boost::future_uninitialized if *this
is not associated with an asynchronous result. boost::thread_interrupted if the result
associated with *this is not ready at the point
of the call, and the current thread is interrupted. Any exception
thrown by the wait callback if such a callback
is called.

If *this
is associated with an asynchronous result, waits until the result
is ready, or the time point specified by wait_timeout
has passed. If the result is not ready on entry, and the result
has a wait callback set, that callback is
invoked prior to waiting.

Returns:

true if *this
is associated with an asynchronous result, and that result is
ready before the specified time has passed, false
otherwise.

Throws:

boost::future_uninitialized if *this
is not associated with an asynchronous result. boost::thread_interrupted if the result
associated with *this is not ready at the point
of the call, and the current thread is interrupted. Any exception
thrown by the wait callback if such a callback
is called.

template<typenameR>classshared_future{public:typedeffuture_state::statestate;shared_future();~shared_future();// copy supportshared_future(shared_futureconst&other);shared_future&operator=(shared_futureconst&other);// move supportshared_future(shared_future&&other);shared_future(unique_future<R>&&other);shared_future&operator=(shared_future&&other);shared_future&operator=(unique_future<R>&&other);voidswap(shared_future&other);// retrieving the valueRget();// functions to check state, and wait for readystateget_state()const;boolis_ready()const;boolhas_exception()const;boolhas_value()const;// waiting for the result to be readyvoidwait()const;template<typenameDuration>booltimed_wait(Durationconst&rel_time)const;booltimed_wait_until(boost::system_timeconst&abs_time)const;};

If *this
is associated with an asynchronous result, waits until the result
is ready as-if by a call to boost::shared_future<R>::wait(),
and returns a const
reference to the result.

Returns:

If the result type R
is a reference, returns the stored reference. If R is void,
there is no return value. Otherwise, returns a const reference to the value stored
in the asynchronous result.

Throws:

boost::future_uninitialized if *this
is not associated with an asynchronous result. boost::thread_interrupted if the result
associated with *this is not ready at the point
of the call, and the current thread is interrupted.

If *this
is associated with an asynchronous result, waits until the result
is ready. If the result is not ready on entry, and the result
has a wait callback set, that callback is
invoked prior to waiting.

Throws:

boost::future_uninitialized if *this
is not associated with an asynchronous result. boost::thread_interrupted if the result
associated with *this is not ready at the point
of the call, and the current thread is interrupted. Any exception
thrown by the wait callback if such a callback
is called.

If *this
is associated with an asynchronous result, waits until the result
is ready, or the time specified by wait_duration
has elapsed. If the result is not ready on entry, and the result
has a wait callback set, that callback is
invoked prior to waiting.

Returns:

true if *this
is associated with an asynchronous result, and that result is
ready before the specified time has elapsed, false
otherwise.

Throws:

boost::future_uninitialized if *this
is not associated with an asynchronous result. boost::thread_interrupted if the result
associated with *this is not ready at the point
of the call, and the current thread is interrupted. Any exception
thrown by the wait callback if such a callback
is called.

If *this
is associated with an asynchronous result, waits until the result
is ready, or the time point specified by wait_timeout
has passed. If the result is not ready on entry, and the result
has a wait callback set, that callback is
invoked prior to waiting.

Returns:

true if *this
is associated with an asynchronous result, and that result is
ready before the specified time has passed, false
otherwise.

Throws:

boost::future_uninitialized if *this
is not associated with an asynchronous result. boost::thread_interrupted if the result
associated with *this is not ready at the point
of the call, and the current thread is interrupted. Any exception
thrown by the wait callback if such a callback
is called.

Transfers ownership of the result associated with other to *this, leaving other
with no associated result. If there was already a result associated
with *this,
and that result was not ready, sets any
futures associated with that result to ready
with a boost::broken_promise
exception as the result.

Throws:

Nothing.

Notes:

If the compiler does not support rvalue-references, this is implemented
using the boost.thread move emulation.

If *this
was not associated with a result, allocate storage for a new
asynchronous result and associate it with *this. Store the value r in the asynchronous result
associated with *this. Any threads blocked waiting
for the asynchronous result are woken.

boost::promise_already_satisfied if
the result associated with *this is already ready.
std::bad_alloc if the memory required
for storage of the result cannot be allocated. Any exception
thrown by the copy or move-constructor of R.

If *this
was not associated with a result, allocate storage for a new
asynchronous result and associate it with *this. Store the exception e in the asynchronous result
associated with *this. Any threads blocked waiting
for the asynchronous result are woken.

The expression f(t) where t
is a lvalue of type boost::packaged_task shall
be well-formed. Invoking a copy of f
shall have the same effect as invoking f

Effects:

Store a copy of f
with the asynchronous result associated with *this as a wait callback.
This will replace any existing wait callback store alongside
that result. If a thread subsequently calls one of the wait functions
on a boost::unique_future or boost::shared_future associated
with this result, and the result is not ready,
f(*this)
shall be invoked.

Throws:

std::bad_alloc if memory cannot
be allocated for the required storage.

Transfers ownership of the task associated with other to *this, leaving other
with no associated task. If there was already a task associated
with *this,
and that task has not been invoked, sets any futures associated
with that task to ready with a boost::broken_promise exception as
the result.

Throws:

Nothing.

Notes:

If the compiler does not support rvalue-references, this is implemented
using the boost.thread move emulation.

boost::task_moved if ownership of
the task associated with *this has been moved to another
instance of boost::packaged_task. boost::future_already_retrieved if
the future associated with the task has already been retrieved.

Invoke the task associated with *this and store the result in the
corresponding future. If the task returns normally, the return
value is stored as the asynchronous result, otherwise the exception
thrown is stored. Any threads blocked waiting for the asynchronous
result associated with this task are woken.

Postconditions:

All futures waiting on the asynchronous result are ready

Throws:

boost::task_moved if ownership of
the task associated with *this has been moved to another
instance of boost::packaged_task. boost::task_already_started if the
task has already been invoked.

The expression f(t) where t
is a lvalue of type boost::packaged_task shall
be well-formed. Invoking a copy of f
shall have the same effect as invoking f

Effects:

Store a copy of f
with the task associated with *this as a wait callback.
This will replace any existing wait callback store alongside
that task. If a thread subsequently calls one of the wait functions
on a boost::unique_future or boost::shared_future associated
with this task, and the result of the task is not ready,
f(*this)
shall be invoked.

Throws:

boost::task_moved if ownership of
the task associated with *this has been moved to another
instance of boost::packaged_task.

The range-based overload returns an Iterator
identifying the first future in the range that was detected as
ready. The remaining overloads return the
zero-based index of the first future that was detected as ready
(first parameter => 0, second parameter => 1, etc.).

Throws:

boost::thread_interrupted if the current
thread is interrupted. Any exception thrown by the wait
callback associated with any of the futures being waited
for. std::bad_alloc if memory could not
be allocated for the internal wait structures.