tutorial.txt

threadpool is a cross-platform C++ thread pool library

/*! \page intro Quick Start

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

\code
01 
02  #include "threadpool.hpp"
03
04  using namespace 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 fifo thread pool container with two threads.
27    smart_pool<fifo_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    //  Wait until all tasks are finished.
35    tp->join();
36    
37    // Now all tasks are finished!
38  }
39
\endcode

We start by including the 
necessary header files. All of the threadpool classes 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 long running task that should be executed by our pool. 

A fifo pool is created at line 27. Fifo is an abbreviation of "first in, first out"
and means in the case of a thread pool that the first task which is added is the
first that will be executed. Generally that is the expected default behaviour
since the tasks are executed in the order they are added to the pool. The new pool
contains two threads that is two tasks can be processed in parallel.

In line 30 to 32 the task functions are scheduled asynchronously. The function schedule()
returns immediately. 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 of size 2 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

To make sure that all scheduled tasks are finished before we proceed in
our program the function join() is called at line 35. join() blocks as long as
the processing of tasks in the pool is in progress.

*/


/*! \page prioritized Prioritized Tasks

It's easy to prioritize asynchronous tasks by using the task adaptor prio_thread_func. 
The following source listing illustrates how to setup the pool and add the tasks:

\code
01 
02  #include "threadpool.hpp"
03
04  using namespace threadpool;
05
06  // Some example tasks
07  void nonrelevant_task()
08  {
09    ...
10  }
11
13  void important_task()
14  {
15    ...
16  }
17  
18  void execute_prioritized()
19  {
20    // Create prioritized thread pool container without any threads.
21    smart_pool<prio_pool> tp(0);
22
23    // Add some tasks to the pool.
24    tp->schedule(prio_thread_func(5,   &nonrelevant_task));
25    tp->schedule(prio_thread_func(100, &important_task));
26    tp->schedule(prio_thread_func(7,   &nonrelevant_task));
27
28    // Add the first thread to the pool.
29    tp->resize(1);
30
31    // The tasks are executed according to their priority: important_task(100), nonrelevant_task(7), nonrelevant_task(5).
32
33    tp->join();
34    
35    // Now all tasks are finished and the pool can be destroyed safely.
36  }
37
\endcode

Once again we start including the main header file and defining some tasks.

At line 21 a prioritized thread pool is created. That means that the pool's tasks are ordered 
according to their priority before they get executed. Therefore the tasks themselves have to realize a partial ordering based 
on operator<. 

The adaptor prio_thread_func satisfies our requirements regarding the ordering and is just a small wrapper object for 
the task functions. In line 24 to 26 some prioritized tasks are scheduled.

At line 29 the first thread is added to the pool and the execution of important_task begins. As we have only one thread 
the tasks are processed sequentially.

Finally join() is called to ensure that all tasks are finished before our example function returns 
and the pool is destroyed. This is very important since the behavior is undefined if pool's lifetime ends while tasks are executed.

*/


/*! \page task_adaptor Arbitrary Task Functions
#if 0
TODO <BR>
boost::bind(member_function, shared_ptr)
26    tp->schedule(boost::bind(task_with_parameter, 42));
12  // Second example task
13  void task_with_parameter(int value)
14  {
15    ...
16  }
#endif
*/
 
 
/*! \page instantiation Advanced Instantiation

TODO <BR>
Pool instantiation
\code

    // use threadpool::pool directly, no pool adaptor is involved
    typedef threadpool::pool<boost::function0<void>, threadpool::fifo_scheduler<boost::function0<void> > > pool_type;

    boost::shared_ptr< pool_type > tp = pool_type::create_pool(5);			

    // same pool as threadpool::fifo_pool(5)

    print("  Add tasks ...\n");
    tp->schedule(&task_1);
    tp->schedule(&task_2);
    tp->schedule(&task_3);
    tp->schedule(&task_4);

    print("  Wait until all tasks are finished ...\n");
    tp->join();
    print("  Tasks finished\n");
\endcode


*/