[/
          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.

        template< class R >
        class packaged_task< R() >
        {
        public:
            packaged_task() noexcept;

            template< typename Fn >
            explicit packaged_task( Fn && fn);

            template< typename Fn, typename Allocator >
            explicit packaged_task( boost::allocator_arg_t, Allocator const& alloc, Fn && fn);

            packaged_task( packaged_task && other) noexcept;

            packaged_task( packaged_task const& other) = delete;

            ~packaged_task();

            packaged_task & operator=( packaged_task && other) noexcept;

            packaged_task & operator=( packaged_task const& other) = delete;

            void swap( packaged_task & other) noexcept;

            operator safe_bool() const noexcept;

            bool operator!() const noexcept;

            bool valid() const noexcept;

            future< R > get_future();

            void operator()();

            void reset();
        };

[heading Default constructor `packaged_task()`]

        packaged_task();

[variablelist
[[Effects:] [Constructs an object of class `packaged_task` with no shared state.]]
[[Throws:] [Nothing.]]
]

[heading Templated constructor `template<> packaged_task()`]

        template< typename Fn >
        explicit packaged_task( Fn && fn);
        
        template< typename Fn, typename Allocator >
        explicit packaged_task( boost::allocator_arg_t, Allocator const& alloc, Fn && fn);

[variablelist
[[Effects:] [Constructs an object of class `packaged_task` with a shared state
and stores the callable target `fn` internally.]]
[[Throws:] [Nothing.]]
[[Note:] [The signature of `Fn` should have a return type convertible to `R`.]]
]

[heading Move constructor]

        packaged_task( packaged_task && other) noexcept;

[variablelist
[[Effects:] [Creates a packaged_task by moving the shared state from `other`.]]
[[Postcondition:] [`other` contains no valid shared state.]]
[[Throws:] [Nothing.]]
]

[heading Destructor]

        ~packaged_task();

[variablelist
[[Effects:] [Destroys `*this` and abandons the shared state if shared state is
ready; otherwise stores __future_error__ with error condition __broken_promise__.]]
[[Throws:] [Nothing.]]
]

[operator_heading packaged_task..operator_assign..operator=]

        packaged_task & operator=( packaged_task && other) noexcept;

[variablelist
[[Effects:] [Transfers the ownership of 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 shared state between other and `*this`.]]
[[Throws:] [Nothing.]]
]

[member_heading packaged_task..operator safe_bool]

        operator safe_bool() const noexcept;

[variablelist
[[Effects:] [Returns `true` if `*this` contains a non-empty shared state.]]
[[Throws:] [Nothing.]]
]

[operator_heading packaged_task..operator_not..operator!]

        bool operator!() const noexcept;

[variablelist
[[Effects:] [Returns `true` if `*this` contains an empty shared state.]]
[[Throws:] [Nothing.]]
]

[member_heading packaged_task..valid]

        bool valid() const noexcept;

[variablelist
[[Effects:] [Returns `true` if `*this` contains a shared state.]]
[[Throws:] [Nothing.]]
]

[member_heading packaged_task..get_future]

        future< R > get_future();

[variablelist
[[Returns:] [A __future__ with the same shared state.]]
[[Throws:] [__future_error__ with __already_retrieved__ or __no_state__.]]
]

[operator_heading packaged_task..operator_apply..operator()]

        void operator()();

[variablelist
[[Effects:] [Invokes the stored callable target. Any exception thrown by the
callable target `fn` is stored in the shared state. Otherwise, the value returned
by `fn` is stored in the shared state.]]
[[Throws:] [__future_error__ with __no_state__.]]
]

[member_heading packaged_task..reset]

        void reset();

[variablelist
[[Effects:] [Resets the shared state and abondons the result of previous
executions. A new shared state is constructed.]]
[[Throws:] [__future_error__ with __no_state__.]]
]

[endsect]