namespace std {
namespace experimental {
namespace net {
inline namespace v1 {
class io_context : public execution_context
{
public:
// types:
class executor_type;
using count_type = implementation-defined;
// construct / copy / destroy:
io_context();
explicit io_context(int concurrency_hint);
io_context(const io_context&) = delete;
io_context& operator=(const io_context&) = delete;
// io_context operations:
executor_type get_executor() noexcept;
count_type run();
template<class Rep, class Period>
count_type run_for(const chrono::duration<Rep, Period>& rel_time);
template<class Clock, class Duration>
count_type run_until(const chrono::time_point<Clock, Duration>& abs_time);
count_type run_one();
template<class Rep, class Period>
count_type run_one_for(const chrono::duration<Rep, Period>& rel_time);
template<class Clock, class Duration>
count_type run_one_until(const chrono::time_point<Clock, Duration>& abs_time);
count_type poll();
count_type poll_one();
void stop();
bool stopped() const noexcept;
void restart();
};
} // inline namespace v1
} // namespace net
} // namespace experimental
} // namespace std
The class io_context satisfies the ExecutionContext type requirements ([async.reqmts.executioncontext]).
The io_context member functions run, run_for, run_until, run_one, run_one_for, run_one_until, poll, and poll_one are collectively referred to as the run functions. The run functions must be called for the io_context to perform asynchronous operations ([defs.async.op]) on behalf of a C++ program. Notification that an asynchronous operation has completed is delivered by execution of the associated completion handler function object, as determined by the requirements for asynchronous operations ([async.reqmts.async]).
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 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.
If at any time the outstanding work falls to 0, the io_context is stopped as if by stop().
The io_context member functions get_executor, stop, and stopped, the run functions, and the io_context::executor_type copy constructors, member functions and comparison operators, do not introduce data races as a result of concurrent calls to those functions from different threads of execution. [ Note: The restart member function is excluded from these thread safety requirements. — end note ] The run functions may be recursively reentered.
io_context();
explicit io_context(int concurrency_hint);
Effects: Creates an object of class io_context.
Remarks: The concurrency_hint parameter is a suggestion to the implementation on the number of threads that should process asynchronous operations and execute function objects.
executor_type get_executor() noexcept;
Returns: An executor that may be used for submitting function objects to the io_context.
Effects: Equivalent to:
count_type n = 0;
while (run_one())
if (n != numeric_limits<count_type>::max())
++n;
Returns: n.
[ Note: Calling run from a thread that is currently calling a run function can introduce the potential for deadlock. It is the caller's responsibility to avoid such deadlocks. — end note ]
template<class Rep, class Period>
count_type run_for(const chrono::duration<Rep, Period>& rel_time);
Effects: Equivalent to:
return run_until(chrono::steady_clock::now() + rel_time);
template<class Clock, class Duration>
count_type run_until(const chrono::time_point<Clock, Duration>& abs_time);
Effects: Equivalent to:
count_type n = 0;
while (run_one_until(abs_time))
if (n != numeric_limits<count_type>::max())
++n;
Returns: n.
Effects: If the io_context object has no outstanding work, performs stop(). Otherwise, blocks while the io_context has outstanding work, or until the io_context is stopped, or until one function object has been executed.
If an executed function object throws an exception, the exception propagates to the caller of run_one(). The io_context state is as if the function object had returned normally.
Returns: 1 if a function object was executed, otherwise 0.
Remarks: This function may invoke additional function objects through nested calls to the io_context executor's dispatch member function. These do not count towards the return value.
[ Note: Calling run_one from a thread that is currently calling a run function can introduce the potential for deadlock. It is the caller's responsibility to avoid such deadlocks. — end note ]
template<class Rep, class Period>
count_type run_one_for(const chrono::duration<Rep, Period>& rel_time);
Effects: Equivalent to:
return run_one_until(chrono::steady_clock::now() + rel_time);
template<class Clock, class Duration>
count_type run_one_until(const chrono::time_point<Clock, Duration>& abs_time);
Effects: If the io_context object has no outstanding work, performs stop(). Otherwise, blocks while the io_context has outstanding work, or until the expiration of the absolute timeout (C++ 2014 [thread.req.timing]) specified by abs_time, or until the io_context is stopped, or until one function object has been executed.
If an executed function object throws an exception, the exception propagates to the caller of run_one(). The io_context state is as if the function object had returned normally.
Returns: 1 if a function object was executed, otherwise 0.
Remarks: This function may invoke additional function objects through nested calls to the io_context executor's dispatch member function. These do not count towards the return value.
Effects: Equivalent to:
count_type n = 0;
while (poll_one())
if (n != numeric_limits<count_type>::max())
++n;
Returns: n.
Effects: If the io_context object has no outstanding work, performs stop(). Otherwise, if there is a function object ready for immediate execution, executes it.
If an executed function object throws an exception, the exception propagates to the caller of poll_one(). The io_context state is as if the function object had returned normally.
Returns: 1 if a function object was invoked, otherwise 0.
Remarks: This function may invoke additional function objects through nested calls to the io_context executor's dispatch member function. These do not count towards the return value.
Effects: Stops the io_context. Concurrent calls to any run function will end as soon as possible. If a call to a run function is currently executing a function object, the call will end only after completion of that function object. The call to stop() returns without waiting for concurrent calls to run functions to complete.
Postconditions: stopped() == true.
[ Note: When stopped() == true, subsequent calls to a run function will exit immediately with a return value of 0, without executing any function objects. An io_context remains in the stopped state until a call to restart(). — end note ]
bool stopped() const noexcept;
Returns: true if the io_context is stopped.
Postconditions: stopped() == false.