RWTIOUTrap< Redeemable > Class Template Reference
[Interthread Communication]

Waits for the next IOU in a group of IOUs to become redeemable. More...

#include <rw/itc/RWTIOUTrap.h>

Inheritance diagram for RWTIOUTrap< Redeemable >:

List of all members.

Public Member Functions
	RWTIOUTrap (void)
	RWTIOUTrap (RWStaticCtor)
	RWTIOUTrap (const RWTIOUTrap< Redeemable > &second)
	~RWTIOUTrap (void)
RWTIOUTrap< Redeemable > &	operator= (const RWTIOUTrap< Redeemable > &second)
bool	isEmpty (void) const
void	setTrap (RWTIOUResult< Redeemable > iou) const
RWTIOUResult< Redeemable >	getNext (void)
RWWaitStatus	getNext (RWTIOUResult< Redeemable > &iouResult, unsigned long milliseconds)
bool	tryGetNext (RWTIOUResult< Redeemable > &iouResult)
Protected Member Functions
RWTIOUTrapImp< Redeemable > &	body (void) const

---

Detailed Description

template<class Redeemable>
class RWTIOUTrap< Redeemable >

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.

Examples

 #include <iostream>
 #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();
    std::cout << "next result = " << l << std::endl;
 }

---

Constructor & Destructor Documentation

template<class Redeemable >

RWTIOUTrap< Redeemable >::RWTIOUTrap

(

void

)

[inline]

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

template<class Redeemable >

RWTIOUTrap< Redeemable >::RWTIOUTrap

(

RWStaticCtor

)

[inline]

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

template<class Redeemable >

RWTIOUTrap< Redeemable >::RWTIOUTrap

(

const RWTIOUTrap< Redeemable > &

second

)

[inline]

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.

template<class Redeemable >

RWTIOUTrap< Redeemable >::~RWTIOUTrap

(

void

)

[inline]

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

---

Member Function Documentation

template<class Redeemable >

RWTIOUTrapImp< Redeemable > & RWTIOUTrap< Redeemable >::body

(

void

)

const [inline, protected]

Gets a reference for the body instance, if any.

Exceptions:

RWTHRInvalidPointer

Thrown if this handle is not attached to a body.

Reimplemented from RWHandleBase.

template<class Redeemable >

RWWaitStatus RWTIOUTrap< Redeemable >::getNext	(	RWTIOUResult< Redeemable > &	iouResult,
		unsigned long	milliseconds
	)			[inline]

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.

template<class Redeemable >

RWTIOUResult< Redeemable > RWTIOUTrap< Redeemable >::getNext

(

void

)

[inline]

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

template<class Redeemable >

bool RWTIOUTrap< Redeemable >::isEmpty

(

void

)

const [inline]

Returns true if the queue is empty, false otherwise.

template<class Redeemable >

RWTIOUTrap< Redeemable > & RWTIOUTrap< Redeemable >::operator=

(

const RWTIOUTrap< Redeemable > &

second

)

[inline]

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.

template<class Redeemable>

void RWTIOUTrap< Redeemable >::setTrap

(

RWTIOUResult< Redeemable >

iou

)

const

Traps the given IOU when it becomes redeemable.

template<class Redeemable >

bool RWTIOUTrap< Redeemable >::tryGetNext

(

RWTIOUResult< Redeemable > &

iouResult

)

[inline]

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.