123456789101112131415161718192021222324252627282930313233343536373839404142434445464748495051525354555657585960616263646566676869707172737475767778798081828384858687888990919293949596979899100101102103104105106107108109110111112113114115116117118119120121122123124125126127128129130131132133134135136137138139140141142143144145146147148149150151152153154155156157158159160161162163164165166167168169170171172173174175176177178179180181182183184185186187188189190191192 |
- [/
- Copyright Oliver Kowalke 2013.
- Distributed under the Boost Software License, Version 1.0.
- (See accompanying file LICENSE_1_0.txt or copy at
- http://www.boost.org/LICENSE_1_0.txt
- ]
- [#class_packaged_task]
- [section:packaged_task Template `packaged_task<>`]
- A __packaged_task__ wraps a callable target that returns a value so that the
- return value can be computed asynchronously.
- Conventional usage of `packaged_task<>` is like this:
- # Instantiate `packaged_task<>` with template arguments matching the signature
- of the callable. Pass the callable to the [link packaged_task_packaged_task
- constructor].
- # Call [member_link packaged_task..get_future] and capture the returned
- [template_link future] instance.
- # Launch a [class_link fiber] to run the new `packaged_task<>`, passing any
- arguments required by the original callable.
- # Call [member_link fiber..detach] on the newly-launched `fiber`.
- # At some later point, retrieve the result from the `future<>`.
- This is, in fact, pretty much what [ns_function_link fibers..async]
- encapsulates.
- #include <boost/fiber/future/packaged_task.hpp>
- namespace boost {
- namespace fibers {
- template< class R, typename ... Args >
- class packaged_task< R( Args ... ) > {
- public:
- packaged_task() noexcept;
- template< typename Fn >
- explicit packaged_task( Fn &&);
- template< typename Fn, typename __Allocator__ >
- packaged_task( __allocator_arg_t__, Allocator const&, Fn &&);
- packaged_task( packaged_task &&) noexcept;
- packaged_task & operator=( packaged_task &&) noexcept;
- packaged_task( packaged_task const&) = delete;
- packaged_task & operator=( packaged_task const&) = delete;
- ~packaged_task();
- void swap( packaged_task &) noexcept;
- bool valid() const noexcept;
- future< R > get_future();
- void operator()( Args ...);
- void reset();
- };
- template< typename Signature >
- void swap( packaged_task< Signature > &, packaged_task< Signature > &) noexcept;
- }}
- [heading Default constructor `packaged_task()`]
- packaged_task() noexcept;
- [variablelist
- [[Effects:] [Constructs an object of class `packaged_task` with no [link
- shared_state shared state].]]
- [[Throws:] [Nothing.]]
- ]
- [#packaged_task_packaged_task]
- [heading Templated constructor `packaged_task()`]
- template< typename Fn >
- explicit packaged_task( Fn && fn);
- template< typename Fn, typename __Allocator__ >
- packaged_task( __allocator_arg_t__, Allocator const& alloc, Fn && fn);
- [variablelist
- [[Effects:] [Constructs an object of class `packaged_task` with a [link
- shared_state shared state] and copies or moves the callable target `fn` to
- internal storage.]]
- [[Throws:] [Exceptions caused by memory allocation.]]
- [[Note:] [The signature of `Fn` should have a return type convertible to `R`.]]
- [[See also:] [__allocator_arg_t__]]
- ]
- [heading Move constructor]
- packaged_task( packaged_task && other) noexcept;
- [variablelist
- [[Effects:] [Creates a packaged_task by moving the [link shared_state shared
- state] from `other`.]]
- [[Postcondition:] [`other` contains no valid shared state.]]
- [[Throws:] [Nothing.]]
- ]
- [heading Destructor]
- ~packaged_task();
- [variablelist
- [[Effects:] [Destroys `*this` and abandons the [link shared_state shared
- state] if shared state is ready; otherwise stores __future_error__ with error
- condition __broken_promise__ as if by [member_link promise..set_exception]:
- the shared state is set ready.]]
- ]
- [operator_heading packaged_task..operator_assign..operator=]
- packaged_task & operator=( packaged_task && other) noexcept;
- [variablelist
- [[Effects:] [Transfers the ownership of [link shared_state shared state] to
- `*this`.]]
- [[Postcondition:] [`other` contains no valid shared state.]]
- [[Throws:] [Nothing.]]
- ]
- [member_heading packaged_task..swap]
- void swap( packaged_task & other) noexcept;
- [variablelist
- [[Effects:] [Swaps the [link shared_state shared state] between other and
- `*this`.]]
- [[Throws:] [Nothing.]]
- ]
- [member_heading packaged_task..valid]
- bool valid() const noexcept;
- [variablelist
- [[Effects:] [Returns `true` if `*this` contains a [link shared_state shared
- state].]]
- [[Throws:] [Nothing.]]
- ]
- [member_heading packaged_task..get_future]
- future< R > get_future();
- [variablelist
- [[Returns:] [A __future__ with the same [link shared_state shared state].]]
- [[Throws:] [__future_error__ with __already_retrieved__ or __no_state__.]]
- ]
- [operator_heading packaged_task..operator_apply..operator()]
- void operator()( Args && ... args);
- [variablelist
- [[Effects:] [Invokes the stored callable target. Any exception thrown by the
- callable target `fn` is stored in the [link shared_state shared state] as if
- by [member_link promise..set_exception]. Otherwise, the value returned by `fn`
- is stored in the shared state as if by [member_link promise..set_value].]]
- [[Throws:] [__future_error__ with __no_state__.]]
- ]
- [member_heading packaged_task..reset]
- void reset();
- [variablelist
- [[Effects:] [Resets the [link shared_state shared state] and abandons the
- result of previous executions. A new shared state is constructed.]]
- [[Throws:] [__future_error__ with __no_state__.]]
- ]
- [function_heading_for swap..packaged_task]
- template< typename Signature >
- void swap( packaged_task< Signature > & l, packaged_task< Signature > & r) noexcept;
- [variablelist
- [[Effects:] [Same as `l.swap( r)`.]]
- ]
- [endsect]
|