[boost] [threadpool] remarques to the documentation

Subject: [boost] [threadpool] remarques to the documentation
From: vicente.botet (vicente.botet_at_[hidden])
Date: 2008-09-16 02:06:52

Hi,

I'm reading the documentation and I don't find any description of the 
concepts Strategy, Channel, QueueingPolicy, Callable.
Do you plan to describe explicitly these concepts in the documentation ?

What do you think about adding a Worker concept, and adding it as parameter 
to the Strategy template class?

I think that the tutorial must be reworked, including more practical 
examples, and starting from the most basic use and going on each one of the 
use cases where the different features are better adapted, currently it 
seams more to a informal reference manual.

Some naming suggestions:
* ThreadManagementStrategy sould be a better name for Strategy.
* As QueueingPolicy can be either fifo or lifo, SchedulingPolicy sould be 
more apropiated.
* Pending tasks can be more adecuated than queued tasks. You can use take 
instead of dequeue which is more general.

Could you give a use case for lifo order?
What about a manual thread management strategy, allowing the user to add new 
workers or interrupting them?

A copy/paste: In the fixed example there is a reference to tp::channel which 
should be tp::bounded_channel.

In the lazy example

// creates a lazy pool with unbounded channel
// tasks are processed in FIFO order
// the pool contains ten worker threads
// no worker threads are started at construction
boost::tp::pool<
  boost::tp::lazy< depend_on_core >,
  boost::tp::unbounded_channel< boost::tp::fifo >
> pool(
  boost::tp::core_poolsize( 5)
  boost::tp::max_poolsize( 10) );

Can this pool have more than 5 worker threads? If the worker threads are 
created  "if current poolsize size is less than core_poolsize or the channel 
is full", as the channel is unbounded_channel the channel will never be 
full, so when the current poolsize size will be 5 no new threads will be 
created, ins't it?

the adaptive ThreadManagementStrategy  seems to be in contradiction to the 
goal of the threadpool "Using a thread pool over creating a new thread for 
each task may result in better performance and better system stability 
because the overhead for thread creation and destruction is negated." Could 
you present a use case in which this adaptive strategy could be useful?

In channnel section you say "If the channel becomes empty all worker threads 
are set to sleep until a new task is enqueued." Except for the adaptive 
strategy which has a keep_alive timeout, the other waits until a new task is 
submited, isn't it?

Which are the advantages/liabilities of a bounded channel respect to an 
unbounded one? When it is better to use one of them?

It will be great to have an example justifying the need for the rendezvous 
channel.

A copy/paste: In the smart section smart must replace priority
template< typename Attr, typename Ord, typename Enq, typename Deq > struct 
priority

A typo: replace terminateing  by terminating in docs and in code

Best regrads,
Vicente