SourcePro® API Reference Guide

 
List of all members | Public Member Functions | Static Public Member Functions
RWServerPool Class Reference

Manages a pool of RWRunnableServer instances used to start runnable objects submitted for execution by other threads. More...

#include <rw/thread/RWServerPool.h>

Inheritance diagram for RWServerPool:
RWRunnableServer RWThread RWRunnable RWRunnableHandle RWHandleBase

Public Member Functions

 RWServerPool ()
 
 RWServerPool (const RWServerPool &second)
 
 ~RWServerPool ()
 
RWThreadAttribute getPoolAttribute ()
 
RWServerPooloperator= (const RWServerPool &second)
 
void resize (size_t size)
 
void setPoolAttribute (const RWThreadAttribute &poolThreadsAttr)
 
size_t size () const
 
- Public Member Functions inherited from RWRunnableServer
 RWRunnableServer ()
 
 RWRunnableServer (const RWRunnableServer &second)
 
 ~RWRunnableServer ()
 
void checkGuards ()
 
void enqueue (const RWRunnable &runnable)
 
RWWaitStatus enqueue (const RWRunnable &runnable, unsigned long milliseconds)
 
void enqueue (const RWRunnable &runnable, const RWRunnableGuard &guard)
 
RWWaitStatus enqueue (const RWRunnable &runnable, const RWRunnableGuard &guard, unsigned long milliseconds)
 
void enqueue (long priority, const RWRunnable &runnable)
 
RWWaitStatus enqueue (long priority, const RWRunnable &runnable, unsigned long milliseconds)
 
void enqueue (long priority, const RWRunnable &runnable, const RWRunnableGuard &guard)
 
RWWaitStatus enqueue (long priority, const RWRunnable &runnable, const RWRunnableGuard &guard, unsigned long milliseconds)
 
size_t getCapacity () const
 
RWRunnableServeroperator= (const RWRunnableServer &second)
 
size_t setCapacity (size_t maxCapacity)
 
void stop ()
 
- Public Member Functions inherited from RWThread
 RWThread ()
 
 RWThread (RWStaticCtor)
 
 RWThread (const RWThread &second)
 
 ~RWThread ()
 
bool canGetPriority () const
 
bool canGetProcessScopePriority () const
 
bool canGetSchedulingPolicy () const
 
bool canGetSystemScopePriority () const
 
bool canGetTimeSliceQuantum () const
 
bool canSetPriority () const
 
bool canSetProcessScopePriority () const
 
bool canSetSchedulingPolicy (RWSchedulingPolicy policy) const
 
bool canSetSystemScopePriority () const
 
bool canSetTimeSliceQuantum () const
 
RWThreadAttribute getActiveAttribute () const
 
RWThreadAttribute getAttribute () const
 
RWPriority getMaxPriority () const
 
RWPriority getMaxProcessScopePriority () const
 
RWPriority getMaxSystemScopePriority () const
 
unsigned long getMaxTimeSliceQuantum () const
 
RWPriority getMinPriority () const
 
RWPriority getMinProcessScopePriority () const
 
RWPriority getMinSystemScopePriority () const
 
unsigned long getMinTimeSliceQuantum () const
 
RWPriority getPriority () const
 
RWPriority getProcessScopePriority () const
 
RWThreadSelf getRWThreadSelf () const
 
RWSchedulingPolicy getSchedulingPolicy () const
 
unsigned getSuspendCount () const
 
RWPriority getSystemScopePriority () const
 
unsigned long getTimeSliceQuantum () const
 
RWThreadoperator= (const RWThread &second)
 
unsigned resume ()
 
void setAttribute (const RWThreadAttribute &second)
 
void setPriority (RWPriority priority)
 
void setProcessScopePriority (RWPriority priority)
 
void setSchedulingPolicy (RWSchedulingPolicy policy)
 
void setSystemScopePriority (RWPriority priority)
 
void setTimeSliceQuantum (unsigned long milliseconds)
 
unsigned suspend ()
 
void terminate ()
 
- Public Member Functions inherited from RWRunnable
 RWRunnable ()
 
 RWRunnable (RWStaticCtor)
 
 RWRunnable (const RWRunnable &second)
 
 ~RWRunnable ()
 
RWRunnable getNestedRunnable () const
 
RWRunnableSelf getRWRunnableSelf () const
 
void join (void)
 
RWWaitStatus join (unsigned long milliseconds)
 
RWRunnableoperator= (const RWRunnable &second)
 
void raise () const
 
void releaseInterrupt ()
 
RWWaitStatus requestCancellation ()
 
RWWaitStatus requestCancellation (unsigned long milliseconds)
 
RWWaitStatus requestInterrupt ()
 
RWWaitStatus requestInterrupt (unsigned long milliseconds)
 
RWCompletionState start ()
 
RWExecutionState wait (unsigned long stateMask)
 
RWWaitStatus wait (unsigned long stateMask, RWExecutionState *state, unsigned long milliseconds)
 
- Public Member Functions inherited from RWRunnableHandle
void addCallback (const RWTFunctor< void(const RWRunnable &, RWExecutionState)> &functor, unsigned long stateMask, RWCallbackScope scope=RW_CALL_REPEATEDLY)
 
RWCompletionState getCompletionState () const
 
RWExecutionState getExecutionState () const
 
bool isInterruptRequested () const
 
bool isSelf () const
 
bool isSelf (const RWThreadId &id) const
 
void removeCallback (const RWTFunctor< void(const RWRunnable &, RWExecutionState)> &functor)
 
RWThreadId threadId () const
 
- Public Member Functions inherited from RWHandleBase
bool isValid (void) const
 
bool operator!= (const RWHandleBase &second) const
 
bool operator< (const RWHandleBase &second) const
 
bool operator== (const RWHandleBase &second) const
 

Static Public Member Functions

static RWServerPool make (size_t numThreads)
 
static RWServerPool make (size_t numThreads, size_t maxCapacity)
 
static RWServerPool make (const RWThreadAttribute &serverThreadAttr, size_t numThreads)
 
static RWServerPool make (const RWThreadAttribute &serverThreadAttr, size_t numThreads, size_t maxCapacity)
 
static RWServerPool make (size_t numThreads, const RWThreadAttribute &poolThreadsAttr)
 
static RWServerPool make (size_t numThreads, const RWThreadAttribute &poolThreadAttr, size_t maxCapacity)
 
static RWServerPool make (const RWThreadAttribute &serverThreadAttr, size_t numThreads, const RWThreadAttribute &poolThreadsAttr)
 
static RWServerPool make (const RWThreadAttribute &serverThreadAttr, size_t numThreads, const RWThreadAttribute &poolThreadsAttr, size_t maxCapacity)
 
- Static Public Member Functions inherited from RWRunnableServer
static RWRunnableServer make ()
 
static RWRunnableServer make (const RWThreadAttribute &serverThreadAttr)
 
static RWRunnableServer make (size_t maxCapacity)
 
static RWRunnableServer make (const RWThreadAttribute &serverThreadAttr, size_t maxCapacity)
 
- Static Public Member Functions inherited from RWThread
static bool canGetMaxThreads ()
 
static bool canSuspendResume ()
 
static size_t getMaxThreads ()
 

Additional Inherited Members

- Protected Member Functions inherited from RWThread
 RWThread (RWThreadImp *threadImpP)
 
- Protected Member Functions inherited from RWRunnable
 RWRunnable (const RWRunnableSelf &second)
 
- Protected Member Functions inherited from RWRunnableHandle
 RWRunnableHandle ()
 
 RWRunnableHandle (RWStaticCtor)
 
 RWRunnableHandle (RWRunnableImp *runnableImpP)
 
 RWRunnableHandle (const RWRunnableHandle &second)
 
 ~RWRunnableHandle ()
 
RWRunnableHandleoperator= (const RWRunnableHandle &second)
 
- Protected Member Functions inherited from RWHandleBase
 RWHandleBase (void)
 
 RWHandleBase (RWStaticCtor)
 
 RWHandleBase (RWBodyBase *body)
 
 RWHandleBase (const RWHandleBase &second)
 
 ~RWHandleBase (void)
 
RWBodyBasebody (void) const
 
RWHandleBaseoperator= (const RWHandleBase &second)
 

Detailed Description

The RWServerPool object is an RWRunnableServer that manages a "pool" of other RWRunnableServer instances that are used to start runnable objects submitted for execution by other threads. A server pool object, when started, waits for other threads to enqueue runnable objects for execution. Each runnable object that the server finds in its internal queue is dequeued and passed to the next available runnable server from the pool. This process continues until the server pool object is interrupted, canceled, or stopped.

Runnables may be enqueued with a guard functor, or a priority value, or both.

The guard functor is used by the server to determine whether the associated runnable is currently eligible for retrieval and execution. A guarded runnable is not retrieved by the server until that runnable is the first runnable in the queue whose guard evaluates to true. Using guards to block runnable execution is important when implementing active objects; guards can be used to ensure that the active object maintains consistent state and preserves any necessary invariants.

The priority value is used during write operations to determine a runnable's insertion point within the server's input queue, such that the set of unprocessed and eligible runnables are retrieved in priority order by the server.

The number of runnable servers to create for the internal pool may be specified when the server pool instance is created. A server pool instance does not create the RWRunnableServer instances for the pool, and does not process any enqueued runnables until the start() member is called. No runnables may be enqueued until the server pool is started.

The size of the runnable server pool may be adjusted after construction using the resize() member.

The stop() member is used to initiate server pool shutdown. The server pool continues to dispatch any runnables already enqueued when stop() is called, but no additional runnables may be enqueued after that point. Once the pending runnables have been dispatched, the server pool thread stops and joins with the runnable servers in the pool and then exits. The stop function does not wait for the server to stop; to wait for the server pool thread to complete its shutdown exit, use the join() function.

The RWRunnable::requestCancellation() function should be used if the server thread is to stop execution as soon as possible without dequeuing and dispatching any additional runnables.

The RWRunnable::requestInterrupt() function can be used to temporarily suspend execution of the server thread.

Example
#include <rw/thread/RWServerPool.h>
#include <rw/thread/RWRunnable.h>
serverPool.start();
RWRunnable runnable = RWRunnableFunction::make(function);
serverPool.enqueue(runnable);
// ...
serverPool.stop();
serverPool.join();
// See the servpool.cpp example program for details
See also
RWRunnable, RWThread, RWRunnableServer, RWThreadAttribute

Constructor & Destructor Documentation

RWServerPool::RWServerPool ( )
inline

Constructs an empty (invalid) handle.

RWServerPool::RWServerPool ( const RWServerPool second)
inline

Constructs an external interface handle to the server pool object pointed to by a second handle second (if any).

RWServerPool::~RWServerPool ( )
inline

Destructor.

Member Function Documentation

RWThreadAttribute RWServerPool::getPoolAttribute ( )

Gets a handle to the thread attribute instance specified during server pool construction or the instance specified in the last call to setPoolAttribute(). May raise RWTHRInvalidPointer or RWTHRInternalError.

static RWServerPool RWServerPool::make ( size_t  numThreads)
static

Makes a runnable server pool instance with the specified number of pool threads. The server pool's main thread and its pool threads are created with default thread attributes.

static RWServerPool RWServerPool::make ( size_t  numThreads,
size_t  maxCapacity 
)
static

Makes a runnable server pool instance with the specified number of pool threads and whose input queue has the specified maximum capacity. The server pool's main thread and its pool threads are created with default thread attributes.

static RWServerPool RWServerPool::make ( const RWThreadAttribute serverThreadAttr,
size_t  numThreads 
)
static

Makes a server pool instance whose main thread has the specified thread attributes, and whose pool contains numThreads threads, each with a default set of thread attributes.

static RWServerPool RWServerPool::make ( const RWThreadAttribute serverThreadAttr,
size_t  numThreads,
size_t  maxCapacity 
)
static

Makes a server pool instance whose main thread has the specified thread attributes; whose pool contains numThreads threads, each with a default set of thread attributes; and whose input queue has the specified maximum capacity.

static RWServerPool RWServerPool::make ( size_t  numThreads,
const RWThreadAttribute poolThreadsAttr 
)
static

Makes a server pool instance whose main thread has the default thread attributes, and whose pool contains numThreads threads, each with the specified set of thread attributes.

static RWServerPool RWServerPool::make ( size_t  numThreads,
const RWThreadAttribute poolThreadAttr,
size_t  maxCapacity 
)
static

Makes a server pool instance whose main thread has the default thread attributes; whose pool contains numThreads threads, each created with the specified set of thread attributes; and whose input queue has the specified maximum capacity.

static RWServerPool RWServerPool::make ( const RWThreadAttribute serverThreadAttr,
size_t  numThreads,
const RWThreadAttribute poolThreadsAttr 
)
static

Makes a server pool instance whose main thread has the thread attributes specified by the thread attribute object serverThreadAttr, and whose pool contains numThreads threads, each created with the thread attributes specified by the thread attribute object poolThreadsAttr.

static RWServerPool RWServerPool::make ( const RWThreadAttribute serverThreadAttr,
size_t  numThreads,
const RWThreadAttribute poolThreadsAttr,
size_t  maxCapacity 
)
static

Makes a server pool instance whose main thread has the thread attributes specified by the thread attribute object serverThreadAttr; whose pool contains numThreads threads, each created with the thread attributes specified by the thread attribute object poolThreadsAttr; and whose input queue has the specified maximum capacity.

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

Binds this external interface handle to the server pool object, if any, pointed to by a second handle second.

void RWServerPool::resize ( size_t  size)

Changes the number of threads within the thread pool. If the new thread pool size is less than the current size, then a sufficient number of threads are destroyed, but only after they have completed execution of any assigned runnable object. If the size is greater than the current size, the pool server thread creates a sufficient number of new threads and adds them to the pool. May raise RWTHRInvalidPointer or RWTHRInternalError.

void RWServerPool::setPoolAttribute ( const RWThreadAttribute poolThreadsAttr)

Changes the thread attribute instance used to initialize new runnable server objects as they are created for the thread pool. Changing the pool thread attributes after the server has started will affect only new threads started by the pool server in response to a request for a larger pool size; existing threads continue with their original attributes. May raise RWTHRInvalidPointer or RWTHRInternalError.

size_t RWServerPool::size ( ) const

Returns the target size for the thread pool. May be less than or greater than the actual number of runnable server instances in the pool, since the pool server thread may not yet have completed a previously requested expansion or contraction of the thread pool. May raise RWTHRInvalidPointer or RWTHRInternalError.

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