Document number: P0958R1
Date:            2018-05-06
Project:         Programming Language C++
Audience:        SG1 - Concurrency and Parallelism, LEWG
Reply-to:        Christopher Kohlhoff <chris@kohlhoff.com>

Networking TS changes to support proposed Executors TS

Introduction

The purpose of this paper is to illustrate the likely changes to the Networking TS to conform to the proposed Executors TS in P0443R7. At this time, this paper is intended only as an aid to discussion of P0443R7, and is not intended for review and incorporation into the Networking TS.

All changes are relative to N4711.

Summary of changes

This paper proposes the following changes to the Networking TS:

• Add a reference to the executors proposal.
• Remove executor_work_guard and make_work_guard, as these have been superseded by the executors proposal's execution::outstanding_work property.
• Remove the Executor type requirements and the is_executor type trait.
• Specify the "Requirements on asynchronous operations" in terms of the new executors model.
• Update system_executor and system_context to conform to the new executors model.
• Remove the polymorphic wrapper executor and replace it with a type alias for the executors proposal's execution::executor.
• Specify the free functions dispatch, post, and defer in terms of the new executors model.
• Update the strand adapter to conform to the new executors model.
• Update the use_future completion token to conform to the new executors model.
• Update io_context to conform to the new executors model.
• Add context() member functions to I/O objects as a convenience.

In addition, this paper proposes some minor modifications to the executors proposal in P0443R7. These changes enable the use of the polymorphic wrapper execution::executor in the Networking TS.

Deployment experience

An implementation of the changes below, including a subset of the P0443R7 specification to enable these changes (except for the polymorphic executor wrapper), can be found in a branch of the Asio library at https://github.com/chriskohlhoff/asio/tree/unified-executors.

This implementation was used to test a number of sample programs. The majority of these programs needed no modification.

Proposed wording

Add a reference to the executors proposal

Add a reference to the executors proposal in -5- Namespaces and headers [namespaces]:

-2- Unless otherwise specified, references to other entities described in this Technical Specification are assumed to be qualified with std::experimental::net::v1::, references to entities described in the C++ standard are assumed to be qualified with std::, and references to entities described in C++ Extensions for Library Fundamentals are assumed to be qualified with std::experimental::fundamentals_v2::, and references to entities described in P0443R7 A Unified Executors Proposal for C++ are assumed to be qualified with std::experimental::executors_v1::.

Remove superseded executor_work_guard and make_work_guard

Remove executor_work_guard from -12.1- Header <experimental/netfwd> synopsis [fwd.decl.synop]:

  template<class Executor>
    class executor_work_guard;

Remove executor_work_guard and make_work_guard from -13.1- Header <experimental/executor> synopsis [async.synop]:

  template<class Executor>
    class executor_work_guard;

  // 13.17, make_work_guard:

  template<class Executor>
    executor_work_guard<Executor>
      make_work_guard(const Executor& ex);
  template<class ExecutionContext>
    executor_work_guard<typename ExecutionContext::executor_type>
      make_work_guard(ExecutionContext& ctx);
  template<class T>
    executor_work_guard<associated_executor_t<T>>
      make_work_guard(const T& t);
  template<class T, class U>
    auto make_work_guard(const T& t, U& u)
      -> decltype(make_work_guard(get_associated_executor(t, forward<U>(u))));

Remove sections -13.16- Class template executor_work_guard [async.exec.work.guard] and -13.17- Function make_work_guard [async.make.work.guard] in their entirety.

Remove Executor requirements and is_executor type trait

Modify Table 3 - Template parameters and type requirements [summary] as follows:

Remove is_executor and is_executor_v from -13.1- Header <experimental/executor> synopsis [async.synop]:

  template<class T> struct is_executor;

  template<class T>
    constexpr bool is_executor_v = is_executor<T>::value;

Remove section -13.2.2- Executor requirements [async.reqmts.executor] in its entirety.

Modify Table 5 - ExecutionContext requirements [async.reqmts.executioncontext] as follows:

Modify section -13.2.7.8- I/O executor [async.reqmts.async.io.exec] as follows.

-1- An asynchronous operation has an associated executor satisfying the Executor (13.2.2) requirementsgeneral requirements on executors (P0443R7). If not otherwise specified by the asynchronous operation, this associated executor is an object of type system_executor.

[...]

-3- Let Executor1 be the type of the associated executor. Let ex1 be a value of type Executor1, representing the associated executor object obtained as described above. execution::can_query_v<Executor1, execution::context_t> shall be true, and execution::query(ex1, execution::context_t) shall yield a value of type execution_context& or of type E&, where E satisifies the ExecutionContext (13.2.3) requirements.

Modify section -13.2.7.9- Completion handler executor [async.reqmts.async.handler.exec] as follows.

-1- A completion handler object of type CompletionHandler has an associated executor satisfying the Executor requirements (13.2.2)general requirements on executors (P0443R7). The type of this associated executor is associated_executor_t<CompletionHandler, Executor1>. Let Executor2 be the type associated_executor_t<CompletionHandler, Executor1>. Let ex2 be a value of type Executor2 obtained by performing get_associated_executor(completion_handler, ex1). execution::can_query_v<Executor2, execution::context_t> shall be true, and execution::query(ex2, execution::context_t) shall yield a value of type execution_context& or of type E&, where E satisifies the ExecutionContext (13.2.3) requirements.

Modify section -13.2.7.14- Composed asynchronous operations [async.reqmts.async.composed] as follows.

An intermediate operation's completion handler shall have an associated executor that is either:

• the type Executor2 and object ex2 obtained from the completion handler type CompletionHandler and object completion_handler; or
• an object of an unspecified type satisfying the Executor requirements (13.2.2)general requirements on executors (P0443R7), that delegates executor operations to the type Executor2 and object ex2.

Remove section -13.9- Class template is_executor [async.is.exec] in its entirety.

Modify section -13.10- Executor argument tag [async.executor.arg] as follows.

Modify section -13.12- Class template associated_executor [async.assoc.exec] as follows.

-1- Class template associated_executor is an associator (13.2.6) for the Executor (13.2.2) type requirementsexecutors, with default candidate type system_executor and default candidate object system_executor().

Modify Table 9 - associated_executor specialization requirements as follows:

Modify section -13.13- Function get_associated_executor [async.assoc.exec.get] as follows.

-3- Remarks: This function shall not participate in overload resolution unless is_executor_v<Executor> is trueis_convertible<Executor&, execution_context&>::value is false.

Modify section -13.14- Class template executor_binder [async.exec.binder] as follows.

-1- 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 (13.2.2)general requirements on executors (P0443R7) to an object or function of type T.

Modify section -13.15- Function bind_executor [async.bind.executor] as follows.

-2- Remarks: This function shall not participate in overload resolution unless is_executor_v<Executor> is trueis_convertible<Executor&, execution_context&>::value is false.

Modify section -13.22- Function dispatch [async.dispatch] as follows.

-8- Remarks: This function shall not participate in overload resolution unless is_executor_v<Executor> is trueis_convertible<Executor&, execution_context&>::value is false.

Modify section -13.23- Function post [async.post] as follows.

-8- Remarks: This function shall not participate in overload resolution unless is_executor_v<Executor> is trueis_convertible<Executor&, execution_context&>::value is false.

Modify section -13.24- Function defer [async.defer] as follows.

-8- Remarks: This function shall not participate in overload resolution unless is_executor_v<Executor> is trueis_convertible<Executor&, execution_context&>::value is false.

Modify section -13.25- Class template strand [async.strand] as follows.

-1- The class template strand is a wrapper around an object of type Executor satisfying the OneWayExecutor requirements (13.2.2P0443R7).

[...]

-2- strand<Executor> satisfies the Executor (13.2.2) requirementsOneWayExecutor requirements (P0443R7).

Modify Table 17 - AsyncReadStream requirements [buffer.stream.reqmts.asyncreadstream] as follows:

Modify Table 19 - AsyncWriteStream requirements [buffer.stream.reqmts.asyncwritestream] as follows:

Specify the "Requirements on asynchronous operations" in terms of the new executors model

Modify section -13.2.7.10- Outstanding work [async.reqmts.async.work] as follows.

-1- Until the asynchronous operation has completed, the asynchronous operation shall maintain:

Modify section -13.2.7.12- Execution of completion handler on completion of asynchronous operation [async.reqmts.async.completion] as follows:

-3- If an asynchronous operation completes immediately (that is, within the thread of execution calling the initiating function, and before the initiating function returns), the completion handler shall be submitted for execution as if by performingex2.post(std::move(f), alloc2). Otherwise, the completion handler shall be submitted for execution as if by performing ex2.dispatch(std::move(f), alloc2).:

  execution::prefer(
    execution::require(ex2, execution::oneway, execution::single, execution::blocking.never),
      execution::allocator(alloc2)).execute(std::move(f));

  execution::prefer(
    execution::require(work2, execution::oneway, execution::single),
      execution::blocking.possibly, execution::allocator(alloc2)).execute(std::move(f));

Update system_executor and system_context to conform to the new executors model

Remove system_executor from, and add system_context to, -12.1- Header <experimental/netfwd> synopsis [fwd.decl.synop]:

  class system_executor;
  class system_context;

Update system_executor to be a type alias in -13.1- Header <experimental/executor> synopsis [async.synop]:

  class system_executor;
  class system_context;
  using system_executor = system_context::executor_type;

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

Remove section -13.18- Class system_executor [async.system.exec] in its entirety.

Modify section -13.19- Class system_context [async.system.context] as follows:

-1- Class system_context implements the execution context associated with system_executor objectsan execution context that represents the ability to run a submitted function object on any thread.

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

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

    using executor_type = system_executorsee below;

[...]

-2- The class system_context satisfies the ExecutionContext (13.2.3) type requirements.

[...]

executor_type get_executor() noexcept;

-5- Returns: system_executor()executor_type().

After section -13.19- Class system_context [async.system.context] insert a new section as follows:

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

  class C
  {
  public:
    // construct / copy / destroy:

    C() {}

    // executor operations:

    see below require(execution::blocking_t::possibly_t) const;
    see below require(execution::blocking_t::never_t) const;
    see below require(execution::relationship_t::fork_t) const;
    see below require(execution::relationship_t::continuation_t) const;
    see below require(execution::allocator_t<void>) const;
    template<class ProtoAllocator>
      see below require(const execution::allocator_t<ProtoAllocator>& a) const;

    static constexpr execution::mapping_t query(execution::mapping_t) noexcept;
    static system_context& query(execution::context_t) noexcept;
    static constexpr execution::blocking_t query(execution::blocking_t) noexcept;
    static constexpr execution::relationship_t query(execution::relationship_t) noexcept;
    see below query(execution::allocator_t<void>) const noexcept;
    template<class ProtoAllocator>
      see below query(const execution::allocator_t<ProtoAllocator>&) const noexcept;

    template<class Function>
      void execute(Function&& f) const;
  };

  bool operator==(const C& a, const C& b) noexcept;
  bool operator!=(const C& a, const C& b) noexcept;

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

see below require(execution::blocking_t::possibly_t) const;
see below require(execution::blocking_t::never_t) const;
see below require(execution::relationship_t::fork_t) const;
see below require(execution::relationship_t::continuation_t) const;

see below require(execution::allocator_t<void>) const;

template<class ProtoAllocator>
  see below require(const execution::allocator_t<ProtoAllocator>& a) const;

static constexpr execution::mapping_t query(execution::mapping_t) noexcept;

static system_context& query(execution::context_t) const;

static constexpr execution::blocking_t query(execution::blocking_t) noexcept;
static constexpr execution::relationship_t query(execution::relationship_t) noexcept;

see below query(execution::allocator_t<void>) const noexcept;
template<class ProtoAllocator>
  see below query(const execution::allocator_t<ProtoAllocator>&) const noexcept;

template<class Function>
  void execute(Function&& f) const

bool operator==(const C& a, const C& b) noexcept;

bool operator!=(const C& a, const C& b) noexcept;

Remove the polymorphic wrapper executor and replace it with a type alias

Remove executor from -12.1- Header <experimental/netfwd> synopsis [fwd.decl.synop]:

  class executor;

Remove classes bad_executor and executor, and add a new type alias executor, in -13.1- Header <experimental/executor> synopsis [async.synop]:

  class bad_executor;

  class executor;

  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;
  using executor = execution::executor<
    execution::oneway_t,
    execution::single_t,
    execution::context_as<execution_context&>,
    execution::blocking_t::possibly_t,
    execution::blocking_t::never_t,
    execution::prefer_only<execution::outstanding_work::untracked_t>,
    execution::prefer_only<execution::outstanding_work::tracked_t>,
    execution::prefer_only<execution::relationship_t::fork_t>,
    execution::prefer_only<execution::relationship_t::continuation_t>>;

[...]

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

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

} // namespace std

Remove sections -13.20- Class bad_executor [async.bad.exec] and -13.21- Class executor [async.executor] in their entirety.

Specify the free functions dispatch, post, and defer in terms of the new executors model

Modify section -13.22- Function dispatch [async.dispatch] as follows:

-1- [Note: The function dispatch satisfies the requirements for an asynchronous operation (13.2.7), except for the requirement that the operation uses postthe execution::blocking.never property if it completes immediately. --end note]

[...]

-3- Effects:

• Constructs an object completion of type async_completion<CompletionToken, void()>, initialized with token.
• Performs ex.dispatch(std::move(completion.completion_handler), alloc), where ex is the result of get_associated_executor(completion.completion_handler), and alloc is the result of get_associated_allocator(completion.completion_handler).
• Performs:

    execution::prefer(
      execution::require(ex, execution::oneway, execution::single),
        execution::blocking.possibly, execution::allocator(alloc)).execute(
          std::move(completion.completion_handler));
  

  where ex is the result of get_associated_executor(completion.completion_handler), and alloc is the result of get_associated_allocator(completion.completion_handler).

[...]

-6- Effects:

• Constructs an object completion of type async_completion<CompletionToken, void()>, initialized with token.
• Constructs a function object f containing as members:
  • an executor object w for the completion handler's associated executor, initialized with execution::prefer(get_associated_executor(h), execution::outstanding_work),
  • a copy of the completion handler h, initialized with std::move(completion.completion_handler),
  • an executor_work_guard object w for the completion handler's associated executor, initialized with make_work_guard(h),
  and where the effect of f() is:
  • w.get_executor().dispatch(std::move(h), alloc), where alloc is the result of get_associated_allocator(h), followed by
  • w.reset().

    execution::prefer(
      execution::require(w, execution::oneway, execution::single),
        execution::blocking.possibly, execution::allocator(alloc)).execute(std::move(h));
  

  where alloc is the result of get_associated_allocator(h).
• Performs ex.dispatch(std::move(f), alloc), where alloc is the result of get_associated_allocator(completion.completion_handler) prior to the construction of f.
• Performs:

    execution::prefer(
      execution::require(ex, execution::oneway, execution::single),
        execution::blocking.possibly, execution::allocator(alloc)).execute(std::move(f));
  

Modify section -13.23- Function post [async.post] as follows:

-3- Effects:

• Constructs an object completion of type async_completion<CompletionToken, void()>, initialized with token.
• Performs ex.post(std::move(completion.completion_handler), alloc), where ex is the result of get_associated_executor(completion.completion_handler), and alloc is the result of get_associated_allocator(completion.completion_handler).
• Performs:

    execution::prefer(
      execution::require(ex, execution::oneway, execution::single, execution::blocking.never),
        execution::allocator(alloc)).execute(std::move(completion.completion_handler));
  

  where ex is the result of get_associated_executor(completion.completion_handler), and alloc is the result of get_associated_allocator(completion.completion_handler).

[...]

-6- Effects:

• Constructs an object completion of type async_completion<CompletionToken, void()>, initialized with token.
• Constructs a function object f containing as members:
  • an executor object w for the completion handler's associated executor, initialized with execution::prefer(get_associated_executor(h), execution::outstanding_work),
  • a copy of the completion handler h, initialized with std::move(completion.completion_handler),
  • an executor_work_guard object w for the completion handler's associated executor, initialized with make_work_guard(h),
  and where the effect of f() is:
  • w.get_executor().dispatch(std::move(h), alloc), where alloc is the result of get_associated_allocator(h), followed by
  • w.reset().

    execution::prefer(
      execution::require(w, execution::oneway, execution::single),
        execution::blocking.possibly, execution::allocator(alloc)).execute(std::move(h));
  

  where alloc is the result of get_associated_allocator(h).
• Performs ex.dispatch(std::move(f), alloc), where alloc is the result of get_associated_allocator(completion.completion_handler) prior to the construction of f.
• Performs:

    execution::prefer(
      execution::require(ex, execution::oneway, execution::single, execution::blocking.never),
        execution::allocator(alloc)).execute(std::move(f));
  

Modify section -13.24- Function defer [async.defer] as follows:

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

[...]

-3- Effects:

• Constructs an object completion of type async_completion<CompletionToken, void()>, initialized with token.
• Performs ex.defer(std::move(completion.completion_handler), alloc), where ex is the result of get_associated_executor(completion.completion_handler), and alloc is the result of get_associated_allocator(completion.completion_handler).
• Performs:

    execution::prefer(
      execution::require(ex, execution::oneway, execution::single, execution::blocking.never),
        execution::relationship.continuation, execution::allocator(alloc)).execute(
          std::move(completion.completion_handler));
  

  where ex is the result of get_associated_executor(completion.completion_handler), and alloc is the result of get_associated_allocator(completion.completion_handler).

[...]

-6- Effects:

• Constructs an object completion of type async_completion<CompletionToken, void()>, initialized with token.
• Constructs a function object f containing as members:
  • an executor object w for the completion handler's associated executor, initialized with execution::prefer(get_associated_executor(h), execution::outstanding_work),
  • a copy of the completion handler h, initialized with std::move(completion.completion_handler),
  • an executor_work_guard object w for the completion handler's associated executor, initialized with make_work_guard(h),
  and where the effect of f() is:
  • w.get_executor().dispatch(std::move(h), alloc), where alloc is the result of get_associated_allocator(h), followed by
  • w.reset().

    execution::prefer(
      execution::require(w, execution::oneway, execution::single),
        execution::blocking.possibly, execution::allocator(alloc)).execute(std::move(h));
  

  where alloc is the result of get_associated_allocator(h).
• Performs ex.dispatch(std::move(f), alloc), where alloc is the result of get_associated_allocator(completion.completion_handler) prior to the construction of f.
• Performs:

    execution::prefer(
      execution::require(ex, execution::oneway, execution::single, execution::blocking.never),
        execution::relationship.continuation, execution::allocator(alloc)).execute(std::move(f));
  

Update the strand adapter to conform to the new executors model

Modify section -13.25- Class template strand [async.strand] as follows:

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

  template<class Executor>
  class strand
  {
  public:

[...]

    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;

    template<class Property>
      see below require(const Property& p) const;

    template<class Property>
      static constexpr see below query(const Property& p);

    template<class Property>
      see below query(const Property& p) const;

    template<class Function>
      void execute(Function&& f) const;

[...]

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

• strand objects s1 and s2 such that s1 == s2
• a function object f1 addedsubmitted to the strand s1 using post or defer, or using dispatchwhen the execution::blocking.never property is established in s1, or when s1.running_in_this_thread() is false
• a function object f2 addedsubmitted to the strand s2 using post or defer, or using dispatchwhen the execution::blocking.never property is established in s2, or when s2.running_in_this_thread() is false

Modify section -13.25.4- strand operations [async.strand.ops] as follows:

bool running_in_this_thread() const noexcept;

-2- Returns: true if the current thread of execution is running a function that was submitted to the strand, or to any other strand object s such that s == *this, using dispatch, post or deferthat shares the same ordered, non-concurrent state, using execute; otherwise false. [Note: That is, the current thread of execution's call chain includes a function that was submitted to the strand. --end note]

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 Property>
  see below require(const Property& p) const;

template<class Property>
  static constexpr see below query(const Property& p);

template<class Property>
  see below query(const Property& p) const;

template<class Function>
  void execute(Function&& f) const;

Update the use_future completion token to conform to the new executors model

Modify section -13.26.2- use_future_t members [async.use.future.members] as follows:

-8- For any executor type E, the associated object for the associator associated_executor<H, E> is an executor where, for function objects executed using the executor's dispatch(), post() or defer() functionsexecute() function, any exception thrown is caught by a function object and stored in the associated shared state.

Modify section -13.26.3- Partial class template specialization async_result for use_future_t [async.use.future.result] as follows:

-3- The implementation specializes associated_executor for F. For function objects executed using the associated executor's dispatch(), post() or defer() functionsexecute() function, any exception thrown is caught by the executor and stored in the associated shared state.

-4- For any executor type E, the associated object for the associator associated_executor<F, E> is an executor where, for function objects executed using the executor's dispatch(), post() or defer() functionsexecute() function, any exception thrown by a function object is caught by the executor and stored in the associated shared state.

Update io_context to conform to the new executors model

Modify section -14.2- Class io_context [io_context.io_context] as follows:

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

  class io_context : public execution_context
  {
  public:
    // types:

    class executor_type;
    using executor_type = see below;

[...]

-1- The class io_context satisfies the ExecutionContext type requirements (13.2.3).

[...]

-4- For an object of type io_context, outstanding work is defined as the sum of:

• the total number of calls to the on_work_started function, less the total number of calls to the on_work_finished function, to any executor of the io_context.
• the number of existing executor objects associated with the io_context for which the execution::outstanding_work property is established;
• the number of function objects that have been added to the io_context via any executor of the io_context, but not yet executed; and
• the number of function objects that are currently being executed by the io_context.

[...]

executor_type get_executor() noexcept;

-3- Returns: An executor that may be used for submitting function objects to the io_context. The returned executor has the following properties already established:

[...]

-13- Remarks: This function may invoke additional function objects through nested calls to the io_context executor's dispatchexecute member function. These do not count towards the return value.

[...]

-19- Remarks: This function may invoke additional function objects through nested calls to the io_context executor's dispatchexecute member function. These do not count towards the return value.

[...]

-25- Remarks: This function may invoke additional function objects through nested calls to the io_context executor's dispatchexecute member function. These do not count towards the return value.

Remove section -14.3- Class io_context::executor_type [io_context.exec] in its entirety.

After section -14.2- Class io_context [io_context.io_context] insert a new section as follows:

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

  class C
  {
  public:
    // construct / copy / destroy:

    C(const C& other) noexcept;
    C(C&& other) noexcept;

    C& operator=(const C& other) noexcept;
    C& operator=(C&& other) noexcept;

    // executor operations:

    see below require(execution::blocking_t::possibly_t) const;
    see below require(execution::blocking_t::never_t) const;
    see below require(execution::relationship_t::fork_t) const;
    see below require(execution::relationship_t::continuation_t) const;
    see below require(execution::outstanding_work_t::untracked_t) const;
    see below require(execution::outstanding_work_t::tracked_t) const;
    see below require(execution::allocator_t<void>) const;
    template<class ProtoAllocator>
      see below require(const execution::allocator_t<ProtoAllocator>& a) const;

    static constexpr execution::mapping_t query(execution::mapping_t) noexcept;
    io_context& query(execution::context_t) const noexcept;
    static constexpr execution::blocking_t query(execution::blocking_t) noexcept;
    static constexpr execution::relationship_t query(execution::relationship_t) noexcept;
    static constexpr execution::outstanding_work_t query(execution::outstanding_work_t) noexcept;
    see below query(execution::allocator_t<void>) const noexcept;
    template<class ProtoAllocator>
      see below query(const execution::allocator_t<ProtoAllocator>&) const noexcept;

    bool running_in_this_thread() const noexcept;

    template<class Function>
      void execute(Function&& f) const;
  };

  bool operator==(const C& a, const C& b) noexcept;
  bool operator!=(const C& a, const C& b) noexcept;

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

C(const C& other) noexcept;

C(C&& other) noexcept;

C& operator=(const C& other) noexcept;

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

see below require(execution::blocking_t::possibly_t) const;
see below require(execution::blocking_t::never_t) const;
see below require(execution::relationship_t::fork_t) const;
see below require(execution::relationship_t::continuation_t) const;
see below require(execution::outstanding_work_t::untracked_t) const;
see below require(execution::outstanding_work_t::tracked_t) const;

see below require(execution::allocator_t<void>) const;

template<class ProtoAllocator>
  see below require(const execution::allocator_t<ProtoAllocator>& a) const;

static constexpr execution::mapping_t query(execution::execution::mapping_t) noexcept;

io_context& query(execution::context_t) const noexcept;

static constexpr execution::blocking_t query(execution::blocking_t) noexcept;
static constexpr execution::relationship_t query(execution::relationship_t) noexcept;
static constexpr execution::outstanding_work_t query(execution::outstanding_work_t) noexcept;

see below query(execution::allocator_t<void>) const noexcept;
template<class ProtoAllocator>
  see below query(const execution::allocator_t<ProtoAllocator>&) const noexcept;

bool running_in_this_thread() const noexcept;

template<class Function>
  void execute(Function&& f) const

bool operator==(const C& a, const C& b) noexcept;

bool operator!=(const C& a, const C& b) noexcept;

Add context() member functions to I/O objects as a convenience

Modify section -15.4- Class template basic_waitable_timer [timer.waitable] as follows:

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

  template<class Clock, class WaitTraits = wait_traits<Clock>>
  class basic_waitable_timer
  {
  public:

[...]

    // 15.4.4, basic_waitable_timer operations:

    io_context& context() noexcept;

    executor_type get_executor() noexcept;

[...]

basic_waitable_timer(io_context& ctx, const time_point& t);

-2- Postconditions:

• addressof(context()) == addressof(ctx).

[...]

basic_waitable_timer(io_context& ctx, const duration& d);

-3- Effects: Sets the expiry time as if by calling expires_after(d).

-4- Postconditions: get_executor() == ctx.get_executor().

[...]

basic_waitable_timer(basic_waitable_timer&& rhs);

-5- Effects: Move constructs an object of class basic_waitable_timer<Clock, WaitTraits> that refers to the state originally represented by rhs.

-6- Postconditions:

• addressof(context()) == addressof(rhs.context()).

[...]

basic_waitable_timer& operator=(basic_waitable_timer&& rhs);

-1- Effects: Cancels any outstanding asynchronous operations associated with *this as if by calling cancel(), then moves into *this the state originally represented by rhs.

-2- Postconditions:

• addressof(context()) == addressof(rhs.context()).

[...]

-15.4.4- basic_waitable_timer operations [timer.waitable.ops]

io_context& context() noexcept;

Modify section -18.6- Class template basic_socket [socket.basic] as follows:

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

  template<class Protocol>
  class basic_socket
  {
  public:

[...]

    // 18.6.4, basic_socket operations:

    io_context& context() noexcept;

    executor_type get_executor() noexcept;

[...]

explicit basic_socket(io_context& ctx);

-1- Postconditions:

• addressof(context()) == addressof(ctx).

[...]

basic_socket(io_context& ctx, const protocol_type& protocol);

-2- Effects: Opens this socket as if by calling open(protocol).

-3- Postconditions:

• addressof(context()) == addressof(ctx).

[...]

basic_socket(io_context& ctx, const endpoint_type& endpoint);

-4- Effects: Opens and binds this socket as if by calling:

  open(endpoint.protocol());
  bind(endpoint);

-5- Postconditions:

• addressof(context()) == addressof(ctx).

[...]

basic_socket(io_context& ctx, const protocol_type& protocol,
             const native_handle_type& native_socket);

-6- Requires: native_socket is a native handle to an open socket.

-7- Effects: Assigns the existing native socket into this socket as if by calling assign(protocol, native_socket).

-8- Postconditions:

• addressof(context()) == addressof(ctx).

[...]

basic_socket(basic_socket&& rhs);

-9- Effects: Move constructs an object of class basic_socket<Protocol> that refers to the state originally represented by rhs.

-10- Postconditions:

• addressof(context()) == addressof(rhs.context()).

[...]

template<class OtherProtocol>
  basic_socket(basic_socket<OtherProtocol>&& rhs);

-11- Requires: OtherProtocol is implicitly convertible to Protocol.

-12- Effects: Move constructs an object of class basic_socket<Protocol> that refers to the state originally represented by rhs.

-13- Postconditions:

• addressof(context()) == addressof(rhs.context()).

[...]

basic_socket& operator=(basic_socket&& rhs);

-1- Effects: If is_open() is true, cancels all outstanding asynchronous operations associated with this socket. Completion handlers for canceled operations are passed an error code ec such that ec == errc::operation_canceled yields true. Disables the linger socket option to prevent the assignment from blocking, and releases socket resources as if by POSIX close(native_handle()). Moves into *this the state originally represented by rhs.

-2- Postconditions:

• addressof(context()) == addressof(rhs.context()).

[...]

template<class OtherProtocol>
  basic_socket& operator=(basic_socket<OtherProtocol>&& rhs);

-4- Requires: OtherProtocol is implicitly convertible to Protocol.

-5- Effects: If is_open() is true, cancels all outstanding asynchronous operations associated with this socket. Completion handlers for canceled operations are passed an error code ec such that ec == errc::operation_canceled yields true. Disables the linger socket option to prevent the assignment from blocking, and releases socket resources as if by POSIX close(native_handle()). Moves into *this the state originally represented by rhs.

-6- Postconditions:

• addressof(context()) == addressof(rhs.context()).

[...]

-18.6.4- basic_socket operations [socket.basic.ops]

io_context& context() noexcept;

Modify section -18.9- Class template basic_socket_acceptor [socket.acceptor] as follows:

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

  template<class Protocol>
  class basic_socket_acceptor
  {
  public:

[...]

    // 18.9.4, basic_socket_acceptor operations:

    io_context& context() noexcept;

    executor_type get_executor() noexcept;

[...]

explicit basic_socket_acceptor(io_context& ctx);

-1- Postconditions:

• addressof(context()) == addressof(ctx).

[...]

basic_socket_acceptor(io_context& ctx, const protocol_type& protocol);

-2- Effects: Opens this acceptor as if by calling open(protocol).

-3- Postconditions:

• addressof(context()) == addressof(ctx).

[...]

basic_socket_acceptor(io_context& ctx, const endpoint_type& endpoint,
                      bool reuse_addr = true);

-4- Effects: Opens and binds this acceptor as if by calling:

  open(endpoint.protocol());
  if (reuse_addr)
    set_option(reuse_address(true));
  bind(endpoint);

-5- Postconditions:

• addressof(context()) == addressof(ctx).

[...]

basic_socket_acceptor(io_context& ctx, const protocol_type& protocol,
                      const native_handle_type& native_acceptor);

-6- Requires: native_acceptor is a native handle to an open acceptor.

-7- Effects: Assigns the existing native acceptor into this acceptor as if by calling assign(protocol, native_acceptor).

-8- Postconditions:

• addressof(context()) == addressof(ctx).

[...]

basic_socket_acceptor(basic_socket_acceptor&& rhs);

-9- Effects: Move constructs an object of class basic_socket_acceptor<Protocol> that refers to the state originally represented by rhs.

-10- Postconditions:

• addressof(context()) == addressof(rhs.context()).

[...]

template<class OtherProtocol>
  basic_socket_acceptor(basic_socket_acceptor<OtherProtocol>&& rhs);

-11- Requires: OtherProtocol is implicitly convertible to Protocol.

-12- Effects: Move constructs an object of class basic_socket_acceptor<Protocol> that refers to the state originally represented by rhs.

-13- Postconditions:

• addressof(context()) == addressof(rhs.context()).

[...]

basic_socket_acceptor& operator=(basic_socket_acceptor&& rhs);

-1- Effects: If is_open() is true, cancels all outstanding asynchronous operations associated with this acceptor, and releases acceptor resources as if by POSIX close(native_handle()). Then moves into *this the state originally represented by rhs. Completion handlers for canceled operations are passed an error code ec such that ec == errc::operation_canceled yields true.

-2- Postconditions:

• addressof(context()) == addressof(rhs.context()).

[...]

template<class OtherProtocol>
  basic_socket_acceptor& operator=(basic_socket_acceptor<OtherProtocol>&& rhs);

-4- Requires: OtherProtocol is implicitly convertible to Protocol.

-5- Effects: If is_open() is true, cancels all outstanding asynchronous operations associated with this acceptor, and releases acceptor resources as if by POSIX close(native_handle()). Then moves into *this the state originally represented by rhs. Completion handlers for canceled operations are passed an error code ec such that ec == errc::operation_canceled yields true.

-6- Postconditions:

• addressof(context()) == addressof(rhs.context()).

[...]

-18.9.4- basic_socket_acceptor operations [socket.acceptor.ops]

io_context& context() noexcept;

Modify section -21.17- Class template ip::basic_resolver [internet.resolver] as follows:

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

  template<class InternetProtocol>
  class basic_resolver : public resolver_base
  {
  public:

[...]

    // 21.17.4, basic_resolver operations:

    io_context& context() noexcept;

    executor_type get_executor() noexcept;

[...]

explicit basic_resolver(io_context& ctx);

-1- Postconditions: get_executor() == ctx.get_executor().

basic_resolver(basic_resolver&& rhs) noexcept;

-2- Effects: Move constructs an object of class basic_resolver<InternetProtocol> that refers to the state originally represented by rhs.

-3- Postconditions: get_executor() == rhs.get_executor().

[...]

basic_resolver& operator=(basic_resolver&& rhs);

-1- Effects: Cancels all outstanding asynchronous operations associated with *this as if by calling cancel(), then moves into *this the state originally represented by rhs.

-2- Postconditions: get_executor() == ctx.get_executor().

-3- Returns: *this.

21.17.4 ip::basic_resolver operations [internet.resolver.ops]

io_context& context() noexcept;

Proposed Modifications to P0443R7 A Unified Executors Proposal for C++

The asynchronous operation requirements specified above stipulate that querying the execution::context_t property for Networking TS executors returns a type of either execution_context&, or of E& where E is a type that is unambiguously derived from execution_context.

However, the execution::context_t property as currently specified in P0443 uses std::any as its polymorphic_query_result_type. This prevents the polymorphic wrapper execution::executor from satisfying the above requirements.

Even without considering the impact of unified executors on the Networking TS, having std::any as the polymorphic query result type prevents us from exposing static_thread_pool as a context through the polymorphic wrapper. This is because std::any is not constructible from a reference to the non-copyable static_thread_pool type.

For these reasons, this paper proposes the following changes to P0443R7.

1. Remove the polymorphic_query_result_type from the execution::context_t property.

struct context_t
{
  static constexpr bool is_requirable = false;
  static constexpr bool is_preferable = false;

  using polymorphic_query_result_type = any;

  template<class Executor>
    static constexpr decltype(auto) static_query_v
      = Executor::query(context_t());
};

2. Relax the requirements on polymorphic_query_result_type to remove the DefaultConstructible requirement for query-only properties.

A property type P may provide a nested type polymorphic_query_result_type that satisfies the DefaultConstructible, CopyConstructible and Destructible requirements. If P::is_requirable == true or P::is_preferable == true, polymorphic_query_result_type shall also satisfy the DefaultConstructible requirements. [*Note:* When present, this type allows the property to be used with the polymorphic executor wrapper. *--end note*]

3. Fix a bug in the polymorphic executor constructor so that only the query-only properties in SupportableProperties... are required to queryable at the point of construction (as the other properties only need to become queryable after they are require()-ed).

template<class Executor> executor(Executor e);

Remarks: This function shall not participate in overload resolution unless:

• can_require_v<Executor, P>, if P::is_requirable, where P is each property in SupportableProperties....
• can_prefer_v<Executor, P>, if P::is_preferable, where P is each property in SupportableProperties....
• and can_query_v<Executor, P>, if P::is_requirable == false and P::is_preferable == false, where P is each property in SupportableProperties....

4. Add the following context_as<> property adapter. This adapter allows us to expose the execution::context_t property through the polymorphic wrapper using a polymorphic query type of our choosing.

static_thread_pool pool;

execution::executor<
    execution::single_t,
    execution::oneway_t,
    execution::context_as<static_thread_pool&>
  > my_executor(pool.executor());

// ...

static_thread_pool& ctx =
  execution::query(my_executor, execution::context);

template<class T>
struct context_as
{
  static constexpr bool is_requirable = false;
  static constexpr bool is_preferable = false;

  using polymorphic_query_result_type = T;

  template<class Executor>
    static constexpr T static_query_v
      = context_t::static_query_v<Executor>;

  constexpr context_as() {}
  constexpr context_as(execution::context_t) {}

  template<class Executor, class Property>
  friend constexpr T query(const Executor& ex, const Property& p)
    noexcept(noexcept(execution::query(ex, execution::context)))
      -> decltype(execution::query(ex, execution::context));
};

template<class Executor, class Property>
friend constexpr T query(const Executor& ex, const Property& p)
  noexcept(noexcept(execution::query(ex, execution::context)))

Revision History

The following changes were made in revision 1 of this paper:

• Updated to match the unified executor facilities as described in P0443R7.
• Added a section on deployment experience.
• Specify that system_context executors use distinct types when different properties are established.
• Added missing property queries on system_context executors.
• Changed strand to conditionally forward static query() calls to the adapted executor.
• Specify that io_context executors use distinct types when different properties are established.
• Added missing property queries on io_context executors.
• Added modifications to P0443R7 executors, including the execution::context_as<> property adapter.