SourcePro® API Reference Guide

 
Loading...
Searching...
No Matches
RWRunnableTrap Class Reference

Waits for a number of runnables or threads to reach a certain execution state. More...

#include <rw/thread/RWRunnableTrap.h>

Inheritance diagram for RWRunnableTrap:
RWHandleBase

Public Member Functions

 RWRunnableTrap ()
 
 RWRunnableTrap (const RWRunnableTrap &second)
 
 RWRunnableTrap (RWStaticCtor)
 
 ~RWRunnableTrap ()
 
RWRunnable getNext ()
 
void getNext (RWRunnable &r, RWExecutionState &es)
 
RWWaitStatus getNext (RWRunnable &r, RWExecutionState &es, unsigned long milliseconds)
 
RWWaitStatus getNext (RWRunnable &r, unsigned long milliseconds)
 
bool isEmpty (void) const
 
RWRunnableTrapoperator= (const RWRunnableTrap &second)
 
void setTrap (RWRunnable runnable, RWCallbackScope scope=RW_CALL_ONCE)
 
bool tryGetNext (RWRunnable &runnable)
 
bool tryGetNext (RWRunnable &runnable, RWExecutionState &es)
 
- 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 RWRunnableTrap make (unsigned long executionStateMask=RW_THR_INITIAL)
 

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

RWRunnableTrap allows you to wait for a number of runnables or threads to reach a certain execution state. When you create an RWRunnableTrap you specify the target execution state. This causes any runnable that the trap has been set on to catch the runnable when it reaches the given execution state.

Another thread can get each runnable as it reaches the target execution state by calling the getNext() function of the runnable trap. A runnable may be caught by the trap by calling setTrap() and passing in the target runnable. By default the runnable is caught only once, the first time that it enters the execution state. When you set the trap on a runnable you may specify that the runnable be caught repeatedly, each time that it enters the execution state.

A common usage of an RWRunnableTrap is to wait for a number of threads to complete execution. This allows you to launch and wait for multiple threads without having to keep track of those threads in an array or other data structure. After a thread is created, but before it is started, it can be added to a runnable trap.

The default target execution state is RW_THR_INITIAL which is the state that a runnable reaches when it completes execution.

Example
#include <rw/thread/RWRunnable.h>
#include <rw/thread/RWRunnableTrap.h>
#include <rw/thread/RWThreadFunction.h>
void function(void);
int main() {
int i;
for (i = 0; i < 10; i++) {
RWThread thread = RWThreadFunction::make(function);
rnblTrap.setTrap(thread); // before starting thread!
thread.start();
}
for (i = 0; i < 10; i++) {
RWRunnable rnbl = rnblTrap.getNext();
rnbl.join();
}
return 0;
}
Waits for a number of runnables or threads to reach a certain execution state.
Definition RWRunnableTrap.h:98
static RWRunnableTrap make(unsigned long executionStateMask=RW_THR_INITIAL)
void setTrap(RWRunnable runnable, RWCallbackScope scope=RW_CALL_ONCE)
RWRunnable getNext()
Handle class for a runnable object, i.e. one that controls an application's threads of execution.
Definition RWRunnable.h:106
RWCompletionState start()
void join(void)
static RWThreadFunction make()
Handle class for a threaded runnable object.
Definition RWThread.h:77
See also
RWRunnable

Constructor & Destructor Documentation

◆ RWRunnableTrap() [1/3]

RWRunnableTrap::RWRunnableTrap ( void )
inline

Constructs an invalid RWRunnableTrap. If the runnable trap is used without having being initialized, an invalid pointer exception is thrown.

◆ RWRunnableTrap() [2/3]

RWRunnableTrap::RWRunnableTrap ( RWStaticCtor )
inline

Constructs a static RWRunnableTrap.

◆ RWRunnableTrap() [3/3]

RWRunnableTrap::RWRunnableTrap ( const RWRunnableTrap & second)
inline

Copy constructor.

◆ ~RWRunnableTrap()

RWRunnableTrap::~RWRunnableTrap ( void )
inline

Default destructor.

Member Function Documentation

◆ getNext() [1/4]

RWRunnable RWRunnableTrap::getNext ( )

Gets the next RWRunnable that has entered RWExecutionState. Blocks if no RWRunnable is trapped.

◆ getNext() [2/4]

void RWRunnableTrap::getNext ( RWRunnable & r,
RWExecutionState & es )

Gets the next trapped RWRunnable and the execution state that caused it to be trapped.

◆ getNext() [3/4]

RWWaitStatus RWRunnableTrap::getNext ( RWRunnable & r,
RWExecutionState & es,
unsigned long milliseconds )

Gets the next trapped RWRunnable and the execution state that caused it to be trapped. Times out after given milliseconds if no RWRunnable is trapped. Returns either RW_THR_TIMEOUT or RW_THR_COMPLETED.

◆ getNext() [4/4]

RWWaitStatus RWRunnableTrap::getNext ( RWRunnable & r,
unsigned long milliseconds )

Gets the next RWRunnable that has entered RWExecutionState. Times out after given milliseconds if no RWRunnable is trapped. Returns either RW_THR_TIMEOUT or RW_THR_COMPLETED.

◆ isEmpty()

bool RWRunnableTrap::isEmpty ( void ) const

Returns true if the queue is empty, otherwise false.

◆ make()

static RWRunnableTrap RWRunnableTrap::make ( unsigned long executionStateMask = RW_THR_INITIAL)
static

Constructs a runnable trap to catch runnables as they reach the given execution state(s). The default is to wait until a runnable finishes execution and returns to its initial state. (See RWExecutionState.)

◆ operator=()

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

Assignment operator.

◆ setTrap()

void RWRunnableTrap::setTrap ( RWRunnable runnable,
RWCallbackScope scope = RW_CALL_ONCE )

Traps the given runnable when it enters RWExecutionState (specified when the runnable trap was created.) An RWCallbackScope may be specified as either RW_CALL_ONCE or RW_CALL_REPEATEDLY. This determines whether the runnable should enter the trap only once when it enters the target execution state, or repeatedly, each time it enters that state.

◆ tryGetNext() [1/2]

bool RWRunnableTrap::tryGetNext ( RWRunnable & runnable)

Gets the next runnable to reach the target execution state, if one is available. Returns true and sets the runnable parameter if one could be read, otherwise returns false.

◆ tryGetNext() [2/2]

bool RWRunnableTrap::tryGetNext ( RWRunnable & runnable,
RWExecutionState & es )

Gets the next runnable to reach the target execution state, if one is available. Returns true and sets the runnable parameter if one could be read, otherwise returns false. Sets es to the execution state that tripped the trap.

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