13 Asynchronous model [async]

The async_result class template is a customization point for asynchronous operations. Template parameter CompletionToken specifies the model used to obtain the result of the asynchronous operation. Template parameter Signature is the call signature (C++ 2014 [func.def]) for the completion handler type invoked on completion of the asynchronous operation. The async_result template:

• (1.1)

  transforms a CompletionToken into a completion handler type that is based on a Signature; and

• (1.2)

  determines the return type and return value of an asynchronous operation's initiating function.

namespace std {
namespace experimental {
namespace net {
inline namespace v1 {

  template<class CompletionToken, class Signature>
  class async_result
  {
  public:
    using completion_handler_type = CompletionToken;
    using return_type = void;

    explicit async_result(completion_handler_type&) {}
    async_result(const async_result&) = delete;
    async_result& operator=(const async_result&) = delete;

    return_type get() {}
  };

} // inline namespace v1
} // namespace net
} // namespace experimental
} // namespace std

The template parameter CompletionToken shall be an object type. The template parameter Signature shall be a call signature (C++ 2014 [func.def]).

Specializations of async_result shall satisfy the Destructible requirements (C++ 2014 [destructible]) in addition to the requirements in Table [tab:async.async.result.requirements]. In this table, R is a specialization of async_result; r is a modifiable lvalue of type R; and h is a modifiable lvalue of type R::completion_handler_type.

Class template async_completion is provided as a convenience, to simplify the implementation of asynchronous operations that use async_result.

namespace std {
namespace experimental {
namespace net {
inline namespace v1 {

  template<class CompletionToken, class Signature>
  struct async_completion
  {
    using completion_handler_type = async_result<decay_t<CompletionToken>,
      Signature>::completion_handler_type;

    explicit async_completion(CompletionToken& t);
    async_completion(const async_completion&) = delete;
    async_completion& operator=(const async_completion&) = delete;

    see below completion_handler;
    async_result<decay_t<CompletionToken>, Signature> result;
  };

} // inline namespace v1
} // namespace net
} // namespace experimental
} // namespace std

The template parameter Signature shall be a call signature (C++ 2014 [func.def]).

explicit async_completion(CompletionToken& t);

Class template associated_allocator is an associator ([async.reqmts.associator]) for the ProtoAllocator ([async.reqmts.proto.allocator]) type requirements, with default candidate type allocator<void> and default candidate object allocator<void>().

namespace std {
namespace experimental {
namespace net {
inline namespace v1 {

  template<class T, class ProtoAllocator = allocator<void>>
  struct associated_allocator
  {
    using type = see below;

    static type get(const T& t, const ProtoAllocator& a = ProtoAllocator()) noexcept;
  };

} // inline namespace v1
} // namespace net
} // namespace experimental
} // namespace std

Specializations of associated_allocator shall satisfy the requirements in Table [tab:async.assoc.alloc.requirements]. In this table, X is a specialization of associated_allocator for the template parameters T and ProtoAllocator; t is a (possibly const) value of type T; and a is an object of type ProtoAllocator.

Class execution_context implements an extensible, type-safe, polymorphic set of services, indexed by service type.

namespace std {
namespace experimental {
namespace net {
inline namespace v1 {

  class execution_context
  {
  public:
    class service;

    // [async.exec.ctx.cons], construct / copy / destroy:

    execution_context();
    execution_context(const execution_context&) = delete;
    execution_context& operator=(const execution_context&) = delete;
    virtual ~execution_context();

    // [async.exec.ctx.ops], execution context operations:

    void notify_fork(fork_event e);

  protected:

    // [async.exec.ctx.protected], execution context protected operations:

    void shutdown() noexcept;
    void destroy() noexcept;
  };

  // service access:
  template<class Service> typename Service::key_type&
    use_service(execution_context& ctx);
  template<class Service, class... Args> Service&
    make_service(execution_context& ctx, Args&&... args);
  template<class Service> bool has_service(const execution_context& ctx) noexcept;
  class service_already_exists : public logic_error { };

} // inline namespace v1
} // namespace net
} // namespace experimental
} // namespace std

Access to the services of an execution_context is via three function templates, use_service, make_service and has_service.

In a call to use_service<Service>, the type argument chooses a service, identified by Service::key_type, from a set of services in an execution_context. If the service is not present in the execution_context, an object of type Service is created and added to the execution_context. A program can check if an execution_context implements a particular service with the function template has_service<Service>.

Service objects may be explicitly added to an execution_context using the function template make_service<Service>. If the service is already present, make_service exits via an exception of type service_already_exists.

Once a service reference is obtained from an execution_context object by calling use_service, that reference remains usable until a call to destroy().

If a call to a specialization of use_service or make_service recursively calls another specialization of use_service or make_service which would choose the same service (identified by key_type) from the same execution_context, then the behavior is undefined. [ Note: Nested calls to specializations for different service types are well-defined.  — end note ]

The class template is_executor can be used to detect executor types satisfying the Executor ([async.reqmts.executor]) type requirements.

namespace std {
namespace experimental {
namespace net {
inline namespace v1 {

  template<class T> struct is_executor;

} // inline namespace v1
} // namespace net
} // namespace experimental
} // namespace std

T shall be a complete type.

Class template is_executor is a UnaryTypeTrait (C++ 2014 [meta.rqmts]) with a BaseCharacteristic of true_type if the type T meets the syntactic requirements for Executor ([async.reqmts.executor]), otherwise false_type.

The executor_arg_t struct is an empty structure type used as a unique type to disambiguate constructor and function overloading. Specifically, types may have constructors with executor_arg_t as the first argument, immediately followed by an argument of a type that satisfies the Executor requirements ([async.reqmts.executor]).

Class template associated_executor is an associator ([async.reqmts.associator]) for the Executor ([async.reqmts.executor]) type requirements, with default candidate type system_executor and default candidate object system_executor().

namespace std {
namespace experimental {
namespace net {
inline namespace v1 {

  template<class T, class Executor = system_executor>
  struct associated_executor
  {
    using type = see below;

    static type get(const T& t, const Executor& e = Executor()) noexcept;
  };

} // inline namespace v1
} // namespace net
} // namespace experimental
} // namespace std

Specializations of associated_executor shall satisfy the requirements in Table [tab:async.assoc.exec.requirements]. In this table, X is a specialization of associated_executor for the template parameters T and Executor; t is a (possible const) value of T; and e is an object of type Executor.

The class template executor_binder binds executors to objects. A specialization executor_binder<T, Executor> binds an executor of type Executor satisfying the Executor requirements ([async.reqmts.executor]) to an object or function of type T.

namespace std {
namespace experimental {
namespace net {
inline namespace v1 {

  template<class T, class Executor>
  class executor_binder
  {
  public:
    // types:

    using target_type = T;
    using executor_type = Executor;

    // [async.exec.binder.cons], construct / copy / destroy:

    executor_binder(T t, const Executor& ex);
    executor_binder(const executor_binder& other) = default;
    executor_binder(executor_binder&& other) = default;
    template<class U, class OtherExecutor>
      executor_binder(const executor_binder<U, OtherExecutor>& other);
    template<class U, class OtherExecutor>
      executor_binder(executor_binder<U, OtherExecutor>&& other);
    template<class U, class OtherExecutor>
      executor_binder(executor_arg_t, const Executor& ex,
        const executor_binder<U, OtherExecutor>& other);
    template<class U, class OtherExecutor>
      executor_binder(executor_arg_t, const Executor& ex,
        executor_binder<U, OtherExecutor>&& other);

    ~executor_binder();

    // [async.exec.binder.access], executor binder access:

    T& get() noexcept;
    const T& get() const noexcept;
    executor_type get_executor() const noexcept;

    // [async.exec.binder.invocation], executor binder invocation:

    template<class... Args>
      result_of_t<T&(Args&&...)> operator()(Args&&... args);
    template<class... Args>
      result_of_t<const T&(Args&&...)> operator()(Args&&... args) const;

  private:
    Executor ex_; // exposition only
    T target_; // exposition only
  };

  template<class T, class Executor, class Signature>
    class async_result<executor_binder<T, Executor>, Signature>;

  template<class T, class Executor, class ProtoAllocator>
    struct associated_allocator<executor_binder<T, Executor>, ProtoAllocator>;

  template<class T, class Executor, class Executor1>
    struct associated_executor<executor_binder<T, Executor>, Executor1>;

} // inline namespace v1
} // namespace net
} // namespace experimental
} // namespace std

Class system_executor represents a set of rules where function objects are permitted to execute on any thread.

namespace std {
namespace experimental {
namespace net {
inline namespace v1 {

  class system_executor
  {
  public:
    // constructors:

    system_executor() {}

    // [async.system.exec.ops], executor operations:

    system_context& context() const noexcept;

    void on_work_started() const noexcept {}
    void on_work_finished() const noexcept {}

    template<class Func, class ProtoAllocator>
      void dispatch(Func&& f, const ProtoAllocator& a) const;
    template<class Func, class ProtoAllocator>
      void post(Func&& f, const ProtoAllocator& a) const;
    template<class Func, class ProtoAllocator>
      void defer(Func&& f, const ProtoAllocator& a) const;
  };

  bool operator==(const system_executor&, const system_executor&) noexcept;
  bool operator!=(const system_executor&, const system_executor&) noexcept;

} // inline namespace v1
} // namespace net
} // namespace experimental
} // namespace std

Class system_executor satisfies the Destructible (C++ 2014 [destructible]), DefaultConstructible (C++ 2014 [defaultconstructible]), and Executor ([async.reqmts.executor]) type requirements.

To satisfy the Executor requirements for the post and defer member functions, the system executor may create thread objects to run the submitted function objects. These thread objects are collectively referred to as system threads.

Class system_context implements the execution context associated with system_executor objects.

namespace std {
namespace experimental {
namespace net {
inline namespace v1 {

  class system_context : public execution_context
  {
  public:
    // types:

    using executor_type = system_executor;

    // construct / copy / destroy:

    system_context() = delete;
    system_context(const system_context&) = delete;
    system_context& operator=(const system_context&) = delete;
    ~system_context();

    // system_context operations:

    executor_type get_executor() noexcept;

    void stop();
    bool stopped() const noexcept;
    void join();
  };

} // inline namespace v1
} // namespace net
} // namespace experimental
} // namespace std

The class system_context satisfies the ExecutionContext ([async.reqmts.executioncontext]) type requirements.

The system_context member functions get_executor, stop, and stopped, and the system_executor copy constructors, member functions and comparison operators, do not introduce data races as a result of concurrent calls to those functions from different threads of execution.

~system_context();

An exception of type bad_executor is thrown by executor member functions dispatch, post, and defer when the executor object has no target.

namespace std {
namespace experimental {
namespace net {
inline namespace v1 {

  class bad_executor : public exception
  {
  public:
    // constructor:
    bad_executor() noexcept;
  };

} // inline namespace v1
} // namespace net
} // namespace experimental
} // namespace std

bad_executor() noexcept;

The executor class provides a polymorphic wrapper for types that satisfy the Executor requirements ([async.reqmts.executor]).

namespace std {
namespace experimental {
namespace net {
inline namespace v1 {

  class executor
  {
  public:
    // [async.executor.cons], construct / copy / destroy:

    executor() noexcept;
    executor(nullptr_t) noexcept;
    executor(const executor& e) noexcept;
    executor(executor&& e) noexcept;
    template<class Executor> executor(Executor e);
    template<class Executor, class ProtoAllocator>
      executor(allocator_arg_t, const ProtoAllocator& a, Executor e);

    executor& operator=(const executor& e) noexcept;
    executor& operator=(executor&& e) noexcept;
    executor& operator=(nullptr_t) noexcept;
    template<class Executor> executor& operator=(Executor e);

    ~executor();

    // [async.executor.modifiers], executor modifiers:

    void swap(executor& other) noexcept;
    template<class Executor, class ProtoAllocator>
      void assign(Executor e, const ProtoAllocator& a);

    // [async.executor.ops], executor operations:

    execution_context& context() const noexcept;

    void on_work_started() const noexcept;
    void on_work_finished() const noexcept;

    template<class Func, class ProtoAllocator>
      void dispatch(Func&& f, const ProtoAllocator& a) const;
    template<class Func, class ProtoAllocator>
      void post(Func&& f, const ProtoAllocator& a) const;
    template<class Func, class ProtoAllocator>
      void defer(Func&& f, const ProtoAllocator& a) const;

    // [async.executor.capacity], executor capacity:

    explicit operator bool() const noexcept;

    // [async.executor.target], executor target access:

    const type_info& target_type() const noexcept;
    template<class Executor> Executor* target() noexcept;
    template<class Executor> const Executor* target() const noexcept;
  };

  // [async.executor.comparisons], executor comparisons:

  bool operator==(const executor& a, const executor& b) noexcept;
  bool operator==(const executor& e, nullptr_t) noexcept;
  bool operator==(nullptr_t, const executor& e) noexcept;
  bool operator!=(const executor& a, const executor& b) noexcept;
  bool operator!=(const executor& e, nullptr_t) noexcept;
  bool operator!=(nullptr_t, const executor& e) noexcept;

  // [async.executor.algo], executor specialized algorithms:

  void swap(executor& a, executor& b) noexcept;

} // inline namespace v1
} // namespace net
} // namespace experimental

  template<class Allocator>
    struct uses_allocator<experimental::net::v1::executor, Allocator>
      : true_type {};

} // namespace std

Class executor meets the requirements of Executor ([async.reqmts.executor]), DefaultConstructible (C++ 2014 [defaultconstructible]), and CopyAssignable (C++ 2014 [copyassignable]).

[ Note: To meet the noexcept requirements for executor copy constructors and move constructors, implementations can share a target between two or more executor objects.  — end note ]

The target is the executor object that is held by the wrapper.

[ Note: The function dispatch satisfies the requirements for an asynchronous operation ([async.reqmts.async]), except for the requirement that the operation uses post if it completes immediately.  — end note ]

template<class CompletionToken> DEDUCED dispatch(CompletionToken&& token);

[ Note: The function post satisfies the requirements for an asynchronous operation ([async.reqmts.async]).  — end note ]

template<class CompletionToken> DEDUCED post(CompletionToken&& token);

[ Note: The function defer satisfies the requirements for an asynchronous operation ([async.reqmts.async]), except for the requirement that the operation uses post if it completes immediately.  — end note ]

template<class CompletionToken> DEDUCED defer(CompletionToken&& token);

The class template strand is a wrapper around an object of type Executor satisfying the Executor requirements ([async.reqmts.executor]).

namespace std {
namespace experimental {
namespace net {
inline namespace v1 {

  template<class Executor>
  class strand
  {
  public:
    // types:

    using inner_executor_type = Executor;

    // [async.strand.cons], construct / copy / destroy:

    strand();
    explicit strand(Executor ex);
    template<class ProtoAllocator>
      strand(allocator_arg_t, const ProtoAllocator& alloc, Executor ex);
    strand(const strand& other) noexcept;
    strand(strand&& other) noexcept;
    template<class OtherExecutor> strand(const strand<OtherExecutor>& other) noexcept;
    template<class OtherExecutor> strand(strand<OtherExecutor>&& other) noexcept;

    strand& operator=(const strand& other) noexcept;
    strand& operator=(strand&& other) noexcept;
    template<class OtherExecutor> strand& operator=(const strand<OtherExecutor>& other) noexcept;
    template<class OtherExecutor> strand& operator=(strand<OtherExecutor>&& other) noexcept;

    ~strand();

    // [async.strand.ops], strand operations:

    inner_executor_type get_inner_executor() const noexcept;

    bool running_in_this_thread() const noexcept;

    execution_context& context() const noexcept;

    void on_work_started() const noexcept;
    void on_work_finished() const noexcept;

    template<class Func, class ProtoAllocator>
      void dispatch(Func&& f, const ProtoAllocator& a) const;
    template<class Func, class ProtoAllocator>
      void post(Func&& f, const ProtoAllocator& a) const;
    template<class Func, class ProtoAllocator>
      void defer(Func&& f, const ProtoAllocator& a) const;

  private:
    Executor inner_ex_; // exposition only
  };

  bool operator==(const strand<Executor>& a, const strand<Executor>& b);
  bool operator!=(const strand<Executor>& a, const strand<Executor>& b);

} // inline namespace v1
} // namespace net
} // namespace experimental
} // namespace std

strand<Executor> satisfies the Executor ([async.reqmts.executor]) requirements.

A strand provides guarantees of ordering and non-concurrency. Given:

• (3.1)

  strand objects s1 and s2 such that s1 == s2

• (3.2)

  a function object f1 added to the strand s1 using post or defer, or using dispatch when s1.running_in_this_thread() is false

• (3.3)

  a function object f2 added to the strand s2 using post or defer, or using dispatch when s2.running_in_this_thread() is false

then the implementation invokes f1 and f2 such that:

• (4.1)

  the invocation of f1 is not concurrent with the invocation of f2

• (4.2)

  the invocation of f1 synchronizes with the invocation of f2.

Furthermore, if the addition of f1 happens before the addition of f2, then the invocation of f1 happens before the invocation of f2.

All member functions, except for the assignment operators and the destructor, do not introduce data races on *this, including its ordered, non-concurrent state. Additionally, constructors and assignment operators do not introduce data races on lvalue arguments.

If any function f executed by the strand throws an exception, the subsequent strand state is as if f had exited without throwing an exception.

The class template use_future_t defines a set of types that, when passed as a completion token ([async.reqmts.async.token]) to an asynchronous operation's initiating function, cause the result of the asynchronous operation to be delivered via a future (C++ 2014 [futures.uniquefuture]).

namespace std {
namespace experimental {
namespace net {
inline namespace v1 {

  template<class ProtoAllocator = allocator<void>>
  class use_future_t
  {
  public:
    // use_future_t types:
    using allocator_type = ProtoAllocator;

    // use_future_t members:
    constexpr use_future_t() noexcept(noexcept(allocator_type()));
    explicit use_future_t(const allocator_type& a) noexcept;
    template<class OtherProtoAllocator> use_future_t<OtherProtoAllocator>
      rebind(const OtherProtoAllocator& a) const noexcept;
    allocator_type get_allocator() const noexcept;
    template <class F> unspecified operator()(F&& f) const;
  };

} // inline namespace v1
} // namespace net
} // namespace experimental
} // namespace std