Main Page   Class Hierarchy   Alphabetical List   Compound List   File List   Compound Members   File Members   Related Pages  

ACE_Future Class Template Reference

This class implements a ``single write, multiple read'' pattern that can be used to return results from asynchronous method invocations. More...

#include <Future.h>

Collaboration diagram for ACE_Future:

Collaboration graph
[legend]
List of all members.

Public Methods

 ACE_Future (void)
 Constructor. More...

 ACE_Future (const ACE_Future< T > &r)
 Copy constructor binds this and r to the same ACE_Future_Rep. An ACE_Future_Rep is created if necessary. More...

 ACE_Future (const T &r)
 Constructor that initialises an ACE_Future to point to the result r immediately. More...

 ~ACE_Future (void)
 Destructor. More...

void operator= (const ACE_Future< T > &r)
 Assignment operator that binds this and r to the same ACE_Future_Rep. An ACE_Future_Rep is created if necessary. More...

int cancel (const T &r)
 Cancel an ACE_Future and assign the value r. It is used if a client does not want to wait for the value to be produced. More...

int cancel (void)
int operator== (const ACE_Future< T > &r) const
int operator!= (const ACE_Future< T > &r) const
 Inequality operator, which is the opposite of equality. More...

int set (const T &r)
int get (T &value, ACE_Time_Value *tv=0) const
 operator T ()
int ready (void) const
 Check if the result is available. More...

int attach (ACE_Future_Observer< T > *observer)
int detach (ACE_Future_Observer< T > *observer)
void dump (void) const
 Dump the state of an object. More...

ACE_Future_Rep< T > * get_rep (void)

Public Attributes

 ACE_ALLOC_HOOK_DECLARE
 Declare the dynamic allocation hooks. More...


Private Types

typedef ACE_Future_Rep< T > FUTURE_REP
 Protect operations on the <Future>. More...


Private Methods

void * operator new (size_t nbytes)
 Do not allow new operator. More...

void operator delete (void *)
 Do not allow delete operator. More...

void operator & ()
 Do not allow address-of operator. More...


Private Attributes

FUTURE_REPfuture_rep_

Detailed Description

template<class T>
class ACE_Future< T >

This class implements a ``single write, multiple read'' pattern that can be used to return results from asynchronous method invocations.

Definition at line 233 of file Future.h.


Member Typedef Documentation

template<class T>
typedef ACE_Future_Rep<T> ACE_Future::FUTURE_REP [private]
 

Protect operations on the <Future>.

Definition at line 371 of file Future.h.


Constructor & Destructor Documentation

template<class T>
ACE_Future< T >::ACE_Future void   
 

Constructor.

Definition at line 282 of file Future.cpp.

00283   : future_rep_ (FUTURE_REP::create ())
00284 {
00285 }

template<class T>
ACE_Future< T >::ACE_Future const ACE_Future< T > &    r
 

Copy constructor binds this and r to the same ACE_Future_Rep. An ACE_Future_Rep is created if necessary.

Definition at line 288 of file Future.cpp.

00289   : future_rep_ (FUTURE_REP::attach (((ACE_Future<T> &) r).future_rep_))
00290 {
00291 }

template<class T>
ACE_Future< T >::ACE_Future const T &    r
 

Constructor that initialises an ACE_Future to point to the result r immediately.

Definition at line 294 of file Future.cpp.

References ACE_DEBUG, ACE_LIB_TEXT, future_rep_, LM_DEBUG, and ACE_Future_Rep::set.

00295   : future_rep_ (FUTURE_REP::create ())
00296 {
00297   ACE_DEBUG ((LM_DEBUG,
00298               ACE_LIB_TEXT (" (%t) funny constructor\n")));
00299   this->future_rep_->set (r,
00300                           *this);
00301 }

template<class T>
ACE_Future< T >::~ACE_Future void   
 

Destructor.

Definition at line 304 of file Future.cpp.

References future_rep_.

00305 {
00306   FUTURE_REP::detach (future_rep_);
00307 }


Member Function Documentation

template<class T>
int ACE_Future< T >::attach ACE_Future_Observer< T > *    observer
 

Attaches the specified observer to a subject (this ACE_Future). The update method of the specified subject will be invoked with a copy of the associated ACE_Future as input when the result gets set. If the result is already set when this method gets invoked, then the update method of the specified subject will be invoked immediately.

Parameters:
observer  The observer to attach to the subject.
Return values:
0  Success.
1  The observer was already attached.
-1  Error; check ACE_OS::last_error() for an error code.

Definition at line 363 of file Future.cpp.

References ACE_Future_Rep::attach, and future_rep_.

00364 {
00365   return this->future_rep_->attach (observer, *this);
00366 }

template<class T>
int ACE_Future< T >::cancel void   
 

Cancel an ACE_Future. Put the future into its initial state. Returns 0 on succes and -1 on failure. It is now possible to reuse the ACE_Future. But remember, the ACE_Future is now bound to a new ACE_Future_Rep.

Definition at line 330 of file Future.cpp.

Referenced by cancel.

00331 {
00332   // If this ACE_Future is already attached to a ACE_Future_Rep,
00333   // detach it (maybe delete the ACE_Future_Rep).
00334   FUTURE_REP::assign (this->future_rep_,
00335                       FUTURE_REP::create ());
00336   return 0;
00337 }

template<class T>
int ACE_Future< T >::cancel const T &    r
 

Cancel an ACE_Future and assign the value r. It is used if a client does not want to wait for the value to be produced.

Definition at line 322 of file Future.cpp.

References cancel, future_rep_, and ACE_Future_Rep::set.

00323 {
00324   this->cancel ();
00325   return this->future_rep_->set (r,
00326                                  *this);
00327 }

template<class T>
int ACE_Future< T >::detach ACE_Future_Observer< T > *    observer
 

Detaches the specified observer from a subject (this ACE_Future). The update method of the specified subject will not be invoked when the ACE_Future_Rep result gets set.

Parameters:
observer  The observer to attach to the subject.
Return values:
0  The observer was successfully detached.
-1  Error, including the observer not attached prior to calling this method.

Definition at line 369 of file Future.cpp.

References ACE_Future_Rep::detach, and future_rep_.

00370 {
00371   return this->future_rep_->detach (observer);
00372 }

template<class T>
void ACE_Future< T >::dump void    const
 

Dump the state of an object.

Definition at line 406 of file Future.cpp.

References ACE_BEGIN_DUMP, ACE_DEBUG, ACE_END_DUMP, ACE_Future_Rep::dump, future_rep_, and LM_DEBUG.

00407 {
00408   ACE_DEBUG ((LM_DEBUG,
00409               ACE_BEGIN_DUMP, this));
00410 
00411   if (this->future_rep_)
00412     this->future_rep_->dump ();
00413 
00414   ACE_DEBUG ((LM_DEBUG,
00415               ACE_END_DUMP));
00416 }

template<class T>
int ACE_Future< T >::get T &    value,
ACE_Time_Value   tv = 0
const
 

Wait to get the object's value.

Parameters:
value  Receives the value of this ACE_Future when it is set.
tv  Pointer to an ACE_Time_Value containing the absolute time to wait until for the value to be set. If tv is 0, the call waits indefinitely for the value to be set, unless an error occurs.
Return values:
0  Success; value contains the value of the ACE_Future.
-1  Error; check ACE_OS::last_error() for an error code.

Definition at line 355 of file Future.cpp.

References future_rep_, and ACE_Future_Rep::get.

00357 {
00358   // We return the ACE_Future_rep.
00359   return this->future_rep_->get (value, tv);
00360 }

template<class T>
ACE_Future_Rep< T > * ACE_Future< T >::get_rep void   
 

Get the underlying ACE_Future_Rep pointer. Note that this method should rarely, if ever, be used and that modifying the underlying ACE_Future_Rep should be done with extreme caution.

Definition at line 419 of file Future.cpp.

References future_rep_.

Referenced by ACE_Future_Set::update.

00420 {
00421   return this->future_rep_;
00422 }

template<class T>
void ACE_Future< T >::operator &   [private]
 

Do not allow address-of operator.

Definition at line 439 of file Future.cpp.

00440 {
00441 }

template<class T>
void ACE_Future< T >::operator delete void *    [private]
 

Do not allow delete operator.

Definition at line 434 of file Future.cpp.

00435 {
00436 }

template<class T>
void * ACE_Future< T >::operator new size_t    nbytes [private]
 

Do not allow new operator.

Definition at line 425 of file Future.cpp.

References ACE_throw_bad_alloc.

00426 {
00427   ACE_throw_bad_alloc;
00428 #if defined (__HP_aCC)
00429   return 0;
00430 #endif /* 0 */
00431 }

template<class T>
ACE_Future< T >::operator T  
 

Deprecated:
Note that this method is going away in a subsequent release since it doesn't distinguish between failure results and success results (exceptions should be used, but they aren't portable...). Type conversion, which obtains the result of the asynchronous method invocation. Will block forever. The get() method should be used instead since it separates the error value from the result, and also permits timeouts.

Definition at line 375 of file Future.cpp.

References future_rep_.

00376 {
00377   // note that this will fail (and COREDUMP!)
00378   // if future_rep_ == 0 !
00379   //
00380   // but...
00381   // this is impossible unless somebody is so stupid to
00382   // try something like this:
00383   //
00384   // Future<T> futT;
00385   // T t;
00386   // t = futT;
00387 
00388   // perform type conversion on Future_Rep.
00389   return *future_rep_;
00390 }

template<class T>
int ACE_Future< T >::operator!= const ACE_Future< T > &    r const
 

Inequality operator, which is the opposite of equality.

Definition at line 316 of file Future.cpp.

References future_rep_.

00317 {
00318   return r.future_rep_ != this->future_rep_;
00319 }

template<class T>
void ACE_Future< T >::operator= const ACE_Future< T > &    r
 

Assignment operator that binds this and r to the same ACE_Future_Rep. An ACE_Future_Rep is created if necessary.

Definition at line 393 of file Future.cpp.

References future_rep_.

00394 {
00395   // assignment:
00396   //
00397   //  bind <this> to the same <ACE_Future_Rep> as <r>.
00398 
00399   // This will work if &r == this, by first increasing the ref count
00400   ACE_Future<T> &r = (ACE_Future<T> &) rhs;
00401   FUTURE_REP::assign (this->future_rep_,
00402                       FUTURE_REP::attach (r.future_rep_));
00403 }

template<class T>
int ACE_Future< T >::operator== const ACE_Future< T > &    r const
 

Equality operator that returns 1 if both ACE_Future objects point to the same ACE_Future_Rep object. Attention: It also returns 1 if both objects have just been instantiated and not used yet.

Definition at line 310 of file Future.cpp.

References future_rep_.

00311 {
00312   return r.future_rep_ == this->future_rep_;
00313 }

template<class T>
int ACE_Future< T >::ready void    const
 

Check if the result is available.

Definition at line 348 of file Future.cpp.

References future_rep_, and ACE_Future_Rep::ready.

00349 {
00350   // We're ready if the ACE_Future_rep is ready...
00351   return this->future_rep_->ready ();
00352 }

template<class T>
int ACE_Future< T >::set const T &    r
 

Make the result available. Is used by the server thread to give the result to all waiting clients. Returns 0 for success, -1 on failure. This function only has an effect the first time it is called for the object (actually, the first time the underlying ACE_Future_Rep has a value assigned to it). Subsequent calls return 0 (success) but have no effect.

Definition at line 340 of file Future.cpp.

References future_rep_, and ACE_Future_Rep::set.

00341 {
00342   // Give the pointer to the result to the ACE_Future_Rep.
00343   return this->future_rep_->set (r,
00344                                  *this);
00345 }


Member Data Documentation

template<class T>
ACE_Future::ACE_ALLOC_HOOK_DECLARE
 

Declare the dynamic allocation hooks.

Definition at line 357 of file Future.h.

template<class T>
FUTURE_REP* ACE_Future::future_rep_ [private]
 

Definition at line 372 of file Future.h.

Referenced by ACE_Future, attach, cancel, detach, dump, get, get_rep, operator T, operator!=, operator=, operator==, ready, set, and ~ACE_Future.


The documentation for this class was generated from the following files:
Generated on Mon Jun 16 12:48:10 2003 for ACE by doxygen1.2.14 written by Dimitri van Heesch, © 1997-2002