RWTEscrowImp< Redeemable > Class Template Reference
[Interthread Communication]

Base class for all concrete IOU escrow implementations. More...

#include <rw/itc/RWTEscrowImp.h>

Inheritance diagram for RWTEscrowImp< Redeemable >:

List of all members.

Public Types
typedef Redeemable	RedeemableType
typedef RWTFunctor1 < RWTEscrowHandle< Redeemable > >	RWTIOUResultCallback
Public Member Functions
virtual	~RWTEscrowImp (void)
void	abort (void)
bool	aborted (void) const
void	addCallback (const RWTIOUResultCallback &iouResultCallback)
void	close (const Redeemable &value)
bool	closeable (void) const
bool	closed (void) const
bool	inError (void) const
RWTEscrowHandle< Redeemable >	newInstance (void) const
const Redeemable &	redeem (void) const
bool	redeemable (void) const
bool	redeemed (void) const
void	removeCallback (const RWTIOUResultCallback &iouResultCallback)
void	setException (const RWTHRxmsg &xmsg)
Protected Member Functions
	RWTEscrowImp (void)

---

Detailed Description

template<class Redeemable>
class RWTEscrowImp< Redeemable >

RWTEscrowImp<Redeemable> serves as the base class for all concrete IOU escrow implementations. It provides basic functionality and allows for extension via virtual functions.

This class should never be used directly. It should only be used through RWTIOUResult<Redeemable> and RWTIOUEscrow<Redeemable> handles. The interface of RWTEscrowImp<Redeemable> is a union of the interfaces provided by RWTIOUResult<Redeemable> and RWTIOUEscrow<Redeemable> .

---

Member Typedef Documentation

template<class Redeemable >

typedef Redeemable RWTEscrowImp< Redeemable >::RedeemableType

A synonym for the value type of the IOU, or future, result.

Reimplemented in RWTThreadEscrowImp< Redeemable >.

template<class Redeemable >

typedef RWTFunctor1< RWTEscrowHandle<Redeemable> > RWTEscrowImp< Redeemable >::RWTIOUResultCallback

A typedef for a callback function created by rwtMakeIOUCallback().

---

Constructor & Destructor Documentation

template<class Redeemable >

virtual RWTEscrowImp< Redeemable >::~RWTEscrowImp

(

void

)

[virtual]

Virtual destructor.

template<class Redeemable >

RWTEscrowImp< Redeemable >::RWTEscrowImp

(

void

)

[protected]

RWTEscrowImp<Redeemable> may not be explicitly constructed. It may only be constructed implicitly using make() functions in concrete derived classes. The derived-class make() functions return an RWTEscrowHandle<Redeemable> for initializing an RWTIOUEscrow<Redeemable> or RWTIOUResult<Redeemable> .

This means that, under normal circumstances, you will never see a raw RWTEscrowImp<Redeemable> pointer.

---

Member Function Documentation

template<class Redeemable >

void RWTEscrowImp< Redeemable >::abort

(

void

)

Tells the service provider that the result is no longer needed. Notifies anyone waiting on the IOU, so they can detect abort and catch an exception. Subsequent calls to redeem the IOU will immediately receive an exception, indicating that the operation associated with the Escrow has been aborted. Ignored if the operation was already aborted.

template<class Redeemable >

bool RWTEscrowImp< Redeemable >::aborted

(

void

)

const

Returns true if the operation has been aborted.

template<class Redeemable >

void RWTEscrowImp< Redeemable >::addCallback

(

const RWTIOUResultCallback &

iouResultCallback

)

Adds a callback. The callback is fired when the Escrow is closed.

template<class Redeemable >

void RWTEscrowImp< Redeemable >::close

(

const Redeemable &

value

)

Stores a value into the Escrow. If the Escrow has already been closed then an RWTHREscrowAlreadyClosed exception will be thrown. If the escrow operation has been aborted, then an RWTHROperationAborted exception is thrown. If an exception has been set, then that exception is thrown.

template<class Redeemable >

bool RWTEscrowImp< Redeemable >::closeable

(

void

)

const

Can a value be written into the Escrow? true if no value has been written and the escrow isn't in error or aborted.

template<class Redeemable >

bool RWTEscrowImp< Redeemable >::closed

(

void

)

const

Has a value been successfully written into the Escrow? (Note that redeemable() or !closeable() is better for polling as they will inform of errors and abortion in addition to valid closures).

template<class Redeemable >

bool RWTEscrowImp< Redeemable >::inError

(

void

)

const

Was the Escrow closed with an error? If it was, then the function returns true and the caller can expect an exception to be thrown on the next call to redeem.

template<class Redeemable >

RWTEscrowHandle<Redeemable> RWTEscrowImp< Redeemable >::newInstance

(

void

)

const

Creates a new instance of this RWTEscrowImp<Redeemable> type. Implemented by most derived types.

template<class Redeemable >

const Redeemable& RWTEscrowImp< Redeemable >::redeem

(

void

)

const

Gets the result, blocking if the result is not yet available.

Exceptions:

RWTHROperationAborted

Thrown if the Escrow (or the associated operation) has been aborted. If an exception is thrown and stored in the Escrow, then that exception is re-thrown by this routine.

template<class Redeemable >

bool RWTEscrowImp< Redeemable >::redeemable

(

void

)

const

Returns true if a proper value has been set, if an error has been set, or if the operation has been aborted. This function is used primarily by the reader side to poll the Escrow for the availability of a result.

template<class Redeemable >

bool RWTEscrowImp< Redeemable >::redeemed

(

void

)

const

Returns whether the result has been successfully redeemed. Note that redemption that results in the throwing of an exception does not count as a success.

template<class Redeemable >

void RWTEscrowImp< Redeemable >::removeCallback

(

const RWTIOUResultCallback &

iouResultCallback

)

Removes callback if it exists; otherwise does nothing.

template<class Redeemable >

void RWTEscrowImp< Redeemable >::setException

(

const RWTHRxmsg &

xmsg

)

Sets an error on the Escrow and causes an exception to be stored inside the Escrow. Notifies callers waiting for the Escrow to be closed so that they can redeem the IOU and catch the error. If the Escrow has already been closed normally, closed with an error, or aborted, then the error is ignored.