rwlogo
SourcePro C++ 12.0

SourcePro® C++ API Reference Guide



   SourcePro C++
Documentation Home

RWTIOUResult< Redeemable > Class Template Reference
[Interthread Communication]

A readable IOU handle. More...

#include <rw/itc/RWTIOUResult.h>

Inheritance diagram for RWTIOUResult< Redeemable >:
RWTEscrowHandle< Redeemable > RWHandleBase

List of all members.

Public Types

typedef Redeemable RedeemableType
typedef RWTFunctor1
< RWTEscrowHandle< Redeemable > > 
RWTIOUResultCallback

Public Member Functions

 ~RWTIOUResult (void)
 RWTIOUResult (void)
 RWTIOUResult (const RWTEscrowHandle< Redeemable > &escrowHandle)
 RWTIOUResult (const RWTIOUResult< Redeemable > &second)
RWTIOUResult< Redeemable > & operator= (const RWTIOUResult< Redeemable > &second)
void abort (void) const
bool aborted (void) const
void addCallback (const RWTIOUResultCallback &callback)
bool inError (void) const
Redeemable operator() (void) const
 operator Redeemable (void) const
Redeemable redeem (void) const
bool redeemable (void) const
bool redeemed (void) const
void removeCallback (const RWTIOUResultCallback &callback)

Protected Member Functions

RWTEscrowImp< Redeemable > & body (void) const

Related Functions

(Note that these are not member functions.)



 rwtMakeIOUCallbackG(function, Redeemable)
template<class Redeemable >
RWTFunctor1< RWTEscrowHandle
< Redeemable > > 
rwtMakeIOUCallback (void(*function)(RWTIOUResult< Redeemable >))
 rwtMakeIOUCallbackM(Callee, callee, function, Redeemable)
template<class Redeemable , class Callee >
RWTFunctor1< RWTEscrowHandle
< Redeemable > > 
rwtMakeIOUCallback (Callee &callee, void(Callee::*function)(RWTIOUResult< Redeemable >))
 rwtMakeIOUCallbackGA1(function, Redeemable, A1, a1)
template<class Redeemable , class A1 >
RWTFunctor1< RWTEscrowHandle
< Redeemable > > 
rwtMakeIOUCallback (void(*function)(RWTIOUResult< Redeemable >, A1), A1 a1)
 rwtMakeIOUCallbackMA1(Callee, callee, function, Redeemable, A1, a1)
template<class Redeemable , class Callee , class A1 >
RWTFunctor1< RWTEscrowHandle
< Redeemable > > 
rwtMakeIOUCallback (Callee &callee, void(Callee::*function)(RWTIOUResult< Redeemable >, A1), A1 a1)
 rwtMakeIOUCallbackGA2(function, Redeemable, A1, a1, A2, a2)
template<class Redeemable , class A1 , class A2 >
RWTFunctor1< RWTEscrowHandle
< Redeemable > > 
rwtMakeIOUCallback (void(*function)(RWTIOUResult< Redeemable >, A1, A2), A1 a1, A2 a2)
 rwtMakeIOUCallbackMA2(Callee, callee, function, Redeemable, 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)

Detailed Description

template<class Redeemable>
class RWTIOUResult< Redeemable >

An RWTIOUResult<Redeemable> 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<Redeemable> handle is a reference counted handle to an RWTEscrowImp<Redeemable> . It can be copied and passed by value. When the last handle to a given RWTEscrowImp<Redeemable> is destroyed, the internal RWTEscrowImp<Redeemable> is destroyed.

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

The holder of the RWTIOUResult<Redeemable> 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<Redeemable> :

An IOU may be aborted by the holder of an RWTIOUResult<Redeemable> . 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<Redeemable> . This causes the exception to be thrown when an attempt is made to redeem the IOU.

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

Examples

 #include <rw/thread/RWTThreadIOUFunction.h> // for RWTThreadIOUFunction
 #include <rw/itc/rwtMakeIOUCallback.h>      // for rwtMakeIOUCallback
 #include <rw/itc/RWTIOUResult.h>            // for RWTIOUResult<Redeemable>
 #include <rw/thread/RWRunnableSelf.h>       // for ::rwSleep()
 
 int sixteen(void)
 {
    ::rwSleep(500); // simulate useful activity
    return 16;
 }
 
 void callback(RWTIOUResult<int> intIOUResult) {
    try {
       int val = intIOUResult;  // redeem value
       cout << "callback received value of " << val << endl;
    }
    catch (...) { cout << "something bad happened" << endl; }
 }
 
 int main()
 {
    try {
       RWTThreadIOUFunction<int> thread;
       thread = rwtMakeThreadIOUFunction(sixteen);

       // get RWTIOUResult
       RWTIOUResult<int> iouRes = thread.result(); 
 
       // register callback
       iouRes.addCallback(rwtMakeIOUCallback(callback));
 
       thread.start();
 
       // poll until redeemable
       while (!iouRes.redeemable()) ::rwSleep(50);
 
       // redeem RWTIOUResult
       cout << "redeemed " << iouRes.redeem() << endl;
    }
    catch (...) {
       cout << "something bad happened" << 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.

Reimplemented from RWTEscrowHandle< Redeemable >.

template<class Redeemable>
typedef RWTFunctor1< RWTEscrowHandle<Redeemable> > RWTIOUResult< Redeemable >::RWTIOUResultCallback

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


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<Redeemable> 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<Redeemable> to be constructed from an RWTIOUResult<Redeemable> .

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 >
RWTEscrowImp< Redeemable > & RWTIOUResult< 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 >
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 , class Callee , class A1 , class A2 >
RWTFunctor1< RWTEscrowHandle< Redeemable > > rwtMakeIOUCallback ( Callee &  callee,
void(Callee::*)(RWTIOUResult< Redeemable >, A1, A2)  function,
A1  a1,
A2  a2 
) [related]

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

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

Examples

 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 , class A1 , class A2 >
RWTFunctor1< RWTEscrowHandle< Redeemable > > rwtMakeIOUCallback ( void(*)(RWTIOUResult< Redeemable >, A1, A2)  function,
A1  a1,
A2  a2 
) [related]

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

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

Examples

 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 >
RWTFunctor1< RWTEscrowHandle< Redeemable > > rwtMakeIOUCallback ( Callee &  callee,
void(Callee::*)(RWTIOUResult< Redeemable >, A1)  function,
A1  a1 
) [related]

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

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

Examples

 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 >
RWTFunctor1< RWTEscrowHandle< Redeemable > > rwtMakeIOUCallback ( void(*)(RWTIOUResult< Redeemable >, A1)  function,
A1  a1 
) [related]

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

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

Examples

 void function(RWTIOUResult<int>, A1);

 A1 a1;
 RWTIOUResult<int> iouResult = ...;
 iouResult.addCallback(rwtMakeIOUCallback(function, a1));
template<class Redeemable , class Callee >
RWTFunctor1< RWTEscrowHandle< Redeemable > > rwtMakeIOUCallback ( Callee &  callee,
void(Callee::*)(RWTIOUResult< Redeemable >)  function 
) [related]

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

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

Examples

 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 >
RWTFunctor1< RWTEscrowHandle< Redeemable > > rwtMakeIOUCallback ( void(*)(RWTIOUResult< Redeemable >)  function  )  [related]

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

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

Examples

 void function(RWTIOUResult<int> result);
 RWTIOUResult<int> iouResult = ...;
 iouResult.addCallback(rwtMakeIOUCallback(function));
template<class Redeemable>
rwtMakeIOUCallbackG ( function,
Redeemable   )  [related]

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

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

Macro arguments:

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

Examples

 void function(RWTIOUResult<int> result);
 RWTIOUResult<int> iouResult = ...;
 iouResult.addCallback(rwtMakeIOUCallbackG(function, int));
template<class Redeemable>
rwtMakeIOUCallbackGA1 ( function,
Redeemable,
A1,
a1   )  [related]

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

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<Redeemable>,A1).

Macro Arguments:

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

Examples

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

 A1 a1;
 RWTIOUResult<int> iouResult = ...;
 iouResult.addCallback(rwtMakeIOUCallbackGA1(function, int, A1, a1));
template<class Redeemable>
rwtMakeIOUCallbackGA2 ( function,
Redeemable,
A1,
a1,
A2,
a2   )  [related]

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

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<Redeemable>,A1,A2).

Macro Arguments:

function Global function pointer.
Redeemable The redeemable type of the RWTIOUResult<Redeemable>.
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.

Examples

 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>
rwtMakeIOUCallbackM ( Callee,
callee,
function,
Redeemable   )  [related]

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

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<Redeemable>).

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

Examples

 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>
rwtMakeIOUCallbackMA1 ( Callee,
callee,
function,
Redeemable,
A1,
a1   )  [related]

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

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<Redeemable>,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<Redeemable>.
A1 Type name of the first additional argument.
a1 Expression that can be converted to an instance of A1.

Examples

 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>
rwtMakeIOUCallbackMA2 ( Callee,
callee,
function,
Redeemable,
A1,
a1,
A2,
a2   )  [related]

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

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<Redeemable>.
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<Redeemable>,A1,A2).

Examples

 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));
 All Classes Functions Variables Typedefs Enumerations Enumerator Friends

© Copyright Rogue Wave Software, Inc. All Rights Reserved.
Rogue Wave and SourcePro are registered trademarks of Rogue Wave Software, Inc. in the United States and other countries. All other trademarks are the property of their respective owners.
Contact Rogue Wave about documentation or support issues.