RWTIOUTrap<Redeemable>

Threads Module Reference Guide
Rogue Wave web site: Home Page | Main Documentation Page

RWTIOUTrap<Redeemable>

Module: Threads Package: Interthread Communication


RWTIOUTrap<Redeemable>   RWHandleBase

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

Local Index

Members

getNext()
isEmpty()

operator=()
RWTIOUTrap()

setTrap()
tryGetNext()

~RWTIOUTrap()

Header File

#include <rw/itc/RWTIOUTrap.h>

Description

RWTIOUTrap<Redeemable> allows you to wait for next IOU in a group of IOUs to become redeemable. For example, it can be used to wait on IOU results from a number of RWThreadIOUFunction instances. You may either block waiting for the next IOU to become available, wait with a time-out, or poll for the next IOU.

RWTIOUTrap<Redeemable> assists in the management of a number of RWTIOUResult instances. Without an IOU trap, you would have to poll each of a number of IOUs in turn, testing to see when the next one becomes redeemable. This kind of polling loop, however, is inefficient in a multithreaded environment. With an IOU trap, you merely wait for the trap to provide you with the next redeemable IOU.

Each IOU you wish to trap must first be registered using the setTrap() member function. Once an IOU is registered, it will automatically notify the trap when it becomes redeemable. RWTIOUTrap<Redeemable> uses a producer-consumer queue to store each IOU as they notify the trap that they are redeemable. An RWTIOUResult<Redeemable> is inserted into the queue by the thread that closed it, and taken off the queue when the trap's getNext() member is called.

The IOU trap is an implemented handle-body object. The RWTIOUTrap<Redeemable> is the handle for an IOU trap object. These handles allow a trap to be passed and shared by value. The actual trap object is deleted when the last handle that references it is destroyed.

Example

#include <rw/itc/RWTIOUTrap.h>

RWTIOUTrap<long> iouTrap;

RWTIOUResult<long> result1 = ...;
RWTIOUResult<long> result2 = ...;
RWTIOUResult<long> result3 = ...;

iouTrap.setTrap(result1);
iouTrap.setTrap(result2);
iouTrap.setTrap(result3);

for (int i; i < 3; i++) {
   long l = iouTrap.getNext();
   cout << "next result = " << l << endl;
}

Public Constructors

RWTIOUTrap();

Constructs an RWTIOUTrap<Redeemable> instance bound to a new RWTIOUTrapImp<Redeemable> instance.

RWTIOUTrap(RWStaticCtor);

Constructs a static RWTIOUTrap<Redeemable> handle instance. This constructor does not construct an RWTIOUTrapImp<Redeemable> instance, and does not change the handle instance.

RWTIOUTrap(const RWTIOUTrap<Redeemable>& second);

Copy constructor. Constructs a new handle instance and attaches it to the trap instance, if any, pointed to by second, and increments the trap's reference count.

Public Destructor

~RWTIOUTrap();

Destroys the handle and decrements the reference count of the current trap instance, if any, deleting the trap if its reference count reaches zero.

Public Member Operator

RWTIOUTrap<Redeemable>&
operator=(const RWTIOUTrap<Redeemable>& second)

Detaches this handle from its current trap instance, if any, decrementing the trap's reference count and deleting the trap if the count reaches zero. It then attaches to the trap instance, if any, pointed by second, and increments the new trap's reference count.

Public Member Functions

RWTIOUResult<Redeemable> 
getNext()

Gets the next redeemable RWTIOUResult<Redeemable>, and if none are ready, waits until one becomes available.

RWWaitStatus
getNext(RWTIOUResult<Redeemable>& iouResult, 
        unsigned long milliseconds);

Gets the next redeemable RWTIOUResult<Redeemable>, and if none are ready, waits until one becomes available. Returns with RW_THR_TIMEOUT status if an IOU does become redeemable within the specified number of milliseconds; otherwise the returned status is RW_THR_COMPLETED.

bool 
isEmpty() const;

Returns true if the queue is empty, false otherwise.

void
setTrap(RWTIOUResult<Redeemable> iou) const;

Traps the given IOU when it becomes redeemable.

bool
tryGetNext(RWTIOUResult<Redeemable>& iouResult);

Gets next redeemable RWTIOUResult<Redeemable> if one is available. Returns true and assigns the redeemable IOU to the iouResult argument, if an IOU has already been trapped, and otherwise returns false.