RWServerPool

Module:  Threads   Package:  Threading

RWServerPool   RWRunnableServer

• Local Index
• Header File
• Description
• Example
• Static Member Functions
• Public Constructors
• Public Destructor
• Public Member Operator
• Public Member Functions
• See Also

Members

getPoolAttribute() make()

operator=() resize()

RWServerPool() setPoolAttribute()

size() ~RWServerPool()

#include <rw/thread/RWServerPool.h>

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 that they would like to have executed. Each runnable object that the server finds in its internal queue is dequeued and is 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 insure 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 un-processed and eligible runnables will be 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 will continue 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 will stop and join with the runnable servers in the pool and then exit. 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.

#include <rw/thread/RWServerPool.h>
#include <rw/thread/RWRunnable.h>
#include <rw/thread/rwtMakeRunnableFunction.h>

RWServerPool serverPool(RWServerPool::make(4));
serverPool.start();
RWRunnable runnable = rwtMakeRunnableFunction(function);
serverPool.enqueue(runnable); 
// ...
serverPool.stop();
serverPool.join();

// See the servpool.cpp example program for details

static RWServerPool
make(size_t numThreads);

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

static RWServerPool
make(size_t numThreads,size_t maxCapacity);

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 will be created with default thread attributes.

static RWServerPool
make(const RWThreadAttribute& serverAttr, size_t numThreads);

Makes a server pool instance whose main thread will be created with the specified thread attributes, and whose pool will contain numThreads threads, each created with a default set of thread attributes.

static RWServerPool
make(const RWThreadAttribute& serverAttr,
     size_t numThreads, size_t maxCapacity);

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

static RWServerPool
make (size_t numThreads, const RWThreadAttribute& poolAttr);

Makes a server pool instance whose main thread will be created with default thread attributes, and whose pool will contain numThreads threads, each created with the specified set of thread attributes.

static RWServerPool
make (size_t numThreads, const RWThreadAttribute& poolAttr,
      size_t maxCapacity);

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

static RWServerPool
make(const RWThreadAttribute& serverAttr, size_t numThreads, 
     const RWThreadAttribute& poolAttr);

Makes a server pool instance whose main thread will be created with the thread attributes specified by the first thread attribute object, and whose pool will contain numThreads threads, each created with the thread attributes specified by the second thread attribute object.

static RWServerPool
make(const RWThreadAttribute& serverAttr, size_t numThreads,
     const RWThreadAttribute& poolAttr, size_t maxCapacity);

Makes a server pool instance whose main thread will be created with the thread attributes specified by the first thread attribute object, whose pool will contain numThreads threads, each created with the thread attributes specified by the second thread attribute object, and whose input queue has the specified maximum capacity.

RWServerPool();

Constructs an empty (invalid) handle.

RWServerPool(const RWServerPool& second);

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

~RWServerPool();

Destructor.

RWServerPool&
operator=(const RWServerPool& second);

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

RWThreadAttribute
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.

void
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 will be 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 will create a sufficient number of new threads and add them to the pool. May raise RWTHRInvalidPointer or RWTHRInternalError.

void
setPoolAttribute(const RWThreadAttribute& poolAttr);

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 only affect new threads started by the pool server in response to a request for a larger pool size; existing threads will continue with their original attributes. May raise RWTHRInvalidPointer or RWTHRInternalError.

size_t
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.

RWRunnable, RWThread, RWRunnableServer, RWThreadAttribute

© Copyright Rogue Wave Software, Inc. All Rights Reserved.
Rogue Wave and SourcePro are registered trademarks of Rogue Wave Software, Inc. in the United States and other countries. All other trademarks are the property of their respective owners.
Contact Rogue Wave about documentation or support issues.