MCThreadPool Class Reference

Manages creation of threads and allocation of threads to jobs. More...

#include <mcllib/MCThreadPool.h>

Inheritance diagram for MCThreadPool:

List of all members.

Public Member Functions
mcuint32	addJob (MCThreadJob *pJob)
	Add a job to the pool.
void	join ()
	Wait until all the jobs have finished running.
	MCThreadPool (const MCString &name, mcuint32 maxConcurrency=1, MCThread::EType type=MCThread::THRTYPEUSER, MCThread::EScope scope=MCThread::THRSCOPELOCAL, MCThread::EState state=MCThread::THRSTATEJOIN, MCThread::EPriority pri=MCThread::THRPRINORMAL, mcstacksize_t sz=0)
	Construct a named thread pool object.
void	removeJob (mcuint32 jobId)
	Remove a job from the pool.
void	start ()
	Start the jobs in the pool running.
void	stop ()
	Stop the jobs in the pool running.

---

Detailed Description

Manages creation of threads and allocation of threads to jobs.

The MCThreadPool class is responsible for allocating threads to the different thread jobs (see MCThreadJob) that it is managing. Threads are created on demand and allocated to jobs to ensure that each job can keep up with the work it is doing.

The thread pool has jobs added to it with the addJob() method. Once all the necessary jobs have been added, the pool is set running with the start() method. To wait for all jobs in the pool to complete, the join() method is called. To prematurely stop all jobs call the stop() method.

Example.

  // Allow up to 20 threads in a pool called "MyPool"
  MCThreadPool pool("MyPool", 20);
  // Add three jobs to the pool
  pool.addJob(...);
  pool.addJob(...);
  pool.addJob(...);
  // Start the pool scheduling threads for the three jobs
  pool.start();
  // Wait for the jobs to complete
  pool.join();
 

If the thread pool is destructed the stop() method is called automatically.

See also:

MCThreadJob

---

Constructor & Destructor Documentation

MCThreadPool (  const MCString &  name, mcuint32  maxConcurrency = 1, MCThread::EType  type = MCThread::THRTYPEUSER, MCThread::EScope  scope = MCThread::THRSCOPELOCAL, MCThread::EState  state = MCThread::THRSTATEJOIN, MCThread::EPriority  pri = MCThread::THRPRINORMAL, mcstacksize_t  sz = 0 )

Construct a named thread pool object. The type and subsequent parameters are used when threads need to be created. It is possible to have different pools with different thread parameters (e.g. low priority for background threads, high priority for interactive or low-latency threads). Parameters: name  the name of the pool for diagnostic purposes. maxConcurrency  the maximum number of threads which may be executing within the pool. If the total minimum concurrency of all the jobs added to the pool exceeds the pool maximum concurrency the pool maximum concurrency is increased accordingly. type  the type of thread to start scope  the thread scope state  the thread state. Indicates whether the thread can be joined or not. pri  the thread priority. Higher priority threads get more CPU time than lower priority threads. sz  the size of the thread stack. Zero indicates that a default stack size should be used.

---

Member Function Documentation

mcuint32 addJob (  MCThreadJob *  pJob  )

Add a job to the pool. addJob() cannot be called once the pool has been start()ed. Parameters: pJob  a pointer to the job object to add to the pool. Note the job must have been allocated using new (i.e. no auto variables). The job must not be de-allocated (i.e. don't delete it). It will be de-allocated automatically when it is no longer referenced. Returns: a jobId which allows the job to be removed with the removeJob() method.

void join (   )

Wait until all the jobs have finished running. Returns immediately if the pool is not running.

void removeJob (  mcuint32  jobId  )

Remove a job from the pool. removeJob() cannot be called once the pool has been start()ed. Parameters: jobId  the id of a job added to the pool with addJob()

void start (   )

Start the jobs in the pool running. No threads will be created until start is called. Once start is called, enough threads will be created to satisfy the minimum concurrency requirements of all the jobs in the pool. Additional threads may be automatically created if the pool determines that this is required. Only the stop() or join() methods may be called after start(). Start is ignored if the pool is already running.

void stop (   )

Stop the jobs in the pool running. Stop is ignored if the pool is already stopped. Stop will end all jobs in the pool whether or not they have finished running. Stop will return once all threads managed by the pool have finished.

---