Docs about calling sync APIs

[anarthal]

Complementing #43. Discuss the possible approaches in the docs, even if they don't get shown in code.

[anarthal]

Code like the following is viable:

// Given a 3rd-party function sync_get_db_customer that may block for some time
// and returns a customer object (plain data), we could write the following wrapper:

class db_client
{
    // configure this with the number of threads you want
    boost::asio::thread_pool pool_;
public:
    customer get_customer(boost::asio::yield_context yield)
    {
        // A channel is a structure to communicate between coroutines.
        // concurrent_channel is thread-safe
        boost::asio::experimental::concurrent_channel<void(error_code, customer)> chan{yield.get_executor()};
       
        // Whatever function we pass to post() will be run in the thread pool
        boost::asio::post(pool_.get_executor(), [&chan] {
            // This is now running in the thread_pool. Call the sync function
            customer res = sync_get_db_customer();

            // Communicate the result back to the coroutine
            chan.async_send(error_code(), std::move(res), boost::asio::detached);
        });

        // The coroutine will suspend until the result is ready, allowing
        // other coroutines to make progress
        return chan.async_receive(yield);
    }
};

[anarthal]

Alternative as contributed by @mzimbres:

asio::awaitable<void> coro(asio::any_io_executor async_ex, asio::any_io_executor sync_ex)
{
	// Do async stuff.
	std::cout << "Thread id 1: " << std::this_thread::get_id() << std::endl;

	// Switch to the executor to do sync stuff.
	co_await asio::post(asio::bind_executor(sync_ex, use_awaitable));

	// Sync code
	std::cout << "Thread id 2: " << std::this_thread::get_id() << std::endl;

	// Back to the executor where we do async stuff.
	co_await asio::post(asio::bind_executor(async_ex, use_awaitable));

	// More async
	std::cout << "Thread id 1: " << std::this_thread::get_id() << std::endl;
}

int main()
{
	boost::asio::io_context ioc1;
	boost::asio::io_context ioc2; // Performs sync work.

	// Spawns the coroutine in ioc1 and then switches to ioc2.
	asio::co_spawn(ioc1, coro(ioc1.get_executor(), ioc2.get_executor()), asio::detached);

	std::thread t2{[&](){ioc2.run();}};

	ioc1.run();
	t2.join();
}
``