14 Basic I/O services [io_context]

14.2 Class io_context [io_context.io_context]

14.2.1 io_context members [io_context.io_context.members]

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.

count_type run();

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.

count_type run_one();

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.

count_type poll();

Effects: Equivalent to:

count_type n = 0;
while (poll_one())
  if (n != numeric_limits<count_type>::max())
    ++n;

Returns: n.

count_type poll_one();

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.

void stop();

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.

void restart();

Postconditions: stopped() == false.