[io_context.io_context.members] run()/run_one() specification overly restrictive on users

[chriskohlhoff]

Both the run() and run_one() functions include the following statement:

Must not be called from a thread that is currently calling a run function.

This restriction was originally added as a way to prevent users from entering a kind of "deadlock". This is because run() and run_one() can block until the io_context runs out of work. Since outstanding work includes currently executing function objects, if a function object makes a nested call to run()/run_one() that nested call could block forever as the work count can never reach zero.

However, it has been brought to my attention by users that there are valid use cases for making these nested calls. Deadlock can be avoided if some other condition will cause run()/run_one() to exit (e.g. an exception, explicit call to stop, run_one finished running a single function, etc). This condition can be known ahead of time by the user.

The existing implementation in asio does not make any beneficial use of this restriction.

Therefore, I propose striking those sentences from both those places. It is the responsibility of the user to avoid the conditions for deadlock.

[jwakely]

I'd be OK with replacing the normative preconditions with a note saying there's a potential for deadlock, which the user must avoid.