Future.h

Go to the documentation of this file.

/*
* Copyright Onix Solutions Limited [OnixS]. All rights reserved.
*
* This software owned by Onix Solutions Limited [OnixS] and is protected by copyright law
* and international copyright treaties.
*
* Access to and use of the software is governed by the terms of the applicable OnixS Software
* Services Agreement (the Agreement) and Customer end user license agreements granting
* a non-assignable, non-transferable and non-exclusive license to use the software
* for it's own data processing purposes under the terms defined in the Agreement.
*
* Except as otherwise granted within the terms of the Agreement, copying or reproduction of any part
* of this source code or associated reference material to any other location for further reproduction
* or redistribution, and any amendments to this copyright notice, are expressly prohibited.
*
* Any reproduction or redistribution for sale or hiring of the Software not in accordance with
* the terms of the Agreement is a violation of copyright law.
*/
#pragma once

#include <OnixS/CboeCFE/Trading/BOE/ABI.h>

#ifdef ONIXS_BATS_BOE_CXX11
#  include <utility>
#  include <exception>
#endif

namespace OnixS {
namespace System {
    class FutureSharedState;
}}

namespace OnixS {
namespace CboeCFE {
namespace Trading {
namespace BOE {
namespace Threading
{

/// State of a \c SharedFuture object (similar to std::future_status, @see http://en.cppreference.com/w/cpp/thread/future_status ).
struct FutureStatus
{
    enum Enum
    {
        /// the shared state is ready.
        ready,
        /// the shared state did not become ready before specified timeout duration has passed.
        timeout,
        /// the shared state contains a deferred function, so the result will be computed only when explicitly requested.
        deferred
    };
};

namespace Implementation {

class FutureHelper;

/// Base implementation of SharedFuture<T>.
class FutureBase
{
public:
    /// Check if a future instance is associated with an asynchronous result.
    ///
    /// Returns \c true if the *this has an associated asynchronous result, false otherwise.
    bool valid() const ONIXS_BATS_BOE_NOEXCEPT
    {
        return state_ != ONIXS_BATS_BOE_NULLPTR;
    }

    /// Returns \c true if the asynchronous result associated with this Future is ready
    /// (has a value or exception stored in the shared state), \c false otherwise.
    ///
    /// There are often situations where a \c get() call on a Future may not be a blocking call,
    /// or is only a blocking call under certain circumstances.
    /// This method gives the ability to test for early completion and allows us to avoid
    /// associating a continuation, which needs to be scheduled with some non-trivial overhead
    /// and near-certain loss of cache efficiency.
    ///
    /// @throw std::logic_error if this instance does not refer to a shared state.
    ONIXS_CBOE_CFE_BOE_API bool is_ready() const;

    /// Returns \c true if the asynchronous result associated with this Future has a stored value,
    ///         \c false otherwise.
    ///
    /// @throw std::logic_error if this instance does not refer to a shared state.
    ONIXS_CBOE_CFE_BOE_API bool has_value() const;

    /// Returns \c true if the asynchronous result associated with this Future has a stored exception,
    ///         \c false otherwise.
    ///
    /// @throw std::logic_error if this instance does not refer to a shared state.
    ONIXS_CBOE_CFE_BOE_API bool has_exception() const;

    enum
    {
        InfiniteTimeout = -1
    };

    /// Waits for the result to become available during the timeout.
    ///
    /// \note Calling \c wait on the same Future from multiple threads is \e not safe;
    /// the intended use is for each thread that waits on the same shared state to have a \e copy of a Future.
    ///
    /// \throw std::logic_error if this instance does not refer to a shared state.
    ONIXS_CBOE_CFE_BOE_API FutureStatus::Enum wait(int timeoutInMs) const;

protected:
    FutureBase()
      : state_()
    {}

    ONIXS_CBOE_CFE_BOE_API FutureBase(const FutureBase &other) ONIXS_BATS_BOE_NOEXCEPT;

    ONIXS_CBOE_CFE_BOE_API FutureBase &operator=(const FutureBase &other) ONIXS_BATS_BOE_NOEXCEPT;

#ifdef ONIXS_BATS_BOE_CXX11

    ONIXS_CBOE_CFE_BOE_API FutureBase(FutureBase &&other) ONIXS_BATS_BOE_NOEXCEPT;

    ONIXS_CBOE_CFE_BOE_API FutureBase &operator=(FutureBase &&other) ONIXS_BATS_BOE_NOEXCEPT;

#endif

    struct moving_init_t
    {};

    /// Initializes the instance with shared state.
    ONIXS_CBOE_CFE_BOE_API FutureBase(const System::FutureSharedState *state) ONIXS_BATS_BOE_NOEXCEPT;

    /// Initializes the instance with shared state.
    ONIXS_CBOE_CFE_BOE_API FutureBase(const System::FutureSharedState *state, moving_init_t) ONIXS_BATS_BOE_NOEXCEPT;

    /// Destroys a future object.
    ///
    /// If this is the last reference to the asynchronous result associated with *this (if any), then destroy that asynchronous result.
    ONIXS_CBOE_CFE_BOE_API ~FutureBase() ONIXS_BATS_BOE_NOEXCEPT;

    ONIXS_CBOE_CFE_BOE_API void swap(FutureBase &other) ONIXS_BATS_BOE_NOEXCEPT;

    ONIXS_CBOE_CFE_BOE_API const void *getValuePtr() const;

    ONIXS_CBOE_CFE_BOE_API void getVoid() const;

private:
    const System::FutureSharedState *state_;

    friend class FutureHelper;
};

template <typename T>
struct FutureGetReturn
{
    typedef const T &Type;
};

template <>
struct FutureGetReturn<void>
{
    typedef void Type;
};

}

/// Represents a future result of an asynchronous operation - a result that will eventually appear in the Future after
/// the processing is complete.
///
/// The class template Future provides a mechanism to access the result of \e asynchronous operations :
/// \li An asynchronous operation (e.g. created via Promise) can provide a Future object to the creator of that asynchronous
/// operation (e.g. via Promise::get_future).
/// \li The creator of the asynchronous operation can then use a variety of methods to query, wait for, or extract a value from Future.
/// These methods may block if the asynchronous operation has not yet provided a value.
/// \li When the asynchronous operation is ready to send a result to the creator, it can do so by modifying <em> shared state </em>
/// (e.g. via Promise::set_value) that is linked to the creator's Future.
///
/// Future is the synchronization object constructed around the \e receiving end of the Promise channel. It allows for the separation
/// of the initiation of an operation and the act of waiting for its result.
///
/// Future is \e copiable and multiple SharedFuture objects may refer to the same shared state.
///
/// Unlike std::future, this implementation has an extended API, allowing you to query the state of SharedFuture.
/// The internal implementation is lock-free; therefore, setting and polling states do not lead to blocking of threads and/or switching
/// of an execution context.
///
/// \note Access to the same shared state from multiple threads is safe if each thread does it through its own copy of
/// a SharedFuture object.
///
/// \see http://en.cppreference.com/w/cpp/thread/shared_future .
template <typename T>
class SharedFuture : public Implementation::FutureBase
{
public:
    SharedFuture() ONIXS_BATS_BOE_NOEXCEPT
      : FutureBase() {}

    /// Copy constructor.
    SharedFuture(const SharedFuture<T> &other) ONIXS_BATS_BOE_NOEXCEPT
      : FutureBase(other) {}

    /// Copy assignment.
    SharedFuture<T> &operator=(const SharedFuture<T> &other) ONIXS_BATS_BOE_NOEXCEPT
    {
        FutureBase::operator=(other);
        return *this;
    }

#ifdef ONIXS_BATS_BOE_CXX11

    SharedFuture(SharedFuture<T> &&other) ONIXS_BATS_BOE_NOEXCEPT
      : FutureBase(std::move(other))
    {}

    FutureBase &operator=(SharedFuture<T> &&other) ONIXS_BATS_BOE_NOEXCEPT
    {
        FutureBase::operator=(std::move(other));
        return *this;
    }

#endif

    /// Returns the result. If the result is not ready, the method will block. When completes, it either returns a value or throws an exception.
    ///
    /// This method waits until the Future has a valid result and retrieves it. It effectively calls wait() in order to wait for the result.
    ///
    /// \exception If an exception was stored in the shared state referenced by this Future (e.g. via a call to Promise::set_exception()) then that exception will be thrown.
    typename Implementation::FutureGetReturn<T>::Type get() const
    {
        return *reinterpret_cast<const T *>(getValuePtr());
    }

    /// swaps two SharedFuture objects
    void swap(SharedFuture<T> &other) ONIXS_BATS_BOE_NOEXCEPT
    {
        FutureBase::swap(other);
    }

private:
    /// Initializes the instance with shared state.
    SharedFuture(const System::FutureSharedState *state)
      : FutureBase(state)
    {}

    /// Initializes the instance with shared state.
    SharedFuture(const System::FutureSharedState *state, moving_init_t t) ONIXS_BATS_BOE_NOEXCEPT
      : FutureBase(state, t) {}

    friend class Implementation::FutureHelper;
};

template <>
inline void SharedFuture<void>::get() const
{
    getVoid();
}

}}}}}