RWTIOUTrap< Redeemable > Class Template Reference

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

#include <rw/itc/RWTIOUTrap.h>

Inheritance diagram for RWTIOUTrap< Redeemable >:

Public Member Functions
	RWTIOUTrap (void)
	RWTIOUTrap (RWStaticCtor)
	RWTIOUTrap (const RWTIOUTrap< Redeemable > &second)
	~RWTIOUTrap (void)
RWTIOUResult< Redeemable >	getNext (void)
RWWaitStatus	getNext (RWTIOUResult< Redeemable > &iouResult, unsigned long milliseconds)
bool	isEmpty (void) const
RWTIOUTrap< Redeemable > &	operator= (const RWTIOUTrap< Redeemable > &second)
void	setTrap (RWTIOUResult< Redeemable > iou) const
bool	tryGetNext (RWTIOUResult< Redeemable > &iouResult)
Public Member Functions inherited from RWHandleBase
bool	isValid (void) const
bool	operator!= (const RWHandleBase &second) const
bool	operator< (const RWHandleBase &second) const
bool	operator== (const RWHandleBase &second) const

Additional Inherited Members
Protected Member Functions inherited from RWHandleBase
	RWHandleBase (void)
	RWHandleBase (RWStaticCtor)
	RWHandleBase (RWBodyBase *body)
	RWHandleBase (const RWHandleBase &second)
	~RWHandleBase (void)
RWBodyBase &	body (void) const
RWHandleBase &	operator= (const RWHandleBase &second)

Detailed Description

template<class Redeemable>
class RWTIOUTrap< Redeemable >

RWTIOUTrap allows you to wait for the 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 RWTThreadIOUFunction 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 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 automatically notifies the trap when it becomes redeemable. RWTIOUTrap uses a producer-consumer queue to store each IOU as it notifies the trap that it is redeemable. An RWTIOUResult 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 implemented as a handle-body object. The RWTIOUTrap is the handle for an IOU trap object. These handles can be passed and shared by value. The actual trap object is deleted when the last handle that references it is destroyed.

Example

#include <iostream>
#include <rw/itc/RWTIOUTrap.h>

int main(void)
{
    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 instance bound to a new body instance.

template<class Redeemable >

RWTIOUTrap< Redeemable >::RWTIOUTrap ( RWStaticCtor  )

inline

Constructs a static RWTIOUTrap handle instance. This constructor does not construct a body 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 equals zero.

Member Function Documentation

template<class Redeemable >

RWTIOUResult< Redeemable > RWTIOUTrap< Redeemable >::getNext ( void  )

inline

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

template<class Redeemable >

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

inline

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

template<class Redeemable >

bool RWTIOUTrap< Redeemable >::isEmpty ( void  ) const

inline

Returns true if the queue is empty, otherwise returns false.

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 equals 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 if one is available. If an IOU has already been trapped, returns true and assigns the redeemable IOU to the iouResult argument, otherwise returns false.