RWTIOUEscrow<Redeemable>

Module:  Threads   Package:  Interthread Communication

RWTIOUEscrow   RWTEscrowHandle<Redeemable>

• Local Index
• Header File
• Description
• Example
• Public Typedef
• Public Constructors
• Public Destructor
• Public Member Operators
• Public Member Functions
• See Also

Members

aborted() close() closeable() closed()

inError() newInstance() operator()() operator=()

RedeemableType redeemed() RWTIOUEscrow() setException()

~RWTIOUEscrow()

#include <rw/itc/RWTIOUEscrow.h> 

An RWTIOUEscrow<Redeemable> is a writable IOU handle. An IOU, also known as a future, is a promise for a value that is forthcoming -- 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.

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 template parameter Redeemable is the value type of IOU result. This type must provide a public copy-constructor and must allow dynamic allocation using operator new().

The RWTIOUEscrow<Redeemable> is the handle through which a value is eventually written to an underlying escrow object. One or more readers may redeem that value once it is available by using any RWTIOUResult<Redeemable> handle that is bound to the same escrow instance.

An RWTIOUEscrow<Redeemable> 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, then the internal RWTEscrowImp<Redeemable> is destroyed.

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

An exception may be set on an IOU by the holder of an RWTIOUEscrow<Redeemable>. This will cause the exception to be thrown when an attempt is made to redeem it.

Similarly, 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.

An RWTIOUEscrow<Redeemable> is closable if a value has not been set, if it has not been aborted, and if an exception has not been set.

#include <rw/itc/RWTIOUEscrow.h>             // for RWTIOUEscrow
#include <rw/itc/RWTIOUResult.h>             // for RWTIOUResult
#include <rw/thread/RWRunnableSelf.h>        // for ::rwSleep()
#include <rw/thread/RWThreadFunction.h>  // for RWThreadFunction
#include <rw/thread/rwtMakeThreadFunction.h  // for
                                        // rwtMakeThreadFunction
#include <rw/thread/rwtMakeThreadIOU.h> // for rwtMakeThreadIOU
#include <rw/itc/rwtMakeIOUCallback.h> // for rwtMakeIOUCallback


// This function is started in a thread and is passed an 
// RWTIOUEscrow<int>.
// It is expected to close the escrow.
void sixteen(RWTIOUEscrow<int> iouInt)
{
   ::rwSleep(500); // simulate useful activity
   iouInt = 16;    // close escrow
}

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 {
      RWThreadFunction thread;

      // Create an RWTIOUResult<int> using the
      // rwtMakeThreadIOU() helper function. This specifies 
      // that the IOU should be thread safe and the 
      // Redeemable type is int.
      RWTIOUResult<int> intResult = rwtMakeThreadIOU((int*)0);

      // create thread, pass in RWTIOUResult<int> as additional
      // arg. intResult will be converted into an
      // RWTIOUEscrow<int> in sixteen()
      thread = rwtMakeThreadFunction(sixteen, intResult);

      // register callback
      intResult.addCallback(rwtMakeIOUCallback(callback));

      thread.start();

      // block, wait for result
      int val = intResult;
      cout << "redeemed " << val << endl;
   }
   catch (...) {
      cout << "something bad happened" << endl;
   }
   return 0;
}

typedef Redeemable RedeemableType;

RWTIOUEscrow();

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

RWTIOUEscrow(const RWTEscrowHandle<Redeemable>& escrowHandle);

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

RWTIOUEscrow(const RWTIOUEscrow<Redeemable>& second);

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.

~RWTIOUEscrow();

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

RWTIOUEscrow<Redeemable>&
operator=(const RWTIOUEscrow<Redeemable>& second);

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 to by second, and increments the new Escrow's reference count.

void
operator=(Redeemable value)

Equivalent to close().

void
operator()(Redeemable value)

Equivalent to close().

bool
aborted() const;

Returns true if the IOU has been aborted, and false if not. Possible exceptions include RWTHRInvalidPointer.

void
close(const Redeemable& value);

Stores a value into the underlying escrow. If the IOU has already been closed, the function throws an RWTHREscrowAlreadyClosed exception. If the escrow operation has been aborted then exception RWTHROperationAborted is thrown. If an exception has been set, then that exception is thrown.

bool
closeable() const;

Returns true if the IOU has not been closed, closed with an error, or aborted; otherwise returns false. Possible exceptions include RWTHRInvalidPointer.

bool
closed();

Returns true if the IOU has been closed, and false if not. Possible exceptions include RWTHRInvalidPointer.

bool
inError();

Returns true if the IOU has been closed with an error, and false if not. Possible exceptions include RWTHRInvalidPointer.

RWTIOUEscrow<Redeemable>
newInstance() const;

Creates a new instance of the same class as the current concrete RWTEscrowImp<Redeemable> body. Returns a new RWTIOUEscrow<Redeemable> handle which points to the new body.

bool
redeemed() const;

Returns true if the IOU has been successfully redeemed at least once. and false if the escrow has never been redeemed. Possible exceptions include RWTHRInvalidPointer.

void
setException(const RWTHRxmsg& xmsg);

Used to indicate that IOU result could not be produced because an exception occurred. Causes a copy of the specified exception to be stored inside the IOU escrow object. The stored exception is rethrown in response to any attempt to redeem the IOU. If the IOU has already either been closed normally, closed with an error, or aborted, the error is ignored.

RWTIOUResult<Redeemable>, RWTEscrowHandle<Redeemable>, RWTEscrowImp<Redeemable>, RWTThreadEscrowImp<Redeemable>, rwtMakeThreadIOU()

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