RWTIOUResult< Redeemable > Class Template Reference

A readable IOU handle. More...

#include <rw/itc/RWTIOUResult.h>

Inheritance diagram for RWTIOUResult< Redeemable >:

Public Types
typedef Redeemable	RedeemableType
typedef RWTFunctor< void(RWTEscrowHandle< Redeemable >)>	RWTIOUResultCallback
Public Types inherited from RWTEscrowHandle< Redeemable >
typedef Redeemable	RedeemableType

Public Member Functions
	RWTIOUResult (void)
	RWTIOUResult (const RWTEscrowHandle< Redeemable > &escrowHandle)
	RWTIOUResult (const RWTIOUResult< Redeemable > &second)
	~RWTIOUResult (void)
void	abort (void) const
bool	aborted (void) const
void	addCallback (const RWTIOUResultCallback &callback)
bool	inError (void) const
	operator Redeemable (void) const
Redeemable	operator() (void) const
RWTIOUResult< Redeemable > &	operator= (const RWTIOUResult< Redeemable > &second)
Redeemable	redeem (void) const
bool	redeemable (void) const
bool	redeemed (void) const
void	removeCallback (const RWTIOUResultCallback &callback)
Public Member Functions inherited from RWTEscrowHandle< Redeemable >
	RWTEscrowHandle (void)
	RWTEscrowHandle (RWEscrowImpBase *imp)
	RWTEscrowHandle (const RWTEscrowHandle< Redeemable > &second)
RWTEscrowHandle< Redeemable > &	operator= (const RWTEscrowHandle< Redeemable > &second)
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

Related Functions
(Note that these are not member functions.)
template<class Redeemable >
RWTFunctor1< RWTEscrowHandle< Redeemable > >	rwtMakeIOUCallback (void(*function)(RWTIOUResult< Redeemable >))
template<class Redeemable , class Callee >
RWTFunctor1< RWTEscrowHandle< Redeemable > >	rwtMakeIOUCallback (Callee &callee, void(Callee::*function)(RWTIOUResult< Redeemable >))
template<class Redeemable , class A1 >
RWTFunctor1< RWTEscrowHandle< Redeemable > >	rwtMakeIOUCallback (void(*function)(RWTIOUResult< Redeemable >, A1), A1 a1)
template<class Redeemable , class Callee , class A1 >
RWTFunctor1< RWTEscrowHandle< Redeemable > >	rwtMakeIOUCallback (Callee &callee, void(Callee::*function)(RWTIOUResult< Redeemable >, A1), A1 a1)
template<class Redeemable , class A1 , class A2 >
RWTFunctor1< RWTEscrowHandle< Redeemable > >	rwtMakeIOUCallback (void(*function)(RWTIOUResult< Redeemable >, A1, A2), A1 a1, A2 a2)
template<class Redeemable , class Callee , class A1 , class A2 >
RWTFunctor1< RWTEscrowHandle< Redeemable > >	rwtMakeIOUCallback (Callee &callee, void(Callee::*function)(RWTIOUResult< Redeemable >, A1, A2), A1 a1, A2 a2)
#define	rwtMakeIOUCallbackG(function, Redeemable)
#define	rwtMakeIOUCallbackGA1(function, Redeemable, A1, a1)
#define	rwtMakeIOUCallbackGA2(function, Redeemable, A1, a1, A2, a2)
#define	rwtMakeIOUCallbackM(Callee, callee, function, Redeemable)
#define	rwtMakeIOUCallbackMA1(Callee, callee, function, Redeemable, A1, a1)
#define	rwtMakeIOUCallbackMA2(Callee, callee, function, Redeemable, A1, a1, A2, a2)

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 RWTIOUResult< Redeemable >

An RWTIOUResult is a readable IOU handle. An IOU, sometimes known as a future, is a promise for a value that is forthcoming, and is a placeholder for that value. Usually the writer of an IOU and the reader (or readers) of an IOU are in different threads of control. In this sense, IOUs are a mechanism for interthread communication.

The template parameter Redeemable is the value type of the IOU result. This type must provide a public copy-constructor and must allow dynamic allocation using operator new.

An IOU is a write once/read many structure. It may only be written to once, but may be read any number of times.

The RWTIOUResult handle is a reference counted handle to an RWTEscrowImp. It can be copied and passed by value. When the last handle to a given RWTEscrowImp is destroyed, the internal RWTEscrowImp is destroyed.

An RWTIOUResult can be initialized by or assigned to an RWTIOUEscrow, and vice versa. Both are interfaces to the same underlying RWTEscrowImp. RWTIOUResult is a read interface, and RWTIOUEscrow is a write interface.

The holder of the RWTIOUResult decides how and when to redeem the value held by the IOU. IOU redemption is the process of getting the result from the IOU when it is available. There are 3 ways to redeem an RWTIOUResult :

• Blocking. A call to RWTIOUResult::redeem() blocks the caller until the result is available.
• Polling. Calls to RWTIOUResult::redeemable() tell whether the IOU is redeemable. An IOU is redeemable if a value has been set, an exception has been set, or the IOU has been aborted.
• Callback. A callback function may be registered with the IOU using RWTIOUResult::addCallback(). The callback is called and passed an RWTIOUResult when the IOU is redeemable.

An IOU may be aborted by the holder of an RWTIOUResult. This will cause an exception to be thrown if an attempt is made to redeem the IOU or to set its value.

Similarly an exception may be set on an IOU by the holder of an RWTIOUEscrow. This causes the exception to be thrown when an attempt is made to redeem the IOU.

An RWTIOUResult is redeemable if a value has been set, if it has been aborted, or if an exception has been set.

Example

#include <rw/itc/RWTIOUResult.h>
#include <rw/thread/RWRunnableSelf.h>
#include <rw/thread/RWTThreadIOUFunction.h>

int sixteen(void)
{
    ::rwSleep(500); // simulate useful activity
    return 16;
}

void callback(RWTIOUResult<int> intIOUResult)
{
    try {
        int val = intIOUResult;  // redeem value
        std::cout << "callback received value of " << val << std::endl;
    }
    catch (...) {
        std::cout << "something bad happened" << std::endl;
    }
}

int main()
{
    try {
        RWTThreadIOUFunction<int> thread =
            RWTThreadIOUFunction<int>::make(sixteen);

        // get RWTIOUResult
        RWTIOUResult<int> iouRes = thread.result();

        // register callback
        iouRes.addCallback(callback);

        thread.start();

        // poll until redeemable
        while (!iouRes.redeemable()) {
            ::rwSleep(50);
        }

        // redeem RWTIOUResult
        std::cout << "redeemed " << iouRes.redeem() << std::endl;
    }
    catch (...) {
        std::cout << "something bad happened" << std::endl;
    }
    return 0;
}

Member Typedef Documentation

template<class Redeemable>

typedef Redeemable RWTIOUResult< Redeemable >::RedeemableType

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

template<class Redeemable>

typedef RWTFunctor<void(RWTEscrowHandle<Redeemable>)> RWTIOUResult< Redeemable >::RWTIOUResultCallback

A typedef for a callback function object.

Constructor & Destructor Documentation

template<class Redeemable >

RWTIOUResult< Redeemable >::~RWTIOUResult ( void  )

inline

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

template<class Redeemable >

RWTIOUResult< Redeemable >::RWTIOUResult ( void  )

inline

Creates an empty, invalid handle. Use of an instance created by the default constructor results in an RWTHRInvalidPointer exception being thrown. You can determine if an RWTIOUResult handle is valid by calling the isValid() member function, which is inherited from the RWHandleBase base class.

template<class Redeemable >

RWTIOUResult< Redeemable >::RWTIOUResult ( const RWTEscrowHandle< Redeemable > &  escrowHandle )

inline

Constructs a new handle instance and attaches it to the escrow instance, if any, pointed to by escrowHandle, and increments the escrow's reference count. This constructor allows an RWTIOUEscrow to be constructed from an RWTIOUResult.

template<class Redeemable >

RWTIOUResult< Redeemable >::RWTIOUResult ( const RWTIOUResult< Redeemable > &  second )

inline

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

Member Function Documentation

template<class Redeemable >

void RWTIOUResult< Redeemable >::abort ( void  ) const

inline

Tells the writer of an IOU that a result is no longer needed. Notifies anyone waiting to redeem the IOU so they can detect, abort, and catch an exception. Subsequent calls to redeem the IOU immediately receive an exception indicating that the operation associated with the IOU has already been aborted. This method is ignored if the operation has already been aborted. Possible exceptions include RWTHRInvalidPointer.

template<class Redeemable >

bool RWTIOUResult< Redeemable >::aborted ( void  ) const

inline

Returns true if the operation has been aborted, otherwise returns false. Possible exceptions include RWTHRInvalidPointer.

template<class Redeemable >

void RWTIOUResult< Redeemable >::addCallback ( const RWTIOUResultCallback &  callback )

inline

Adds a callback. The callback is called when the IOU is closed.

template<class Redeemable >

bool RWTIOUResult< Redeemable >::inError ( void  ) const

inline

Returns true if the IOU was closed with an error, otherwise returns false. Possible exceptions include RWTHRInvalidPointer.

template<class Redeemable >

RWTIOUResult< Redeemable >::operator Redeemable ( void  ) const

inline

Equivalent to redeem().

template<class Redeemable >

Redeemable RWTIOUResult< Redeemable >::operator() ( void  ) const

inline

Equivalent to redeem().

template<class Redeemable >

RWTIOUResult< Redeemable > & RWTIOUResult< Redeemable >::operator= ( const RWTIOUResult< Redeemable > &  second )

inline

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

template<class Redeemable >

Redeemable RWTIOUResult< Redeemable >::redeem ( void  ) const

inline

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

Throws RWTHROperationAborted if the IOU (or the associated operation) has been aborted. If an exception has been thrown and stored in the IOU, that exception is re-thrown.

template<class Redeemable >

bool RWTIOUResult< Redeemable >::redeemable ( void  ) const

inline

Returns true if the IOU has been closed, closed with an error, or aborted, otherwise returns false. This function is used to poll an IOU for the availability of a result. Possible exceptions include RWTHRInvalidPointer.

template<class Redeemable >

bool RWTIOUResult< Redeemable >::redeemed ( void  ) const

inline

Returns true if the IOU has been redeemed at least once, otherwise returns false. Possible exceptions include RWTHRInvalidPointer.

template<class Redeemable >

void RWTIOUResult< Redeemable >::removeCallback ( const RWTIOUResultCallback &  callback )

inline

Removes the callback represented by callback. If callback does not exist, does nothing.

Friends And Related Function Documentation

template<class Redeemable >

RWTFunctor1< RWTEscrowHandle< Redeemable > > rwtMakeIOUCallback ( void(*)(RWTIOUResult< Redeemable >)  function )

related

Deprecated:

As of SourcePro 12.5, use rwBind(function, rw1) instead.

The rwtMakeIOUCallback() helper functions create functors that may be passed to the addCallback() method of an RWTIOUResult. The functor may be created from functions that accept a first argument that is compatible with an RWTIOUResult.

Template function to create an IOU callback functor from a global function, function(), which takes an RWTIOUResult as its only argument.

Example

void function(RWTIOUResult<int> result);
RWTIOUResult<int> iouResult = ...;
iouResult.addCallback(rwtMakeIOUCallback(function));

template<class Redeemable , class Callee >

RWTFunctor1< RWTEscrowHandle< Redeemable > > rwtMakeIOUCallback ( Callee &  callee, void(Callee::*)(RWTIOUResult< Redeemable >)  function  )

related

Deprecated:

As of SourcePro 12.5, use rwBind(function, callee, rw1) instead.

The rwtMakeIOUCallback() helper functions create functors that may be passed to the addCallback() method of an RWTIOUResult. The functor may be created from functions that accept a first argument that is compatible with an RWTIOUResult.

Template function to create an IOU callback functor from a member function, callee.function(), which takes an RWTIOUResult as its only argument.

Example

class A {
public:
  void function(RWTIOUResult<int> result);  // Member function with no arguments
};

A a;
RWTIOUResult<int> iouResult = ...;
iouResult.addCallback(rwtMakeIOUCallback(a, &A::function));

template<class Redeemable , class A1 >

RWTFunctor1< RWTEscrowHandle< Redeemable > > rwtMakeIOUCallback ( void(*)(RWTIOUResult< Redeemable >, A1)  function, A1  a1  )

related

Deprecated:

As of SourcePro 12.5, use rwBind(function, rw1, a1) instead.

The rwtMakeIOUCallback() helper functions create functors that may be passed to the addCallback() method of an RWTIOUResult. The functor may be created from functions that accept a first argument that is compatible with an RWTIOUResult.

Template function to create an IOU callback functor from a global function, function(a1), which takes an RWTIOUResult and one additional argument.

Example

void function(RWTIOUResult<int>, A1);

A1 a1;
RWTIOUResult<int> iouResult = ...;
iouResult.addCallback(rwtMakeIOUCallback(function, a1));

template<class Redeemable , class Callee , class A1 >

RWTFunctor1< RWTEscrowHandle< Redeemable > > rwtMakeIOUCallback ( Callee &  callee, void(Callee::*)(RWTIOUResult< Redeemable >, A1)  function, A1  a1  )

related

Deprecated:

As of SourcePro 12.5, use rwBind(function, callee, rw1, a1) instead.

The rwtMakeIOUCallback() helper functions create functors that may be passed to the addCallback() method of an RWTIOUResult. The functor may be created from functions that accept a first argument that is compatible with an RWTIOUResult.

Template function to create an IOU callback functor from a member function, callee.function(a1), which takes an RWTIOUResult and one additional argument.

Example

class A {
public:
  void function(RWTIOUResult<int>, A1);  // Member function with 1 argument
};

A a;
A1 a1;
RWTIOUResult<int> iouResult = ...;
iouResult.addCallback(rwtMakeIOUCallback(a, &A::function, a1));

template<class Redeemable , class A1 , class A2 >

RWTFunctor1< RWTEscrowHandle< Redeemable > > rwtMakeIOUCallback ( void(*)(RWTIOUResult< Redeemable >, A1, A2)  function, A1  a1, A2  a2  )

related

Deprecated:

As of SourcePro 12.5, use rwBind(function, rw1, a1, a2) instead.

The rwtMakeIOUCallback() helper functions create functors that may be passed to the addCallback() method of an RWTIOUResult. The functor may be created from functions that accept a first argument that is compatible with an RWTIOUResult.

Template function to create an IOU callback functor from a global function, function(a1,a2), which takes an RWTIOUResult and two additional arguments.

Example

void function(RWTIOUResult<int>, A1, A2);

A1 a1;
A2 a2;
RWTIOUResult<int> iouResult = ...;
iouResult.addCallback(rwtMakeIOUCallback(function, a1, a2));

template<class Redeemable , class Callee , class A1 , class A2 >

RWTFunctor1< RWTEscrowHandle< Redeemable > > rwtMakeIOUCallback ( Callee &  callee, void(Callee::*)(RWTIOUResult< Redeemable >, A1, A2)  function, A1  a1, A2  a2  )

related

Deprecated:

As of SourcePro 12.5, use rwBind(function, callee, rw1, a1, a2) instead.

The rwtMakeIOUCallback() helper functions create functors that may be passed to the addCallback() method of an RWTIOUResult. The functor may be created from functions that accept a first argument that is compatible with an RWTIOUResult.

Template function to create an IOU callback functor from a member function, callee.function(a1,a2), which takes an RWTIOUResult and two additional arguments.

Example

class A {
public:
  void function(RWTIOUResult<int>, A1, A2);  // Member function with 2 arguments
};

A a;
A1 a1;
A2 a2;
RWTIOUResult<int> iouResult = ...;
iouResult.addCallback(rwtMakeIOUCallback(a, function, a1, a2));

template<class Redeemable>

#define rwtMakeIOUCallbackG (   function,   Redeemable  )

related

Deprecated:

As of SourcePro 12.5, use rwBind(function, rw1) instead.

The rwtMakeIOUCallback() helper functions and macros create functors that may be passed to the addCallback() method of an RWTIOUResult. The functor may be created from functions that accept a first argument that is compatible with an RWTIOUResult.

Since not all compilers are able to handle templates to the degree required by the rwtMakeIOUCallback() functions, we also provide a corresponding set of macros.

The template functions are slightly easier to use and you only have to remember one name. The macros are more portable but they do require more arguments; and because we cannot overload macros, each must have a unique name.

Creates an IOU callback functor from a global function, function(). function must have signature void(*)(RWTIOUResult )

Macro arguments:

function	Global function pointer.
Redeemable	The redeemable type of the RWTIOUResult.

Example

void function(RWTIOUResult<int> result);
RWTIOUResult<int> iouResult = ...;
iouResult.addCallback(rwtMakeIOUCallbackG(function, int));

template<class Redeemable>

#define rwtMakeIOUCallbackGA1 (   function,   Redeemable,   A1,   a1  )

related

Deprecated:

As of SourcePro 12.5, use rwBind(function, rw1, a1) instead.

The rwtMakeIOUCallback() helper functions and macros create functors that may be passed to the addCallback() method of an RWTIOUResult. The functor may be created from functions that accept a first argument that is compatible with an RWTIOUResult.

Since not all compilers are able to handle templates to the degree required by the rwtMakeIOUCallback() functions, we also provide a corresponding set of macros.

The template functions are slightly easier to use and you only have to remember one name. The macros are more portable but they do require more arguments; and because we cannot overload macros, each must have a unique name.

Creates an IOU callback functor from a global function, function(Redeemable,a1). function must have signature void (*)(RWTIOUResult,A1).

Macro Arguments:

function	Global function pointer.
Redeemable	The redeemable type of the RWTIOUResult.
A1	Type name of the first additional argument.
a1	Expression that can be converted to an instance of A1.

Example

void function(RWTIOUResult<int> result, A1 a1);

A1 a1;
RWTIOUResult<int> iouResult = ...;
iouResult.addCallback(rwtMakeIOUCallbackGA1(function, int, A1, a1));

template<class Redeemable>

#define rwtMakeIOUCallbackGA2 (   function,   Redeemable,   A1,   a1,   A2,   a2  )

related

Deprecated:

As of SourcePro 12.5, use rwBind(function, rw1, a1, a2) instead.

The rwtMakeIOUCallback() helper functions and macros create functors that may be passed to the addCallback() method of an RWTIOUResult. The functor may be created from functions that accept a first argument that is compatible with an RWTIOUResult.

Since not all compilers are able to handle templates to the degree required by the rwtMakeIOUCallback() functions, we also provide a corresponding set of macros.

The template functions are slightly easier to use and you only have to remember one name. The macros are more portable but they do require more arguments; and because we cannot overload macros, each must have a unique name.

Creates an IOU callback functor from a global function, function(a1,a2). function must have signature void (*)(RWTIOUResult,A1,A2).

Macro Arguments:

function	Global function pointer.
Redeemable	The redeemable type of the RWTIOUResult.
A1	Type name of the first additional argument.
a1	Expression that can be converted to an instance of A1.
A2	Type name of the second additional argument.
a2	Expression that can be converted to an instance of A2.

Example

void function(RWTIOUResult<int>, A1, A2);

A1 a1;
A2 a2;
RWTIOUResult<int> iouResult = ...;
iouResult.addCallback(rwtMakeIOUCallbackGA2(function, int, A1, a1, A2, a2));

template<class Redeemable>

#define rwtMakeIOUCallbackM (   Callee,   callee,   function,   Redeemable  )

related

Deprecated:

As of SourcePro 12.5, use rwBind(function, callee, rw1) instead.

The rwtMakeIOUCallback() helper functions and macros create functors that may be passed to the addCallback() method of an RWTIOUResult. The functor may be created from functions that accept a first argument that is compatible with an RWTIOUResult.

Since not all compilers are able to handle templates to the degree required by the rwtMakeIOUCallback() functions, we also provide a corresponding set of macros.

The template functions are slightly easier to use and you only have to remember one name. The macros are more portable but they do require more arguments; and because we cannot overload macros, each must have a unique name.

Creates an IOU callback functor from a member function, callee.function(). function must have signature void (Caller::*)(RWTIOUResult).

Macro Arguments:

Callee	Type name of the function's class.
callee	Expression that results in a reference to a Callee instance.
function	Global function pointer.
Redeemable	The redeemable type of the RWTIOUResult.

Example

class A {
public:
  void function(RWTIOUResult<int>);  // Member function with no arguments
};

A a;
RWTIOUResult<int> iouResult = ...;
iouResult.addCallback(rwtMakeIOUCallbackM(A, a, &A::function, int));

template<class Redeemable>

#define rwtMakeIOUCallbackMA1 (   Callee,   callee,   function,   Redeemable,   A1,   a1  )

related

Deprecated:

As of SourcePro 12.5, use rwBind(function, callee, rw1, a1) instead.

The rwtMakeIOUCallback() helper functions and macros create functors that may be passed to the addCallback() method of an RWTIOUResult. The functor may be created from functions that accept a first argument that is compatible with an RWTIOUResult.

Since not all compilers are able to handle templates to the degree required by the rwtMakeIOUCallback() functions, we also provide a corresponding set of macros.

The template functions are slightly easier to use and you only have to remember one name. The macros are more portable but they do require more arguments; and because we cannot overload macros, each must have a unique name.

Creates an IOU callback functor from a member function, callee.function(a1). function must have signature void (Caller::*)(RWTIOUResult,A1).

Macro Arguments:

Callee	Type name of the function's class.
callee	Expression that results in a reference to a Callee instance.
function	Global function pointer.
Redeemable	The redeemable type of the RWTIOUResult.
A1	Type name of the first additional argument.
a1	Expression that can be converted to an instance of A1.

Example

class A {
public:
  void function(RWTIOUResult<int>, A1);  // Member function with 1 argument
};

A a;
A1 a1;
RWTIOUResult<int> iouResult = ...;
iouResult.addCallback(rwtMakeIOUCallbackMA1(A, a, &A::function, int, A1, a1));

template<class Redeemable>

#define rwtMakeIOUCallbackMA2 (   Callee,   callee,   function,   Redeemable,   A1,   a1,   A2,   a2  )

related

Deprecated:

As of SourcePro 12.5, use rwBind(function, callee, rw1, a1, a2) instead.

The rwtMakeIOUCallback() helper functions and macros create functors that may be passed to the addCallback() method of an RWTIOUResult. The functor may be created from functions that accept a first argument that is compatible with an RWTIOUResult.

Since not all compilers are able to handle templates to the degree required by the rwtMakeIOUCallback() functions, we also provide a corresponding set of macros.

The template functions are slightly easier to use and you only have to remember one name. The macros are more portable but they do require more arguments; and because we cannot overload macros, each must have a unique name.

Macro Arguments:

Callee	Type name of the function's class.
callee	Expression that results in a reference to a Callee instance.
function	Global function pointer.
Redeemable	The redeemable type of the RWTIOUResult.
A1	Type name of the first additional argument.
a1	Expression that can be converted to an instance of A1.
A2	Type name of the second additional argument.
a2	Expression that can be converted to an instance of A2.

Creates an IOU callback functor from a member function, callee.function(a1,a2). function must have signature void (Caller::*)(RWTIOUResult,A1,A2).

Example

class A {
public:
  void function(RWTIOUResult<int>, A1, A2);  // Member function with 2 arguments
};

A a;
A1 a1;
A2 a2;
RWTIOUResult<int> iouResult = ...;
iouResult.addCallback(rwtMakeIOUCallbackMA2(A, a, &A::function, int, A1, a1, A2, a2));