Why must io_service::reset() be called?

Question

io_service::reset documentation states that reset() must be called before subsequent calls to run(), run_one(), poll() or poll_one().

Questions:

• Why is this necessary? -
• What behaviour might I expect if this step is neglected?
• Why is this requirement not important enough to warrant an assert if it's neglected?

Some context: I finished debugging some unit-tests that checked that called poll() repeatedly without reset() and was attempting to check the expected number of handlers was being executed each time. It appears that with enough calls to poll(), all handlers are eventually executed in the order expected, but it takes more calls than you would otherwise expect. Correctly calling reset() fixes the problem, but I'm curious to know if this is the only side effect of not calling reset(), or if there are potentially worse effects such as dropping handlers or effects that might appear in a multi-threaded example.

Answer 1

When the io_service has been stopped:

• all invocations of poll(), poll_one(), run(), and run_one() will return as soon as possible
• subsequent calls to poll(), poll_one(), run(), and run_one() will return immediately without invoking any handlers or processing the event loop

Invoking io_service::reset() sets the io_service to no longer be in a stopped state, allowing subsequent calls to poll(), poll_one(), run(), and run_one() to invoke handlers and process the event loop.

---

Why is this necessary?

It is necessary if one wishes to invoke handlers or process the event loop once the io_service has been stopped explicitly via io_service.stop() or implicitly by running out of work.

What behaviour might I expect if this step is neglected?

If io_service.stopped() is true, then subsequent calls to poll(), poll_one(), run(), and run_one() will not perform any work.

Why is this requirement not important enough to warrant an assert if it's neglected?

The io_service::reset() documentation's use of the word "must" tends to set an overly critical tone without mentioning the consequences of not calling reset(). The behavior described by io_service::stop() is not critical enough to warrant an error:

• Subsequent calls to run(), run_one(), poll() or poll_one() will return immediately until reset() is called.

For reset(), the only hard requirement is to not call it when there are unfinished calls to poll(), poll_one(), run(), and run_one().