A type A meets the proto-allocator requirements if A is CopyConstructible (C++ 2014 [copyconstructible]), Destructible (C++ 2014 [destructible]), and allocator_traits<A>::rebind_alloc<U> meets the allocator requirements (C++ 2014 [allocator.requirements]), where U is an object type. [ Note: For example, allocator<void> meets the proto-allocator requirements but not the allocator requirements. — end note ] No comparison operator, copy operation, move operation, or swap operation on these types shall exit via an exception.
The library describes a standard set of requirements for executors. A type meeting the Executor requirements embodies a set of rules for determining how submitted function objects are to be executed.
A type X meets the Executor requirements if it satisfies the requirements of CopyConstructible (C++ 2014 [copyconstructible]) and Destructible (C++ 2014 [destructible]), as well as the additional requirements listed below.
No comparison operator, copy operation, move operation, swap operation, or member functions context, on_work_started, and on_work_finished on these types shall exit via an exception.
The executor copy constructor, comparison operators, and other member functions defined in these requirements shall not introduce data races as a result of concurrent calls to those functions from different threads. The member function dispatch may be recursively reentered.
Let ctx be the execution context returned by the executor's context() member function. An executor becomes invalid when the first call to ctx.shutdown() returns. The effect of calling on_work_started, on_work_finished, dispatch, post, or defer on an invalid executor is undefined. [ Note: The copy constructor, comparison operators, and context() member function continue to remain valid until ctx is destroyed. — end note ]
In Table [tab:async.reqmts.executor.requirements], x1 and x2 denote (possibly const) values of type X, mx1 denotes an xvalue of type X, f denotes a function object of MoveConstructible (C++ 2014 [moveconstructible]) type Func such that f() is a valid expression, a denotes a (possibly const) value of type A where A is a type meeting the ProtoAllocator requirements ([async.reqmts.proto.allocator]), and u denotes an identifier.
| expression | type | assertion/note pre/post-conditions |
| X u(x1); |
Shall not exit via an exception. post: u == x1 and std::addressof(u.context()) == std::addressof(x1.context()). | |
| X u(mx1); |
Shall not exit via an exception. post: u equals the prior value of mx1 and std::addressof(u.context()) equals the prior value of std::addressof(mx1.context()). | |
| x1 == x2 | bool |
Returns true only if x1 and x2 can be interchanged with identical effects in any of the expressions defined in these type requirements. [ Note: Returning false does not necessarily imply that the effects are not identical. — end note ] operator== shall be reflexive, symmetric, and transitive, and shall not exit via an exception. |
| x1 != x2 | bool | Same as !(x1 == x2). |
| x1.context() | execution_context&, or E& where E is a type that satisfies the ExecutionContext ([async.reqmts.executioncontext]) requirements. | Shall not exit via an exception. The comparison operators and member functions defined in these requirements shall not alter the reference returned by this function. |
| x1.on_work_started() | Shall not exit via an exception. | |
| x1.on_work_finished() |
Shall not exit via an exception. Precondition: A preceding call x2.on_work_started() where x1 == x2. | |
| x1.dispatch( std::move(f), a) |
Effects: Creates an object f1 initialized with DECAY_COPY(std::forward<Func>(f)) (C++ 2014 [thread.decaycopy]) in the current thread of execution. Calls f1() at most once. The executor may block forward progress of the caller until f1() finishes execution. Executor implementations should use the supplied allocator to allocate any memory required to store the function object. Prior to invoking the function object, the executor shall deallocate any memory allocated. [ Note: Executors defined in this document always use the supplied allocator unless otherwise specified. — end note ] Synchronization: The invocation of dispatch synchronizes with (C++ 2014 [intro.multithread]) the invocation of f1. | |
| x1.post(std::move(f), a) |
Effects: Creates an object f1 initialized with DECAY_COPY(std::forward<Func>(f)) in the current thread of execution. Calls f1() at most once. The executor shall not block forward progress of the caller pending completion of f1(). The executor may begin f1's progress before the call to post completes. Executor implementations should use the supplied allocator to allocate any memory required to store the function object. Prior to invoking the function object, the executor shall deallocate any memory allocated. [ Note: Executors defined in this document always use the supplied allocator unless otherwise specified. — end note ] Synchronization: The invocation of post synchronizes with (C++ 2014 [intro.multithread]) the invocation of f1. | |
| x1.defer(std::move(f), a) |
Effects: Creates an object f1 initialized with DECAY_COPY(std::forward<Func>(f)) in the current thread of execution. Calls f1() at most once. The executor shall not block forward progress of the caller pending completion of f1(). The executor should not begin f1's progress before the call to defer completes. [ Note: One use of defer is to convey the intention of the caller that f1 is a continuation of the current call context. The executor can use this information to optimize or otherwise adjust the way in which f1 is invoked. — end note ] Executor implementations should use the supplied allocator to allocate any memory required to store the function object. Prior to invoking the function object, the executor shall deallocate any memory allocated. [ Note: Executors defined in this document always use the supplied allocator unless otherwise specified. — end note ] Synchronization: The invocation of defer synchronizes with (C++ 2014 [intro.multithread]) the invocation of f1. |
A type X meets the ExecutionContext requirements if it is publicly and unambiguously derived from execution_context, and satisfies the additional requirements listed below.
In Table [tab:async.reqmts.executioncontext.requirements], x denotes a value of type X.
| expression | return type | assertion/note pre/post-condition |
| X::executor_type | type meeting Executor ([async.reqmts.executor]) requirements | |
| x.~X() | Destroys all unexecuted function objects that were submitted via an executor object that is associated with the execution context. | |
| x.get_executor() | X::executor_type | Returns an executor object that is associated with the execution context. |
A class is a service if it is publicly and unambiguously derived from execution_context::service, or if it is publicly and unambiguously derived from another service. For a service S, S::key_type shall be valid and denote a type (C++ 2014 [temp.deduct]), is_base_of_v<typename S::key_type, S> shall be true, and S shall satisfy the Destructible requirements (C++ 2014 [destructible]).
The first parameter of all service constructors shall be an lvalue reference to execution_context. This parameter denotes the execution_context object that represents a set of services, of which the service object will be a member. [ Note: These constructors can be called by the make_service function. — end note ]
A service shall provide an explicit constructor with a single parameter of lvalue reference to execution_context. [ Note: This constructor can be called by the use_service function. — end note ]
[ Example:
class my_service : public execution_context::service{
public:
using key_type = my_service;
explicit my_service(execution_context& ctx);
my_service(execution_context& ctx, int some_value);
private:
virtual void shutdown() noexcept override;
...
};
— end example ]
A service's shutdown member function shall destroy all copies of function objects that are held by the service.
A type satisfies the signature requirements if it is a call signature (C++ 2014 [func.def]).
An associator defines a relationship between different types and objects where, given:
a source object s of type S,
type requirements R, and
a candidate object c of type C meeting the type requirements R,
an associated type A meeting the type requirements R may be computed, and an associated object a of type A may be obtained.
An associator shall be a class template that takes two template type arguments. The first template argument is the source type S. The second template argument is the candidate type C. The second template argument shall be defaulted to some default candidate type D that satisfies the type requirements R.
An associator shall additionally satisfy the requirements in Table [tab:async.reqmts.associator.requirements]. In this table, X is a class template that meets the associator requirements, S is the source type, s is a value of type S or const S, C is the candidate type, c is a (possibly const) value of type C, D is the default candidate type, and d is a (possibly const) value of type D that is the default candidate object.
| expression | return type | assertion/note pre/post-conditions |
| X<S>::type | X<S, D>::type | |
| X<S, C>::type | The associated type. | |
| X<S>::get(s) | X<S>::type | Returns X<S>::get(S, d). |
| X<S, C>::get(s, c) | X<S, C>::type | Returns the associated object. |
The associator's primary template shall be defined. A program may partially specialize the associator class template for some user-defined type S.
Finally, the associator shall provide the following type alias and function template in the enclosing namespace:
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);
}
where X is replaced with the name of the associator class template. [ Note: This function template is provided as a convenience, to automatically deduce the source and candidate types. — end note ]
This subclause uses the names Alloc1, Alloc2, alloc1, alloc2, Args, CompletionHandler, completion_handler, Executor1, Executor2, ex1, ex2, f, i, N, Signature, token, Ti, ti, work1, and work2 as placeholders for specifying the requirements below.
An initiating function is a function which may be called to start an asynchronous operation. A completion handler is a function object that will be invoked, at most once, with the result of the asynchronous operation.
The life cycle of an asynchronous operation is comprised of the following events and phases:
Event 1: The asynchronous operation is started by a call to the initiating function.
Phase 1: The asynchronous operation is now outstanding.
Event 2: The externally observable side effects of the asynchronous operation, if any, are fully established. The completion handler is submitted to an executor.
Phase 2: The asynchronous operation is now completed.
Event 3: The completion handler is called with the result of the asynchronous operation.
In this document, all functions with the prefix async_ are initiating functions.
Initiating functions:
are function templates with template parameter CompletionToken;
accept, as the final parameter, a completion token object token of type CompletionToken;
specify a completion signature, which is a call signature (C++ 2014 [func.def]) Signature that determines the arguments to the completion handler.
An initiating function determines the type CompletionHandler of its completion handler function object by performing typename async_result<decay_t<CompletionToken>, Signature>::completion_handler_type. The completion handler object completion_handler is initialized with std::forward<CompletionToken>(token). [ Note: No other requirements are placed on the type CompletionToken. — end note ]
The type CompletionHandler shall satisfy the requirements of Destructible (C++ 2014 [destructible]) and MoveConstructible (C++ 2014 [moveconstructible]), and be callable with the specified call signature.
In this document, all initiating functions specify a Completion signature: element that defines the call signature Signature. The Completion signature: elements in this document have named parameters, and the results of an asynchronous operation are specified in terms of these names.
The return type of an initiating function is typename async_result<decay_t<CompletionToken>, Signature>::return_type.
For the sake of exposition, this document sometimes annotates functions with a return type DEDUCED. For every function declaration that returns DEDUCED, the meaning is equivalent to specifying the return type as typename async_result<decay_t<CompletionToken>, Signature>::return_type.
An initiating function produces its return type as follows:
constructing an object result of type async_result<decay_t<CompletionToken>, Signature>, initialized as result(completion_handler); and
using result.get() as the operand of the return statement.
[ Example: Given an asynchronous operation with Completion signature void(R1 r1, R2 r2), an initiating function meeting these requirements may be implemented as follows:
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();
}
For convenience, initiating functions may be implemented using the async_completion template:
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();
}
— end example ]
Unless otherwise specified, the lifetime of arguments to initiating functions shall be treated as follows:
If the parameter has a pointer type or has a type of lvalue reference to non-const, the implementation may assume the validity of the pointee or referent, respectively, until the completion handler is invoked. [ Note: In other words, the program is responsible for guaranteeing the validity of the argument until the completion handler is invoked. — end note ]
Otherwise, the implementation does not assume the validity of the argument after the initiating function completes. [ Note: In other words, the program is not required to guarantee the validity of the argument after the initiating function completes. — end note ] The implementation may make copies of the argument, and all copies shall be destroyed no later than immediately after invocation of the completion handler.
An initiating function shall not block (C++ 2014 [defns.block]) the calling thread pending completion of the outstanding operation.
[ Note: Initiating functions can still block the calling thread for other reasons. For example, if an initiating function locks a mutex in order to synchronize access to shared data. — end note ]
Certain objects that participate in asynchronous operations have an associated executor. These are obtained as specified below.
An asynchronous operation has an associated executor satisfying the Executor ([async.reqmts.executor]) requirements. If not otherwise specified by the asynchronous operation, this associated executor is an object of type system_executor.
All asynchronous operations in this document have an associated executor object that is determined as follows:
If the initiating function is a member function, the associated executor is that returned by the get_executor member function on the same object.
If the initiating function is not a member function, the associated executor is that returned by the get_executor member function of the first argument to the initiating function.
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.
A completion handler object of type CompletionHandler has an associated executor satisfying the Executor requirements ([async.reqmts.executor]). 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).
Until the asynchronous operation has completed, the asynchronous operation shall maintain:
an object work1 of type executor_work_guard<Executor1>, initialized as work1(ex1), and where work1.owns_work() == true; and
an object work2 of type executor_work_guard<Executor2>, initialized as work2(ex2), and where work2.owns_work() == true.
Asynchronous operations may allocate memory. [ Note: Such as a data structure to store copies of the completion_handler object and the initiating function's arguments. — end note ]
Let Alloc1 be a type, satisfying the ProtoAllocator ([async.reqmts.proto.allocator]) requirements, that represents the asynchronous operation's default allocation strategy. [ Note: Typically allocator<void>. — end note ] Let alloc1 be a value of type Alloc1.
A completion handler object of type CompletionHandler has an associated allocator object alloc2 of type Alloc2 satisfying the ProtoAllocator ([async.reqmts.proto.allocator]) requirements. The type Alloc2 is associated_allocator_t<CompletionHandler, Alloc1>. Let alloc2 be a value of type Alloc2 obtained by performing get_associated_allocator(completion_handler, alloc1).
The asynchronous operations defined in this document:
If required, allocate memory using only the completion handler's associated allocator.
Prior to completion handler execution, deallocate any memory allocated using the completion handler's associated allocator.
[ Note: The implementation can perform operating system or underlying API calls that perform memory allocations not using the associated allocator. Invocations of the allocator functions do not introduce data races (see C++ 2014 [res.on.data.races]). — end note ]
Let Args... be the argument types of the completion signature Signature and let N be sizeof...(Args). Let i be in the range [0, N). Let Ti be the ith type in Args... and let ti be the ith completion handler argument associated with Ti.
Let f be a function object, callable as f(), that invokes completion_handler as if by completion_handler(forward<T0>(t0), ..., forward<TN-1>(tN-1)).
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 performing ex2.post(std::move(f), alloc2). Otherwise, the completion handler shall be submitted for execution as if by performing ex2.dispatch(std::move(f), alloc2).
Completion handlers are permitted to throw exceptions. The effect of any exception propagated from the execution of a completion handler is determined by the executor which is executing the completion handler.
In this document, a composed asynchronous operation is an asynchronous operation that is implemented in terms of zero or more intermediate calls to other asynchronous operations. The intermediate asynchronous operations are performed sequentially. [ Note: That is, the completion handler of an intermediate operation initiates the next operation in the sequence. — end note ]
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 ([async.reqmts.executor]), that delegates executor operations to the type Executor2 and object ex2.
An intermediate operation's completion handler shall have an associated allocator that is either:
the type Alloc2 and object alloc2 obtained from the completion handler type CompletionHandler and object completion_handler; or
an object of an unspecified type satisfying the ProtoAllocator requirements ([async.reqmts.proto.allocator]), that delegates allocator operations to the type Alloc2 and object alloc2.