/home/users/khuck/src/hpx-lsu/hpx/lcos/promise.hpp

//  Copyright (c) 2007-2015 Hartmut Kaiser

//  Copyright (c) 2016      Thomas Heller

//  Copyright (c) 2011      Bryce Adelstein-Lelbach

//

//  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)

#ifndef HPX_LCOS_PROMISE_HPP

#define HPX_LCOS_PROMISE_HPP

#include <hpx/config.hpp>

#include <hpx/lcos/detail/promise_base.hpp>

#include <boost/exception_ptr.hpp>

#include <utility>

namespace hpx {

namespace lcos {

    ///////////////////////////////////////////////////////////////////////////

    /// A promise can be used by a single \a thread to invoke a

    /// (remote) action and wait for the result. The result is expected to be

    /// sent back to the promise using the LCO's set_event action

    ///

    /// A promise is one of the simplest synchronization primitives

    /// provided by HPX. It allows to synchronize on a eager evaluated remote

    /// operation returning a result of the type \a Result. The \a promise

    /// allows to synchronize exactly one \a thread (the one passed during

    /// construction time).

    ///

    /// \code

    ///     // Create the promise (the expected result is a id_type)

    ///     lcos::promise<naming::id_type> p;

    ///

    ///     // Get the associated future

    ///     future<naming::id_type> f = p.get_future();

    ///

    ///     // initiate the action supplying the promise as a

    ///     // continuation

    ///     apply<some_action>(new continuation(p.get_id()), ...);

    ///

    ///     // Wait for the result to be returned, yielding control

    ///     // in the meantime.

    ///     naming::id_type result = f.get();

    ///     // ...

    /// \endcode

    ///

    /// \tparam Result   The template parameter \a Result defines the type this

    ///                  promise is expected to return from

    ///                  \a promise#get.

    /// \tparam RemoteResult The template parameter \a RemoteResult defines the

    ///                  type this promise is expected to receive

    ///                  from the remote action.

    ///

    /// \note            The action executed by the promise must return a value

    ///                  of a type convertible to the type as specified by the

    ///                  template parameter \a RemoteResult

    ///////////////////////////////////////////////////////////////////////////

    template <typename Result, typename RemoteResult>

    class promise

      : public detail::promise_base<

            Result, RemoteResult, detail::promise_data<Result> >

    {

        HPX_MOVABLE_ONLY(promise);

        typedef detail::promise_base<

                Result, RemoteResult, detail::promise_data<Result>

           > base_type;

    public:

        // Effects: constructs a promise object and a shared state.

        promise()

          : base_type()

        {}

        // Effects: constructs a new promise object and transfers ownership of

        //          the shared state of other (if any) to the newly-

        //          constructed object.

        // Postcondition: other has no shared state.

        promise(promise&& other) HPX_NOEXCEPT : base_type(std::move(other))

        {}

        // Effects: Abandons any shared state

        ~promise()

        {

        }

        // Effects: Abandons any shared state (30.6.4) and then as if

        //          promise(std::move(other)).swap(*this).

        // Returns: *this.

        promise& operator=(promise&& other) HPX_NOEXCEPT

        {

            base_type::operator=(std::move(other));

            return *this;

        }

        // Effects: Exchanges the shared state of *this and other.

        // Postcondition: *this has the shared state (if any) that other had

        //                prior to the call to swap. other has the shared state

        //                (if any) that *this had prior to the call to swap.

        void swap(promise& other) HPX_NOEXCEPT

        {

            base_type::swap(other);

        }

        // Returns: true only if *this refers to a shared state.

        using base_type::valid;

        // Returns: A future<Result> object with the same shared state as *this.

        // Throws: future_error if *this has no shared state or if get_future

        //         has already been called on a promise with the same shared

        //         state as *this.

        // Error conditions:

        //   - future_already_retrieved if get_future has already been called

        //     on a promise with the same shared state as *this.

        //   - no_state if *this has no shared state.

        using base_type::get_future;

        // Effects: atomically stores the value r in the shared state and makes

        //          that state ready (30.6.4).

        // Throws:

        //   - future_error if its shared state already has a stored value or

        //     exception.

        // Error conditions:

        //   - promise_already_satisfied if its shared state already has a

        //     stored value or exception.

        //   - no_state if *this has no shared state.

        using base_type::set_value;

        // Effects: atomically stores the exception pointer p in the shared

        //          state and makes that state ready (30.6.4).

        // Throws: future_error if its shared state already has a stored value

        //         or exception.

        // Error conditions:

        //   - promise_already_satisfied if its shared state already has a

        //     stored value or exception.

        //   - no_state if *this has no shared state.

        using base_type::set_exception;

    };

    template <>

    class promise<void, hpx::util::unused_type>

      : public detail::promise_base<

            void, hpx::util::unused_type, detail::promise_data<void> >

    {

        HPX_MOVABLE_ONLY(promise);

        typedef detail::promise_base<

                void, hpx::util::unused_type, detail::promise_data<void>

            > base_type;

    public:

        // Effects: constructs a promise object and a shared state.

        promise()

          : base_type()

        {}

        // Effects: constructs a new promise object and transfers ownership of

        //          the shared state of other (if any) to the newly-

        //          constructed object.

        // Postcondition: other has no shared state.

        promise(promise&& other) HPX_NOEXCEPT : base_type(std::move(other))

        {}

        // Effects: Abandons any shared state

        ~promise()

        {}

        // Effects: Abandons any shared state (30.6.4) and then as if

        //          promise(std::move(other)).swap(*this).

        // Returns: *this.

        promise& operator=(promise&& other) HPX_NOEXCEPT

        {

            base_type::operator=(std::move(other));

            return *this;

        }

        // Effects: Exchanges the shared state of *this and other.

        // Postcondition: *this has the shared state (if any) that other had

        //                prior to the call to swap. other has the shared state

        //                (if any) that *this had prior to the call to swap.

        void swap(promise& other) HPX_NOEXCEPT

        {

            base_type::swap(other);

        }

        // Returns: true only if *this refers to a shared state.

        using base_type::valid;

        // Returns: A future<Result> object with the same shared state as *this.

        // Throws: future_error if *this has no shared state or if get_future

        //         has already been called on a promise with the same shared

        //         state as *this.

        // Error conditions:

        //   - future_already_retrieved if get_future has already been called

        //     on a promise with the same shared state as *this.

        //   - no_state if *this has no shared state.

        using base_type::get_future;

        // Effects: atomically stores the value r in the shared state and makes

        //          that state ready (30.6.4).

        // Throws:

        //   - future_error if its shared state already has a stored value or

        //     exception, or

        //   - any exception thrown by the constructor selected to copy an

        //     object of R.

        // Error conditions:

        //   - promise_already_satisfied if its shared state already has a

        //     stored value or exception.

        //   - no_state if *this has no shared state.

        void set_value(error_code& ec = throws)

        {

            base_type::set_value(hpx::util::unused, ec);

        }

        // Effects: atomically stores the exception pointer p in the shared

        //          state and makes that state ready (30.6.4).

        // Throws: future_error if its shared state already has a stored value

        //         or exception.

        // Error conditions:

        //   - promise_already_satisfied if its shared state already has a

        //     stored value or exception.

        //   - no_state if *this has no shared state.

        using base_type::set_exception;

    };

    template <typename Result, typename RemoteResult>

    void swap(promise<Result, RemoteResult>& x,

        promise<Result, RemoteResult>&       y) HPX_NOEXCEPT

    {

        x.swap(y);

    }

}}

#endif /*HPX_LCOS_PROMISE_HPP*/