RWRunnableServer Class Reference

Represents a runnable server for executing runnable objects. More...

#include <rw/thread/RWRunnableServer.h>

Inheritance diagram for RWRunnableServer:

Public Member Functions
	RWRunnableServer ()
	RWRunnableServer (const RWRunnableServer &second)
	~RWRunnableServer ()
void	checkGuards ()
void	enqueue (const RWRunnable &runnable)
void	enqueue (const RWRunnable &runnable, const RWRunnableGuard &guard)
RWWaitStatus	enqueue (const RWRunnable &runnable, const RWRunnableGuard &guard, unsigned long milliseconds)
RWWaitStatus	enqueue (const RWRunnable &runnable, unsigned long milliseconds)
void	enqueue (long priority, const RWRunnable &runnable)
void	enqueue (long priority, const RWRunnable &runnable, const RWRunnableGuard &guard)
RWWaitStatus	enqueue (long priority, const RWRunnable &runnable, const RWRunnableGuard &guard, unsigned long milliseconds)
RWWaitStatus	enqueue (long priority, const RWRunnable &runnable, unsigned long milliseconds)
size_t	getCapacity () const
RWRunnableServer &	operator= (const RWRunnableServer &second)
size_t	setCapacity (size_t maxCapacity)
void	stop ()
Public Member Functions inherited from RWThread
	RWThread ()
	RWThread (const RWThread &second)
	RWThread (RWStaticCtor)
	~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
RWThread &	operator= (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 (const RWRunnable &second)
	RWRunnable (RWStaticCtor)
	~RWRunnable ()
RWRunnable	getNestedRunnable () const
RWRunnableSelf	getRWRunnableSelf () const
RWWaitStatus	join (unsigned long milliseconds)
void	join (void)
RWRunnable &	operator= (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

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

Related Symbols
(Note that these are not member symbols.)
typedef RWTFunctor< bool()>	RWRunnableGuard

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 (const RWRunnableHandle &second)
	RWRunnableHandle (RWRunnableImp *runnableImpP)
	RWRunnableHandle (RWStaticCtor)
	~RWRunnableHandle ()
RWRunnableHandle &	operator= (const RWRunnableHandle &second)
Protected Member Functions inherited from RWHandleBase
	RWHandleBase (const RWHandleBase &second)
	RWHandleBase (RWBodyBase *body)
	RWHandleBase (RWStaticCtor)
	RWHandleBase (void)
	~RWHandleBase (void)
RWBodyBase &	body (void) const
RWHandleBase &	operator= (const RWHandleBase &second)

Detailed Description

The runnable server may be used alone, or within a class for an active object class implementation. The runnable server object, when started, waits for other threads to enqueue runnable objects for the server thread to execute. Each runnable object that the server finds in its internal queue is dequeued and started. The runnable server does not join with the runnables it starts. The runnable server continues to dequeue runnables and execute them until stopped, interrupted, or canceled.

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

The server uses the guard functor 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, so that unprocessed and eligible runnables are retrieved in priority order by the server.

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.

An active object implementation using this class defines a client interface with member functions that simply produce "runnable functor" objects (see RWRunnableFunction and RWTRunnableIOUFunction) which, when invoked, execute some corresponding private or local member function within the active object instance. The public members pass the runnable functors to the server thread by calling the enqueue() member, which stores the runnables in a queue. The client interface member function then returns to its caller.

Runnables that use IOUs can be used to represent a future return value or result of the asynchronous active object operation. In this situation, the client interface would create the appropriate IOU-capable runnable object, enqueue the runnable for execution, retrieve the runnable's IOU result, and return that IOU to the caller. The caller could then redeem that IOU at some point in the future.

Example

#include <rw/thread/RWRunnable.h>
#include <rw/thread/RWRunnableFunction.h>
#include <rw/thread/RWRunnableServer.h>
 
void function(void);
 
RWRunnableServer runnableServer(RWRunnableServer::make());
RWRunnable runnable = RWRunnableFunction::make(function);
 
runnableServer.start();
runnableServer.enqueue(runnable);
// ...
runnableServer.stop();
runnableServer.join();

The following is a skeleton of an active object class implemented using an RWRunnableServer. For a complete active object example, refer to activobj.cpp in the threxam directory.

class ActiveObject {
 public:
  // Starts runnable server.
  ActiveObject();
 
  // Stops runnable server.
  ~ActiveObject(void);
 
  // A function with no return. Creates and enqueues an
  // RWRunnableFunction, wrapping _func1();
  void func1(int arg1, int arg2, int arg3);
 
  // A function with a return value. Creates and enqueues
  // an RWTRunnableIOUFunction, wrapping _func2();
  RWTIOUResult<int> func2(int arg1, int arg2, int arg3);
 
 private:
  // func1()'s better half
  void _func1(int arg1, int arg2, int arg3);
 
  // func2()'s better half
  int _func2(int arg1, int arg2, int arg3);
 
  // Guard functions called by RWRunnableGuard objects
  bool guard1Func();
  bool guard2Func();
 
  // Runnable execution guards enqueued on
  // RWRunnableServer, along with RWRunnable objects.
  RWRunnableGuard guard1_;
  RWRunnableGuard guard2_;
 
  // The internal runnable server instance.
  RWRunnableServer runnableServer_;
};

See also

RWRunnable, RWThread, RWServerPool

Constructor & Destructor Documentation

RWRunnableServer() [1/2]

RWRunnableServer::RWRunnableServer ( )

inline

Constructs an empty, invalid, handle instance.

RWRunnableServer() [2/2]

RWRunnableServer::RWRunnableServer ( const RWRunnableServer & second )

inline

Constructs an external interface handle to the thread object pointed to by handle second, if any.

~RWRunnableServer()

RWRunnableServer::~RWRunnableServer ( )

inline

Destructor.

Member Function Documentation

checkGuards()

void RWRunnableServer::checkGuards

(

)

Notifies all readers that a guard state may have changed, and that all pending requests should be reevaluated.

enqueue() [1/8]

void RWRunnableServer::enqueue

(

const RWRunnable &

runnable

)

Passes a runnable instance to the server for execution. All runnables are inserted into an internal producer-consumer queue, where the server retrieves them, one at a time, in priority order, and executes them to completion.

If the server is running and its input queue has sufficient capacity to hold another runnable, this function inserts the runnable and returns. If the server is running but its input queue is full, this function blocks the calling thread until the input queue is no longer full (because the server has removed a sufficient number of runnables, or another thread has changed the maximum capacity of the input queue) or until the server is stopped.

If the server is stopped while the calling thread is blocked and waiting within this function for space in the input queue, the calling thread is unblocked and the function returns by throwing an RWTHRClosedException. If the server is already closed when this function is called, the function immediately returns by throwing an RWTHRClosedException.

This function takes the parameter runnable, which is a const reference to an RWRunnable instance of the type used to instantiate this template class.

Runnables enqueued with this method are not guarded and are assigned a priority value of zero.

enqueue() [2/8]

void RWRunnableServer::enqueue	(	const RWRunnable &	runnable,
		const RWRunnableGuard &	guard )

Passes a guarded runnable instance runnable to the server for execution. All runnable are inserted into an internal producer-consumer queue, where the server retrieves them, one at a time, in priority order, and executes them to completion.

If the server is running and its input queue has sufficient capacity to hold another runnable, this function inserts the runnable and returns. If the server is running but its input queue is full, this function blocks the calling thread until the input queue is no longer full (because the server has removed a sufficient number of runnables, or another thread has changed the maximum capacity of the input queue) or until the server is stopped.

If the server is stopped while the calling thread is blocked and waiting within this function for space in the input queue, the calling thread is unblocked and the function returns by throwing an RWTHRClosedException. If the server is already closed when this function is called, the function immediately returns by throwing an RWTHRClosedException.

Parameters:

• The parameter runnable is a const reference to an RWRunnable instance.
• The parameter guard is a reference to an RWTFunctor<bool()> functor instance that is invoked by the server thread to determine whether the associated runnable is currently eligible for retrieval from the input queue and execution. The server retrieves and executes a runnable if its guard functor evaluates to true, and skips any runnable whose guard functor evaluates to false, until a runnable is found that can be executed. An empty functor handle indicates that the entry is always eligible for execution. The functor must not attempt to enqueue other runnables on the same server instance, as such access results in deadlock.

Runnables enqueued with this method are assigned a priority value of zero.

enqueue() [3/8]

RWWaitStatus RWRunnableServer::enqueue	(	const RWRunnable &	runnable,
		const RWRunnableGuard &	guard,
		unsigned long	milliseconds )

Passes a guarded runnable instance runnable to the server for execution. All runnables are inserted into an internal producer-consumer queue, where the server retrieves them, one at a time, in priority order, and executes them to completion.

If the server is running and its input queue has sufficient capacity to hold another runnable, this function inserts the runnable and returns RW_THR_COMPLETED. If the server is running but its input queue is full, this function blocks the calling thread until the input queue is no longer full (because the server has removed a sufficient number of runnables, or another thread has changed the maximum capacity of the input queue), or until the server is stopped, or until the specified amount of time passes. If the runnable cannot be inserted in the input queue within the specified amount of time, this function returns a value of RW_THR_TIMEOUT.

If the server is stopped while the calling thread is blocked and waiting within this function for space in the input queue, the calling thread is unblocked and the function returns by throwing an RWTHRClosedException. If the server is already closed when this function is called, the function immediately returns by throwing an RWTHRClosedException.

Parameters:

• The parameter runnable is a const reference to an RWRunnable instance.
• The parameter guard is a reference to an RWTFunctor<bool()> functor instance that is invoked by the server thread to determine whether the associated runnable is currently eligible for retrieval from the input queue and execution. The server retrieves and executes a runnable if its guard functor evaluates to true, and skips any runnable whose guard functor evaluates to false, until a runnable is found that can be executed. An empty functor handle indicates that the entry is always eligible for execution. The functor must not attempt to enqueue other runnables on the same server instance, as such access results in deadlock.
• The parameter milliseconds is an unsigned long value that specifies the maximum number of milliseconds to wait for the operation to complete.

Runnables enqueued with this method are assigned a priority value of zero.

enqueue() [4/8]

RWWaitStatus RWRunnableServer::enqueue	(	const RWRunnable &	runnable,
		unsigned long	milliseconds )

Passes a runnable instance to the server for execution. All runnables are inserted into an internal producer-consumer queue, where the server retrieves them, one at a time, in priority order, and executes them to completion.

If the server is running and its input queue has sufficient capacity to hold another runnable, this function inserts the runnable and returns RW_THR_COMPLETED. If the server is running but its input queue is full, this function blocks the calling thread until the input queue is no longer full (because the server has removed a sufficient number of runnables, or another thread has changed the maximum capacity of the input queue), or until the server is stopped, or until the specified amount of time passes. If the runnable cannot be inserted in the input queue within the specified amount of time provided in milliseconds, this function returns a value of RW_THR_TIMEOUT.

If the server is stopped while the calling thread is blocked and waiting within this function for space in the input queue, the calling thread is unblocked and the function returns by throwing an RWTHRClosedException. If the server is already closed when this function is called, the function immediately returns by throwing an RWTHRClosedException.

Parameters:

• The parameter runnable is a const reference to an RWRunnable instance.
• The parameter milliseconds is an unsigned long value that specifies the maximum number of milliseconds to wait for the operation to complete.

Runnables enqueued with this method are not guarded and are assigned a priority value of zero.

enqueue() [5/8]

void RWRunnableServer::enqueue	(	long	priority,
		const RWRunnable &	runnable )

Passes a prioritized runnable instance to the server for execution. All runnables are inserted into an internal producer-consumer queue, where the server retrieves them, one at a time, in priority order, and executes them to completion.

If the server is running and its input queue has sufficient capacity to hold another runnable, this function inserts the runnable and returns. If the server is running but its input queue is full, this function blocks the calling thread until the input queue is no longer full (because the server has removed a sufficient number of runnables, or another thread has changed the maximum capacity of the input queue) or until the server is stopped.

If the server is stopped while the calling thread is blocked and waiting within this function for space in the input queue, the calling thread is unblocked and the function returns by throwing an RWTHRClosedException. If the server is already closed when this function is called, the function immediately returns by throwing an RWTHRClosedException.

Parameters:

• The parameter priority is a long that is used to determine the insertion point of the runnable within the server's input queue. A runnable with a greater priority value is positioned to be read before a runnable of lower priority. Runnables of equal priority are positioned such that older runnables are executed before newer runnables.
• The parameter runnable is a const reference to an RWRunnable instance.

Runnables enqueued with this method are not guarded.

enqueue() [6/8]

void RWRunnableServer::enqueue	(	long	priority,
		const RWRunnable &	runnable,
		const RWRunnableGuard &	guard )

Passes a guarded and prioritized runnable instance to the server for execution. All runnables are inserted into an internal producer-consumer queue, where the server retrieves them, one at a time, and executes them to completion.

If the server is running and its input queue has sufficient capacity to hold another runnable, this function inserts the runnable and returns. If the server is running but its input queue is full, this function blocks the calling thread until the input queue is no longer full (because the server has removed a sufficient number of runnables, or another thread has changed the maximum capacity of the input queue) or until the server is stopped.

If the server is stopped while the calling thread is blocked and waiting within this function for space in the input queue, the calling thread is unblocked and the function returns by throwing an RWTHRClosedException. If the server is already closed when this function is called, the function immediately returns by throwing an RWTHRClosedException.

Parameters:

• The parameter priority is a long that is used to determine the insertion point of the runnable within the server's input queue. A runnable with a greater priority value is positioned to be read before a runnable of lower priority. Runnables of equal priority are positioned such that older runnables are executed before newer runnables.
• The parameter runnable is a const reference to an RWRunnable instance.
• The parameter guard is a reference to an RWTFunctor<bool()> functor instance that is invoked by the server thread to determine whether the associated runnable is currently eligible for retrieval from the input queue and execution. The server retrieves and executes a runnable if its guard functor evaluates to true, and skips any runnable whose guard functor evaluates to false, until a runnable is found that can be executed. An empty functor handle indicates that the entry is always eligible for execution. The functor must not attempt to enqueue other runnables on the same server instance, as such access results in deadlock.

enqueue() [7/8]

RWWaitStatus RWRunnableServer::enqueue	(	long	priority,
		const RWRunnable &	runnable,
		const RWRunnableGuard &	guard,
		unsigned long	milliseconds )

Passes a guarded and prioritized runnable instance to the server for execution. All runnables are inserted into an internal producer-consumer queue, where the server retrieves them, one at a time, and executes them to completion.

If the server is running and its input queue has sufficient capacity to hold another runnable, this function inserts the runnable and returns RW_THR_COMPLETED. If the server is running but its input queue is full, this function blocks the calling thread until the input queue is no longer full (because the server has removed a sufficient number of runnables, or another thread has changed the maximum capacity of the input queue), or until the server is stopped, or until the specified amount of time passes. If the runnable cannot inserted in the input queue within the specified amount of time, this function returns a value of RW_THR_TIMEOUT.

If the server is stopped while the calling thread is blocked and waiting within this function for space in the input queue, the calling thread is unblocked and the function returns by throwing an RWTHRClosedException. If the server is already closed when this function is called, the function immediately returns by throwing an RWTHRClosedException.

Parameters:

• The parameter priority is a long that is used to determine the insertion point of the runnable within the server's input queue. A runnable with a greater priority value is positioned to be read before a runnable of lower priority. Runnables of equal priority are positioned such that older runnables are executed before newer runnables.
• The parameter runnable is a const reference to an RWRunnable instance.
• The parameter guard is a reference to an RWTFunctor<bool()> functor instance that is invoked by the server thread to determine whether the associated runnable is currently eligible for retrieval from the input queue and execution. The server retrieves and executes a runnable if whose guard functor evaluates to true, and skips any runnable whose guard functor evaluates to false, until a runnable is found that can be executed. An empty functor handle indicates that the entry is always eligible for execution. The functor must not attempt to enqueue other runnables on the same server instance, as such access results in deadlock.
• The parameter milliseconds is an unsigned long value that specifies the maximum number of milliseconds to wait for the operation to complete.

enqueue() [8/8]

RWWaitStatus RWRunnableServer::enqueue	(	long	priority,
		const RWRunnable &	runnable,
		unsigned long	milliseconds )

Passes a prioritized runnable instance to the server for execution. All runnables are inserted into an internal producer-consumer queue, where the server retrieves them, one at a time, and executes them to completion.

If the server is running and its input queue has sufficient capacity to hold another runnable, this function inserts the runnable and returns RW_THR_COMPLETED. If the server is running but its input queue is full, this function blocks the calling thread until the input queue is no longer full (because the server has removed a sufficient number of runnables, or another thread has changed the maximum capacity of the input queue), or until the server is stopped, or until the specified amount of time passes. If the runnable cannot inserted in the input queue within the specified amount of time, this function returns a value of RW_THR_TIMEOUT.

If the server is stopped while the calling thread is blocked and waiting within this function for space in the input queue, the calling thread is unblocked and the function returns by throwing an RWTHRClosedException. If the server is already closed when this function is called, the function immediately returns by throwing an RWTHRClosedException.

Parameters:

• The parameter priority is a long that is used to determine the insertion point of the runnable within the server's input queue. A runnable with a greater priority value is positioned to be read before a runnable of lower priority. Runnables of equal priority are positioned such that older runnables are executed before newer runnables.
• The parameter runnable is a const reference to an RWRunnable instance.
• The parameter milliseconds is an unsigned long value that specifies the maximum number of milliseconds to wait for the operation to complete.

Runnables enqueued with this method are not guarded.

getCapacity()

size_t RWRunnableServer::getCapacity

(

)

const

Returns the maximum capacity of the server's input queue. A value of zero indicates that the queue has no capacity limit.

make() [1/4]

static RWRunnableServer RWRunnableServer::make ( )

static

Makes a runnable server.

make() [2/4]

static RWRunnableServer RWRunnableServer::make ( const RWThreadAttribute & serverThreadAttr )

static

Makes a runnable server instance with the specified thread attributes.

make() [3/4]

static RWRunnableServer RWRunnableServer::make ( const RWThreadAttribute & serverThreadAttr, size_t maxCapacity )

static

Makes a runnable server instance with the specified thread attributes whose input queue has the specified maximum capacity.

make() [4/4]

static RWRunnableServer RWRunnableServer::make ( size_t maxCapacity )

static

Makes a runnable server whose input queue has the specified maximum capacity.

operator=()

RWRunnableServer & RWRunnableServer::operator= ( const RWRunnableServer & second )

inline

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

setCapacity()

size_t RWRunnableServer::setCapacity

(

size_t

maxCapacity

)

Sets the maximum capacity of the server's input queue. The maximum capacity of the input queue determines the maximum number of unprocessed entries allowed to accumulate within the input queue. Once the number of entries equals or exceeds this number, any thread attempting to enqueue another runnable is blocked until the server removes a sufficient number of runnables from the queue, or until another thread increases the capacity. A value of zero indicates that the queue has no capacity limit. This function returns the maximum capacity value that was in use before the call.

stop()

void RWRunnableServer::stop

(

)

Requests that the server stop execution after it executes the runnables that are currently enqueued. Any attempt to enqueue a runnable after the server has been stopped, or before it has been started, results in an RWTHRClosedException.

Friends And Related Symbol Documentation

RWRunnableGuard

typedef RWTFunctor<bool()> RWRunnableGuard

related

A typedef for a function object used to guard the execution of an RWRunnable within RWRunnableServer.