SourcePro® API Reference Guide

 
Loading...
Searching...
No Matches
RWTIOUEscrow< Redeemable > Class Template Reference

A writable IOU handle. More...

#include <rw/itc/RWTIOUEscrow.h>

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

Public Types

typedef Redeemable RedeemableType
 
- Public Types inherited from RWTEscrowHandle< Redeemable >
typedef Redeemable RedeemableType
 

Public Member Functions

 RWTIOUEscrow (const RWTEscrowHandle< Redeemable > &escrowHandle)
 
 RWTIOUEscrow (const RWTIOUEscrow< Redeemable > &second)
 
 RWTIOUEscrow (void)
 
 ~RWTIOUEscrow (void)
 
bool aborted (void) const
 
void close (const Redeemable &value)
 
bool closeable (void) const
 
bool closed (void)
 
bool inError (void)
 
RWTIOUEscrow< Redeemable > newInstance (void) const
 
void operator() (const Redeemable &value)
 
void operator= (const Redeemable &value)
 
RWTIOUEscrow< Redeemable > & operator= (const RWTIOUEscrow< Redeemable > &second)
 
bool redeemed (void) const
 
void setException (const RWCString &msg)
 
void setException (const RWTHRxmsg &xmsg)
 
- Public Member Functions inherited from RWTEscrowHandle< Redeemable >
 RWTEscrowHandle (const RWTEscrowHandle< Redeemable > &second)
 
 RWTEscrowHandle (RWEscrowImpBase *imp)
 
 RWTEscrowHandle (void)
 
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
 

Additional Inherited Members

- Protected Member Functions inherited from RWHandleBase
 RWHandleBase (const RWHandleBase &second)
 
 RWHandleBase (RWBodyBase *body)
 
 RWHandleBase (RWStaticCtor)
 
 RWHandleBase (void)
 
 ~RWHandleBase (void)
 
RWBodyBasebody (void) const
 
RWHandleBaseoperator= (const RWHandleBase &second)
 

Detailed Description

template<class Redeemable>
class RWTIOUEscrow< Redeemable >

An RWTIOUEscrow 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 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 handle that is bound to the same escrow instance.

An RWTIOUEscrow 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 RWTIOUEscrow can be initialized by or assigned to an RWTIOUResult, and vice versa. Both are interfaces to the same underlying RWTEscrowImp. RWTIOUEscrow is a write interface, and RWTIOUResult is a read interface.

An exception may be set on an IOU by the holder of an RWTIOUEscrow. 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. This will cause an exception to be thrown if an attempt is made to redeem the IOU or to set its value.

An RWTIOUEscrow is closeable if a value has not been set, it has not been aborted, and no exception has been set.

Example
#include <rw/thread/RWRunnableSelf.h>
#include <rw/thread/RWTThreadEscrowImp.h>
#include <rw/thread/RWThreadFunction.h>
#include <rw/itc/RWTIOUEscrow.h>
#include <rw/itc/RWTIOUResult.h>
#include <rw/functor/rwBind.h>
// 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
std::cout << "callback received value of " << val << std::endl;
} catch (...) {
std::cout << "something bad happened" << std::endl;
}
}
int main() {
try {
// Create a thread-safe IOU with a redeemable type of int.
// create thread, pass in RWTIOUResult<int> as additional
// arg. intResult will be converted into an
// RWTIOUEscrow<int> in sixteen()
RWThreadFunction::make(rwBind(sixteen, intResult));
// register callback
intResult.addCallback(callback);
thread.start();
// block, wait for result
int val = intResult;
std::cout << "redeemed " << val << std::endl;
} catch (...) {
std::cout << "something bad happened" << std::endl;
}
return 0;
}
RWCompletionState start()
A writable IOU handle.
Definition RWTIOUEscrow.h:119
A readable IOU handle.
Definition RWTIOUResult.h:122
void addCallback(const RWTIOUResultCallback &callback)
Definition RWTIOUResult.h:284
static RWTEscrowHandle< Redeemable > make()
Handle class for functor-based threaded runnable objects.
Definition RWThreadFunction.h:90
static RWThreadFunction make()
unspecified_type rwBind(C &&c, As &&... args)
Binds a callable and arguments into a callable object.

Member Typedef Documentation

◆ RedeemableType

template<class Redeemable >
typedef Redeemable RWTIOUEscrow< Redeemable >::RedeemableType

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

Constructor & Destructor Documentation

◆ ~RWTIOUEscrow()

template<class Redeemable >
RWTIOUEscrow< Redeemable >::~RWTIOUEscrow ( 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.

◆ RWTIOUEscrow() [1/3]

template<class Redeemable >
RWTIOUEscrow< Redeemable >::RWTIOUEscrow ( 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 RWTIOUEscrow handle is valid by calling the isValid() member function, which is inherited from the RWHandleBase base class.

◆ RWTIOUEscrow() [2/3]

template<class Redeemable >
RWTIOUEscrow< Redeemable >::RWTIOUEscrow ( 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.

◆ RWTIOUEscrow() [3/3]

template<class Redeemable >
RWTIOUEscrow< Redeemable >::RWTIOUEscrow ( const RWTIOUEscrow< 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

◆ aborted()

template<class Redeemable >
bool RWTIOUEscrow< Redeemable >::aborted ( void ) const
inline

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

◆ close()

template<class Redeemable >
void RWTIOUEscrow< Redeemable >::close ( const Redeemable & value)
inline

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, the function throws an RWTHROperationAborted exception. If an exception has been set, that exception is thrown.

◆ closeable()

template<class Redeemable >
bool RWTIOUEscrow< Redeemable >::closeable ( void ) const
inline

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

◆ closed()

template<class Redeemable >
bool RWTIOUEscrow< Redeemable >::closed ( void )
inline

Returns true if the IOU has been closed, otherwise returns false. Possible exceptions include RWTHRInvalidPointer.

◆ inError()

template<class Redeemable >
bool RWTIOUEscrow< Redeemable >::inError ( void )
inline

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

◆ newInstance()

template<class Redeemable >
RWTIOUEscrow< Redeemable > RWTIOUEscrow< Redeemable >::newInstance ( void ) const
inline

Creates a new instance of the same class as the current concrete RWTEscrowImp body. Returns a new RWTIOUEscrow handle that points to the new body.

◆ operator()()

template<class Redeemable >
void RWTIOUEscrow< Redeemable >::operator() ( const Redeemable & value)
inline

Equivalent to close().

◆ operator=() [1/2]

template<class Redeemable >
void RWTIOUEscrow< Redeemable >::operator= ( const Redeemable & value)
inline

Equivalent to close().

◆ operator=() [2/2]

template<class Redeemable >
RWTIOUEscrow< Redeemable > & RWTIOUEscrow< Redeemable >::operator= ( const RWTIOUEscrow< 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 to by second, and increments the new escrow's reference count.

◆ redeemed()

template<class Redeemable >
bool RWTIOUEscrow< Redeemable >::redeemed ( void ) const
inline

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

◆ setException() [1/2]

template<class Redeemable >
void RWTIOUEscrow< Redeemable >::setException ( const RWCString & msg)
inline

Used to indicate that IOU result could not be produced because an exception occurred. The string message is packaged in an RWTHRxmsg and stored inside the IOU escrow object. The stored exception is thrown 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.

◆ setException() [2/2]

template<class Redeemable >
void RWTIOUEscrow< Redeemable >::setException ( const RWTHRxmsg & xmsg)
inline

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.

Copyright © 2024 Rogue Wave Software, Inc., a Perforce company. All Rights Reserved.