RWTIOUTrap<Redeemable>RWHandleBase
#include <rw/itc/RWTIOUTrap.h>
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.
#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;
}
RWTIOUTrap(void);
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.
~RWTIOUTrap(void);
Destroys the handle and decrements the reference count of the current trap instance, if any, deleting the trap if its reference count reaches zero.
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.
RWTIOUResult<Redeemable> getNext(void)
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.
RWBoolean isEmpty(void) const;
Returns TRUE if the queue is empty, FALSE otherwise.
void setTrap(RWTIOUResult<Redeemable> iou) const;
Traps the given IOU when it becomes redeemable.
RWBoolean 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.
static RWTIOUTrap<Redeemable> make(void);
Makes a new RWTIOUTrapImp<Redeemable> and returns an RWTIOUTrap<Redeemable> handle.
RWTIOUTrap(RWTIOUTrapImp<Redeemable>* iouTrapImpP);
Constructs a handle from an RWTIOUTrapImp<Redeemable>*.
©Copyright 2000, Rogue Wave Software, Inc.
Contact Rogue Wave about documentation or support issues.