[conformance.9945]

Some behavior is specified by reference to POSIX. How such behavior is actually implemented is unspecified.

[Note: This constitutes an "as if" rule allowing implementations to call native operating system or other APIs. —end note]

Implementations are encouraged to provide such behavior as it is defined by POSIX. Implementations shall document any behavior that differs from the behavior defined by POSIX. Implementations that do not support exact POSIX behavior are encouraged to provide behavior as close to POSIX behavior as is reasonable given the limitations of actual operating systems and file systems. If an implementation cannot provide any reasonable behavior, the implementation shall report an error as specified in Error Reporting.

[Note: This allows users to rely on an exception being thrown or an error code being set when an implementation cannot provide any reasonable behavior. —end note]

Implementations are not required to provide behavior that is not supported by a particular operating system.

[conformance.conditional]

This Technical Specification defines conditially-supported features, in the form of additional member functions on types that satisfy Protocol, Endpoint, SettableSocketOption, GettableSocketOption or IoControlCommand requirements.

[Note: This is so that, when the additional member functions are available, C++ programs may extend the library to add support for other protocols and socket options. —end note]

For the purposes of this Technical Specification, implementations that provide all of the additional member functions are known as extensible implementations.

[Note: Implementations are encouraged to provide the additional member functions, where possible. It is intended that POSIX and Windows implementations will provide them. —end note]

[defs.host.byte.order] See section 3.194 of POSIX Base Definitions, Host Byte Order.

[defs.net.byte.order] See section 3.238 of POSIX Base Definitions, Network Byte Order.

[defs.sync.op] A synchronous operation is one where control is not returned until the operation completes.

[defs.async.op] An asynchronous operation is one where control is returned immediately without waiting for the operation to complete. Multiple asynchronous operations may be executed concurrently.

[defs.orderly.shutdown] The procedure for shutting down a stream after all work in progress has been completed, without loss of data.

[structure]

[conventions]

[err.report.sync]

Most synchronous network library functions provide two overloads, one that throws an exception to report system errors, and another that sets an error_code (C++Std [syserr]).

[Note: This supports two common use cases:

— Uses where system errors are truly exceptional and indicate a serious failure. Throwing an exception is the most appropriate response.

— Uses where system errors are routine and do not necessarily represent failure. Returning an error code is the most appropriate response. This allows application specific error handling, including simply ignoring the error.

—end note]

Functions not having an argument of type error_code& report errors as follows, unless otherwise specified:

— When a call by the implementation to an operating system or other underlying API results in an error that prevents the function from meeting its specifications, the function exits via an exception of a type that would match a handler of type system_error.

— Destructors throw nothing.

Functions having an argument of type error_code& report errors as follows, unless otherwise specified:

— If a call by the implementation to an operating system or other underlying API results in an error that prevents the function from meeting its specifications, the error_code& argument ec is set as appropriate for the specific error. Otherwise, the ec argument is set such that !ec is true.

Where a function is specified as two overloads, with and without an argument of type error_code&:

R f(A1 a1, A2 a2, ..., AN aN);
R f(A1 a1, A2 a2, ..., AN aN, error_code& ec);

then, when R is non-void, the effects of the first overload are as if:

error_code ec;
R r(f(a1, a2, ..., aN, ec));
if (ec) throw system_error(ec, __func__);
return r;

otherwise, when R is void, the effects of the first overload are as if:

error_code ec;
f(a1, a2, ..., aN, ec);
if (ec) throw system_error(ec, __func__);

except that the type thrown may differ as specified above.

For both overloads, failure to allocate storage is reported by throwing an exception as described in the C++ standard (C++Std [res.on.exception.handling]).

In this Technical Specification, when a type requirement is specified using two function call expressions f, with and without an argument ec of type error_code:

f(a1, a2, ..., aN)
f(a1, a2, ..., aN, ec)

then the effects of the first call expression of f shall be as described for the first overload above.

[err.report.async]

Asynchronous network library functions in this Technical Specification are identified by having the prefix async_ and take a completion handler [async.reqmts.async.token]. These asynchronous operations report errors as follows:

— If a call by the implementation to an operating system or other underlying API results in an error that prevents the asynchronous operation from meeting its specifications, the completion handler is invoked with an error_code value ec that is set as appropriate for the specific error. Otherwise, the error_code value ec is set such that !ec is true.

— Asynchronous operations shall not fail with an error condition that indicates interruption of an operating system or underlying API by a signal [Note: Such as POSIX error number EINTR —end note] . Asynchronous operations shall not fail with any error condition associated with non-blocking operations [Note: Such as POSIX error numbers EWOULDBLOCK, EAGAIN, or EINPROGRESS; Windows error numbers WSAEWOULDBLOCK or WSAEINPROGRESS —end note] .

In this Technical Specification, when a type requirement is specified as a call to a function or member function having the prefix async_, then the function shall satisfy the error reporting requirements described above.

[err.report.conditions]

Unless otherwise specified, when the behavior of a synchronous or asynchronous operation is defined "as if" implemented by a POSIX function, the error_code produced by the function shall meet the following requirements:

— If the failure condition is one that is listed by POSIX for that function, the error_code shall compare equal to the error's corresponding enum class errc (C++Std [syserr]) or enum class resolver_errc constant.

— Otherwise, the error_code shall be set to an implementation-defined value that reflects the underlying operating system error.

[Example: The POSIX specification for shutdown lists EBADF as one of its possible errors. If a function that is specified "as if" implemented by shutdown fails with EBADF then the following condition holds for the error_code value ec: ec == errc::bad_file_descriptor —end example]

When the description of a function contains the element Error conditions, this lists conditions where the operation may fail. The conditions are listed, together with a suitable explanation, as enum class constants. Unless otherwise specified, this list is a subset of the failure conditions associated with the function.

[err.report.signal]

Some POSIX functions referred to in this Technical Specification may report errors by raising a SIGPIPE signal. Where a synchronous or asynchronous operation is specified in terms of these POSIX functions, the generation of SIGPIPE is suppressed and an error condition corresponding to POSIX EPIPE is produced instead.

[convenience.hdr.synop]

#include <experimental/executor>
#include <experimental/io_context>
#include <experimental/timer>
#include <experimental/buffer>
#include <experimental/socket>
#include <experimental/internet>

[Note: This header is provided as a convenience for programs so that they may access all networking facilities via a single, self-contained #include. —end note]

[fwd.decl.synop]

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

  class execution_context;
  template<class T, class Executor>
    class executor_binder;
  template<class Executor>
    class executor_work_guard;
  class system_executor;
  class executor;
  template<class Executor>
    class strand;

  class io_context;

  template<class Clock> struct wait_traits;
  template<class Clock, class WaitTraits = wait_traits<Clock>>
    class basic_waitable_timer;
  typedef basic_waitable_timer<chrono::system_clock> system_timer;
  typedef basic_waitable_timer<chrono::steady_clock> steady_timer;
  typedef basic_waitable_timer<chrono::high_resolution_clock> high_resolution_timer;

  template<class Protocol>
    class basic_socket;
  template<class Protocol>
    class basic_datagram_socket;
  template<class Protocol>
    class basic_stream_socket;
  template<class Protocol>
    class basic_socket_acceptor;
  template<class Protocol, class Clock = chrono::steady_clock,
    class WaitTraits = wait_traits<Clock>>
      class basic_socket_streambuf;
  template<class Protocol, class Clock = chrono::steady_clock,
    class WaitTraits = wait_traits<Clock>>
      class basic_socket_iostream;

  namespace ip {

    class address;
    class address_v4;
    class address_v6;
    class address_iterator_v4;
    class address_iterator_v6;
    class address_range_v4;
    class address_range_v6;
    class network_v4;
    class network_v6;
    template<class InternetProtocol>
      class basic_endpoint;
    template<class InternetProtocol>
      class basic_resolver_entry;
    template<class InternetProtocol>
      class basic_resolver_results;
    template<class InternetProtocol>
      class basic_resolver;
    class tcp;
    class udp;

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

Default template arguments are described as appearing both in <netfwd> and in the synopsis of other headers but it is well-formed to include both <netfwd> and one or more of the other headers. [Note: It is the implementation’s responsibility to implement headers so that including <netfwd> and other headers does not violate the rules about multiple occurrences of default arguments. —end note]

[async.synop]

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

  template<class CompletionToken, class Signature, class = void>
    class async_result;

  template<class CompletionToken, class Signature>
    struct async_completion;

  template<class T, class ProtoAllocator = allocator<void>>
    struct associated_allocator;

  template<class T, class ProtoAllocator = allocator<void>>
    using associated_allocator_t = typename associated_allocator<T, ProtoAllocator>::type;

  // get_associated_allocator:

  template<class T>
    associated_allocator_t<T> get_associated_allocator(const T& t) noexcept;
  template<class T, class ProtoAllocator>
    associated_allocator_t<T, ProtoAllocator>
      get_associated_allocator(const T& t, const ProtoAllocator& a) noexcept;

  enum class fork_event {
    prepare,
    parent,
    child
  };

  class execution_context;

  class service_already_exists;

  template<class Service> Service& use_service(execution_context& ctx);
  template<class Service, class... Args> Service&
    make_service(execution_context& ctx, Args&&... args);
  template<class Service> bool has_service(execution_context& ctx) noexcept;

  template<class T> struct is_executor;

  struct executor_arg_t { };
  constexpr executor_arg_t executor_arg = executor_arg_t();

  template<class T, class Executor> struct uses_executor;

  template<class T, class Executor = system_executor>
    struct associated_executor;

  template<class T, class Executor = system_executor>
    using associated_executor_t = typename associated_executor<T, Executor>::type;

  // get_associated_executor:

  template<class T>
    associated_executor_t<T> get_associated_executor(const T& t) noexcept;
  template<class T, class Executor>
    associated_executor_t<T, Executor>
      get_associated_executor(const T& t, const Executor& ex) noexcept;
  template<class T, class ExecutionContext>
    associated_executor_t<T, typename ExecutionContext::executor_type>
      get_associated_executor(const T& t, ExecutionContext& ctx) noexcept;

  template<class T, class Executor>
    class executor_binder;

  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>;

  // bind_executor:

  template<class Executor, class T>
    executor_binder<decay_t<T>, Executor>
      bind_executor(const Executor& ex, T&& t);
  template<class ExecutionContext, class T>
    executor_binder<decay_t<T>, typename ExecutionContext::executor_type>
      bind_executor(ExecutionContext& ctx, T&& t);

  template<class Executor>
    class executor_work_guard;

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

  class system_executor;
  class system_context;

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

  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;

  // dispatch:

  template<class CompletionToken>
    DEDUCED dispatch(CompletionToken&& token);
  template<class Executor, class CompletionToken>
    DEDUCED dispatch(const Executor& ex, CompletionToken&& token);
  template<class ExecutionContext, class CompletionToken>
    DEDUCED dispatch(ExecutionContext& ctx, CompletionToken&& token);

  // post:

  template<class CompletionToken>
    DEDUCED post(CompletionToken&& token);
  template<class Executor, class CompletionToken>
    DEDUCED post(const Executor& ex, CompletionToken&& token);
  template<class ExecutionContext, class CompletionToken>
    DEDUCED post(ExecutionContext& ctx, CompletionToken&& token);

  // defer:

  template<class CompletionToken>
    DEDUCED defer(CompletionToken&& token);
  template<class Executor, class CompletionToken>
    DEDUCED defer(const Executor& ex, CompletionToken&& token);
  template<class ExecutionContext, class CompletionToken>
    DEDUCED defer(ExecutionContext& ctx, CompletionToken&& token);

  template<class Executor>
    class strand;

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

  template<class ProtoAllocator = allocator<void>>
    class use_future_t;

  constexpr use_future_t<> use_future = use_future_t<>();

  template<class ProtoAllocator, class Result, class... Args>
    class async_result<use_future_t<ProtoAllocator>, Result(Args...)>;

  template<class R, class... Args, class Signature>
    class async_result<packaged_task<Result(Args...)>, Signature>;

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

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

} // namespace std

[async.reqmts]

class my_service : public execution_context::service
{
public:
  typedef my_service key_type;
  explicit my_service(execution_context& ctx);
  my_service(execution_context& ctx, int some_value);
private:
  virtual void shutdown() noexcept override;
  ...
};

template<class S, class C = D> using X_t = typename X<S, C>::type;

template<class S, class C = D>
typename X<S, C>::type get_X(const S& s, const C& c = d)
{
  return X<S, C>::get(s, c);
}

template<class CompletionToken>
auto async_xyz(T1 t1, T2 t2, CompletionToken&& token)
{
  typename async_result<decay_t<CompletionToken>, void(R1, R2)>::completion_handler_type
    completion_handler(forward<CompletionToken>(token));

  async_result<decay_t<CompletionToken>, void(R1, R2)> result(completion_handler);

  // initiate the operation and cause completion_handler to be invoked with
  // the result

  return result.get();
}

template<class CompletionToken>
auto async_xyz(T1 t1, T2 t2, CompletionToken&& token)
{
  async_completion<CompletionToken, void(R1, R2)> init(token);

  // initiate the operation and cause init.completion_handler to be invoked
  // with the result

  return init.result.get();
}

[async.async.result]

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++Std [func.def]) for the completion handler type invoked on completion of the asynchronous operation. The async_result template:

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

— 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 = void>
  class async_result
  {
  public:
    typedef CompletionToken completion_handler_type;
    typedef void return_type;

    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++Std [func.def]).

Specializations of async_result shall satisfy the Destructible requirements (C++Std [destructible]) in addition to the requirements in the table below. 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.

[async.async.completion]

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
  {
    typedef async_result<decay_t<CompletionToken>,
      Signature>::completion_handler_type
        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++Std [func.def]).

explicit async_completion(CompletionToken& t);

see below completion_handler;

[async.assoc.alloc]

Class template associated_allocator is an associator for the ProtoAllocator 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
  {
    typedef see below type;

    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 the table below. In this table, X is a specialization of associated_allocator for the template parameters T and ProtoAllocator; t is a value of (possibly const) T; and a is an object of type ProtoAllocator.

typedef see below type;

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

[async.assoc.alloc.get]

template<class T>
  associated_allocator_t<T> get_associated_allocator(const T& t) noexcept;

template<class T, class ProtoAllocator>
  associated_allocator_t<T, ProtoAllocator>
    get_associated_allocator(const T& t, const ProtoAllocator& a) noexcept;

[async.exec.ctx]

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;

    // construct / copy / destroy:

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

    // execution context operations:

    void notify_fork(fork_event e);

  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. If the service is not present in an 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().

execution_context();

~execution_context();

void notify_fork(fork_event e);

void shutdown() noexcept;

void destroy() noexcept;

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;

[async.exec.ctx.svc]

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

  class execution_context::service
  {
  protected:
    // construct / copy / destroy:

    explicit service(execution_context& owner);
    service(const service&) = delete;
    service& operator=(const service&) = delete;
    virtual ~service();

    // service observers:

    execution_context& context() noexcept;

  private:
    // service operations:

    virtual void shutdown() noexcept = 0;
    virtual void notify_fork(fork_event e) {}

    execution_context& context_; // exposition only
  };

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

explicit service(execution_context& owner);

execution_context& context() noexcept;

[async.is.exec]

The class template is_executor can be used to detect executor types satisfying the 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++Std [meta.rqmts]) with a BaseCharacteristic of true_type if the type T meets the syntactic requirements for Executor, otherwise false_type.

[async.executor.arg]

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

  struct executor_arg_t { };
  constexpr executor_arg_t executor_arg = executor_arg_t();

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

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.uses.executor]

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

  template<class T, class Executor> struct uses_executor;

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

[async.assoc.exec]

Class template associated_allocator is an associator for the 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
  {
    typedef see below type;

    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 the table below. In this table, X is a specialization of associated_executor for the template parameters T and Executor; t is a value of (possibly const) T; and e is an object of type Executor.

typedef see below type;

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

[async.assoc.exec.get]