threadpool | Overview | Reference | Tutorial | Examples | Design

Tutorial | Quick Start | Prioritized Tasks | Arbitrary Task Functions | Advanced Pool Instantiation

Quick Start

This tutorial introduces the threadpool library by discussing an easy to understand source listing:

    01
    02  #include "threadpool.hpp"
    03
    04  using namespace boost::threadpool;
    05
    06  // Some example tasks
    07  void first_task()
    08  {
    09    ...
    10  }
    11
    13  void second_task()
    14  {
    15    ...
    16  }
    17
    19  void third_task()
    20  {
    21    ...
    22  }
    23
    24  void execute_with_threadpool()
    25  {
    26    // Create a thread pool.
    27    pool tp(2);
    28
    29    // Add some tasks to the pool.
    30    tp.schedule(&first_task);
    31    tp.schedule(&second_task);
    32    tp.schedule(&third_task);
    33
    34    // Leave this function and wait until all tasks are finished.
    35  }
    36

We start by including the necessary header files. The complete threadpool functionality can be used by simply including the "threadpool.hpp" header file at line 2.

The three functions first_task(), second_task and third_task() are placeholders for tasks that should be executed by our pool.

The thread pool is created at line 27. The argument indicates the number of initial threads. The new pool contains two threads that is two tasks can be processed in parallel. The pool's threads are sleeping until tasks are added. By default it uses a Fifo scheduling strategy. Fifo is an abbreviation of "first in, first out" and means in this case that the first task which is added is the first that will be executed. Generally this is the expected default behaviour since the tasks are executed in the order they are added to the pool.

In line 30 to 32 the task functions are scheduled asynchronously using the pool's schedule function. A task is registered and it will be executed as soon as one of the pool's threads is idle. It is very important to understand that the task is only scheduled for execution. Schedule returns immediately and there are no guarantees about when the tasks are executed and how long the processing will take. As they are added to a fifo pool with two threads the following is true:

- the execution of first_task begins first
- second_task is started after first_task
- third_task is begun at last
- a maximum of two tasks may are processed in parallel
- each scheduled task will be executed once only

The pool reference tp is created in the scope of the function execute_with_threadpool(). When this function returns at line 35 tp goes out of scope and the pool will be destructed. As the default ShutdownPolicy is wait_for_all_tasks it is ensured that all tasks are processed before the pool is destroyed.

    101
    102  ...
    103  execute_with_threadpool();  // execute first_task, second_task and third_task
    104  // When this line is reached all tasks are finished and the pool is destructed.
    105

The small code example clarifies the issue. When the function leaves the pool is shut down and waits for the tasks. That means the current thread of execution is blocked at the end of the execute_with_threadpool as long as the processing of tasks is in progress.

Copyright © 2005-2008 Philipp Henkel | Overview | Reference | Tutorial | Examples | Design