SourcePro® API Reference Guide

 
Loading...
Searching...
No Matches
RWThreadPool Class Reference

Manages a pool of RWThread instances used to execute work encapsulated as RWTFunctor<void()> functors. More...

#include <rw/thread/RWThreadPool.h>

Inheritance diagram for RWThreadPool:
RWHandleBase

Public Member Functions

 RWThreadPool ()
 
 RWThreadPool (const RWThreadPool &second)
 
 ~RWThreadPool ()
 
void enqueue (const RWTFunctor< void()> &functor)
 
size_t entries () const
 
RWThreadAttribute getPoolAttribute ()
 
RWThreadPooloperator= (const RWThreadPool &second)
 
bool resize (size_t minThreads, size_t maxThreads=RW_THR_NO_DYNAMIC_THREAD_POOL)
 
size_t size () const
 
void stop ()
 
- Public Member Functions inherited from RWHandleBase
bool isValid (void) const
 
bool operator!= (const RWHandleBase &second) const
 
bool operator== (const RWHandleBase &second) const
 

Static Public Member Functions

static RWThreadPool make (size_t minThreads, const RWThreadAttribute &poolThreadsAttr, size_t maxThreads=RW_THR_NO_DYNAMIC_THREAD_POOL, unsigned long timeout=RW_THR_NO_TIMEOUT)
 
static RWThreadPool make (size_t minThreads, size_t maxThreads=RW_THR_NO_DYNAMIC_THREAD_POOL, unsigned long timeout=RW_THR_NO_TIMEOUT)
 

Related Symbols

(Note that these are not member symbols.)

const size_t RW_THR_NO_DYNAMIC_THREAD_POOL
 
const unsigned long RW_THR_NO_TIMEOUT
 

Additional Inherited Members

- Protected Member Functions inherited from RWHandleBase
 RWHandleBase (const RWHandleBase &second)
 
 RWHandleBase (RWBodyBase *body)
 
 RWHandleBase (RWStaticCtor)
 
 RWHandleBase (void)
 
 ~RWHandleBase (void)
 
RWBodyBasebody (void) const
 
RWHandleBaseoperator= (const RWHandleBase &second)
 

Detailed Description

The RWThreadPool object manages a pool of RWThread instances that are used to execute work encapsulated as RWTFunctor<void()> functors. A thread pool object, when started, waits for other threads to enqueue work functors for execution.

Pool threads dequeue functors and execute them to completion. This process continues until the thread pool object passes out of scope, its destructor is called, or the stop() member function is called.

A thread pool can have a fixed number of threads, or its size may grow and shrink dynamically, according to load. The dynamic nature of the pool is controlled by parameters in the make() member function.

Example
#include <rw/thread/RWThreadPool.h>
#include <rw/functor/RWTFunctor.h>
#include <rw/sync/RWMutexLock.h>
#include <iostream>
RWMutexLock coutLock;
void work() {
RWMutexLock::LockGuard guard(coutLock);
std::cout << "Hi-ho, hi-ho, it's off to work we go" << std::endl;
}
void play() {
RWMutexLock::LockGuard guard(coutLock);
std::cout << "Catch a wave and you're sittin' on top of the world"
<< std::endl;
}
int main() {
RWTFunctor<void()> workFunc = work;
RWTFunctor<void()> playFunc = play;
thrPool.enqueue(workFunc);
thrPool.enqueue(playFunc);
// stop after all enqueued functors complete:
thrPool.stop();
return 0;
};
Implements a mutex, or mutual exclusion lock.
Definition RWMutexLock.h:231
A guard that acquires its resource upon creation and releases it upon destruction.
Definition RWTLockGuard.h:61
Manages a pool of RWThread instances used to execute work encapsulated as RWTFunctor<void()> functors...
Definition RWThreadPool.h:81
static RWThreadPool make(size_t minThreads, size_t maxThreads=RW_THR_NO_DYNAMIC_THREAD_POOL, unsigned long timeout=RW_THR_NO_TIMEOUT)
void enqueue(const RWTFunctor< void()> &functor)
See also
RWThread, RWTFunctor, RWHandleBase::isValid()

Constructor & Destructor Documentation

◆ RWThreadPool() [1/2]

RWThreadPool::RWThreadPool ( )
inline

Constructs an empty (invalid) handle.

◆ RWThreadPool() [2/2]

RWThreadPool::RWThreadPool ( const RWThreadPool & second)
inline

Constructs a new external interface handle to the thread pool object that is pointed to by a second handle (if any).

◆ ~RWThreadPool()

RWThreadPool::~RWThreadPool ( )
inline

Destructor.

Member Function Documentation

◆ enqueue()

void RWThreadPool::enqueue ( const RWTFunctor< void()> & functor)

Enqueues a piece of work in the functor onto the thread pool. All functors must be valid; that is, functor.isValid() must return true. All exceptions that might be thrown within functor must be handled within functor.

Invalid functors and exceptions thrown by functors but not caught by functors are ignored in the release version of the compiled source code. During initial development, therefore, you should compile source code in debug mode, which throws assertions when invalid functors are found or uncaught exceptions are thrown.

◆ entries()

size_t RWThreadPool::entries ( ) const

Returns the number of work entries queued in the thread pool.

◆ getPoolAttribute()

RWThreadAttribute RWThreadPool::getPoolAttribute ( )

Gets a handle to the thread attribute instance specified during thread pool construction.

◆ make() [1/2]

static RWThreadPool RWThreadPool::make ( size_t minThreads,
const RWThreadAttribute & poolThreadsAttr,
size_t maxThreads = RW_THR_NO_DYNAMIC_THREAD_POOL,
unsigned long timeout = RW_THR_NO_TIMEOUT )
static

Makes a thread pool instance that contains a number of threads from minThreads to maxThreads, each with the specified thread attributes. The actual number of threads grows and shrinks between minThreads and maxThreads, depending on the work load. A thread awaits work for at least timeout milliseconds before exiting.

You are responsible for ensuring the suitability of thread pool attributes. For example, a poolThreadsAttri start policy of RW_THR_START_INTERRUPTED would cause RWThreadPool to hang because all threads in the thread pool would be waiting for RWRunnable::releaseInterrupt() calls.

◆ make() [2/2]

static RWThreadPool RWThreadPool::make ( size_t minThreads,
size_t maxThreads = RW_THR_NO_DYNAMIC_THREAD_POOL,
unsigned long timeout = RW_THR_NO_TIMEOUT )
static

Makes a thread pool instance that contains a number of threads from minThreads to maxThreads, each with the default thread attributes. The actual number of threads grows and shrinks between minThreads to maxThreads depending on work load. A thread awaits work for at least timeout milliseconds before exiting.

◆ operator=()

RWThreadPool & RWThreadPool::operator= ( const RWThreadPool & second)
inline

Binds this external interface handle to the thread pool object that is pointed to by a second handle (if any).

◆ resize()

bool RWThreadPool::resize ( size_t minThreads,
size_t maxThreads = RW_THR_NO_DYNAMIC_THREAD_POOL )

Resizes the thread pool so that it contains at least minThreads and at most maxThreads. This function fails if maxThreads is larger than the number of worker threads (i.e. the value returned by entries()). Otherwise, idle threads are created or destroyed as necessary. Returns true if the resize was successful, otherwise false.

◆ size()

size_t RWThreadPool::size ( ) const

Returns the size of the thread pool, that is, the number of threads currently in the pool.

◆ stop()

void RWThreadPool::stop ( )

Stops work execution after the thread pool executes all the work that is currently enqueued. No additional work is enqueued after stop() is called.

Friends And Related Symbol Documentation

◆ RW_THR_NO_DYNAMIC_THREAD_POOL

const size_t RW_THR_NO_DYNAMIC_THREAD_POOL
related

Constant to indicate that dynamic thread pools are not enabled.

◆ RW_THR_NO_TIMEOUT

const unsigned long RW_THR_NO_TIMEOUT
related

Constant to indicate no timeout value.

Copyright © 2024 Rogue Wave Software, Inc., a Perforce company. All Rights Reserved.