boost::asio io_service thread pool

Question

What's the proper usage of settings up a thread pool for io_service? These 2 statements from the documentation are throwing me off:

io_service::run

A normal exit from the run() function implies that the io_service object is stopped (the stopped() function returns true). Subsequent calls to run(), run_one(), poll() or poll_one() will return immediately unless there is a prior call to reset().

io_service::reset

This function must be called prior to any second or later set of invocations of the run(), run_one(), poll() or poll_one() functions when a previous invocation of these functions returned due to the io_service being stopped or running out of work.

Here's what I'm currently doing:

boost::thread_group     m_Threads;
boost::asio::io_service m_IoService;
boost::barrier          m_Barrier(numThreads);

for( unsigned int i = 0; i < numThreads; ++i )
{
    m_Threads.create_thread(
        [&]()
        {
            for(;;)
            {
                m_IoService.run();

                if( m_Barrier.wait() )  //  will only return true for 1 thread
                {
                    m_IoService.reset();
                }
                m_Barrier.wait();
            }
        });
}

m_IoService.stop();
m_Threads.interrupt_all();
m_Threads.join_all();

Everything seems to work fine if I just put m_IoService.run() in an infinite loop (which the documentation seems to indicate should not be the case). What's the correct way?

Solution

run() is a blocking call, and will execute all events that it can before returning. It will only return if there are no more events to handle. Once it returns, you must call reset() on the io_service before calling run() again.

You can have multiple threads calling run() - this is not a problem, and you don't need the infinite loop as long as the io_service has some work to do. The normal pattern for this is to create a work object on the io_service which will force run() to never return. This does mean that you explicitly have to call stop() on the io_service when you are done as it will never naturally exit.

If you setup a work on the io_service, it will never naturally exit and therefore you will never need to call reset().

work some_work(m_IoService); // this will keep the io_service live.

for( unsigned int i = 0; i < numThreads; ++i )
{
  m_Threads.create_thread(
    [&]()
    {
      m_IoService.run();
    });
}

Now all threads are dispatching events on the io_service

// Now post your jobs
m_IoService.post(boost::bind(...)); // this will be executed in one of the threads
m_IoService.post(boost::bind(...)); // this will be executed in one of the threads
m_IoService.post(boost::bind(...)); // this will be executed in one of the threads

m_IoService.stop(); // explicitly stop the io_service
// now join all the threads and wait for them to exit

Comments

[David]

Random threading question: Is there any need to call boost::this_thread::yield() after m_IoService.run()?

[Nim]

@Dave - it's pointless, execution will only reach that point once run() exits.

[Arvid]

I would argue that it's cleaner to always let run() exit cleanly. If you need to make sure the io_service stays alive when you're out of events, create a work object and destroy it when it's time to exit. That way all pending events will fire, allowing everything to clean up.

[jean]

what if I change post to dispatch? Jobs will be executed by different threads?

[Nim]

@jean, post() will always queue (and therefore be executed in a different context), dispatch() may execute in the current context if possible, else will queue (like post()).