diff options
author | coryan <coryan@ae88bc3d-4319-0410-8dbf-d08b4c9d3795> | 2000-11-01 22:17:39 +0000 |
---|---|---|
committer | coryan <coryan@ae88bc3d-4319-0410-8dbf-d08b4c9d3795> | 2000-11-01 22:17:39 +0000 |
commit | 53284e215e3d3351a7d7e9c4b68f14b427fb4377 (patch) | |
tree | 97236ece363cff48fd287c780db4290da39b02cb /ace/Future.h | |
parent | 7b7c52ad2abd228138ba1a948d5e28bf6dc3b880 (diff) | |
download | ATCD-53284e215e3d3351a7d7e9c4b68f14b427fb4377.tar.gz |
ChangeLogTag:Wed Nov 1 14:11:48 2000 Carlos O'Ryan <coryan@uci.edu>
Diffstat (limited to 'ace/Future.h')
-rw-r--r-- | ace/Future.h | 344 |
1 files changed, 189 insertions, 155 deletions
diff --git a/ace/Future.h b/ace/Future.h index 9aaf6362c66..0faf9578d61 100644 --- a/ace/Future.h +++ b/ace/Future.h @@ -1,21 +1,18 @@ /* -*- C++ -*- */ -// $Id$ - -// ============================================================================ -// -// = LIBRARY -// ace -// -// = FILENAME -// Future.h -// -// = AUTHOR (S) -// Andres Kruse <Andres.Kruse@cern.ch>, -// Douglas C. Schmidt <schmidt@cs.wustl.edu>, -// Per Andersson <Per.Andersson@hfera.ericsson.se>, and -// John Tucker <jtucker@infoglide.com> -// -// ============================================================================ + +//============================================================================= +/** + * @file Future.h + * + * $Id$ + * + * @author Andres Kruse <Andres.Kruse@cern.ch> + * @author Douglas C. Schmidt <schmidt@cs.wustl.edu> + * @author Per Andersson <Per.Andersson@hfera.ericsson.se> + * @author and John Tucker <jtucker@infoglide.com> + */ +//============================================================================= + #ifndef ACE_FUTURE_H #define ACE_FUTURE_H @@ -37,17 +34,20 @@ template <class T> class ACE_Future_Observer; template <class T> class ACE_Future_Rep; template <class T> class ACE_Future; +/** + * @class ACE_Future_Holder + * + * @brief Implementation of object which has holds ACE_Future. + */ template <class T> class ACE_Export ACE_Future_Holder { - // = TITLE - // Implementation of object which has holds ACE_Future. public: ACE_Future_Holder (const ACE_Future<T> &future); ~ACE_Future_Holder (void); + /// Declare the dynamic allocation hooks. ACE_ALLOC_HOOK_DECLARE; - // Declare the dynamic allocation hooks. ACE_Future<T> item_; @@ -55,133 +55,150 @@ protected: ACE_Future_Holder (void); }; +/** + * @class ACE_Future_Observer + * + * @brief ACE_Future_Observer<T> + * + * An ACE_Future_Observer object implements an object that is + * subscribed with an ACE_Future object so that it may be + * notified when the value of the ACE_Future object is + * written to by a writer thread. + * It uses the Observer pattern + */ template <class T> class ACE_Future_Observer { - // = TITLE - // ACE_Future_Observer<T> - // - // = DESCRIPTION - // An ACE_Future_Observer object implements an object that is - // subscribed with an ACE_Future object so that it may be - // notified when the value of the ACE_Future object is - // written to by a writer thread. - // - // It uses the Observer pattern public: // = Destructor virtual ~ACE_Future_Observer (void); + /// Called by the ACE_Future in which we are subscribed to when + /// its value is written to. virtual void update (const ACE_Future<T> &future) = 0; - // Called by the ACE_Future in which we are subscribed to when - // its value is written to. + /// Declare the dynamic allocation hooks. ACE_ALLOC_HOOK_DECLARE; - // Declare the dynamic allocation hooks. protected: // = Constructor ACE_Future_Observer (void); }; +/** + * @class ACE_Future_Rep + * + * @brief ACE_Future_Rep<T> + * + * An ACE_Future_Rep<T> object encapsules a pointer to an object + * of class T which is the result of an asynchronous method + * invocation. It is pointed to by ACE_Future<T> object[s] and + * only accessible through them. + */ template <class T> class ACE_Future_Rep { - // = TITLE - // ACE_Future_Rep<T> - // - // = DESCRIPTION - // An ACE_Future_Rep<T> object encapsules a pointer to an object - // of class T which is the result of an asynchronous method - // invocation. It is pointed to by ACE_Future<T> object[s] and - // only accessible through them. private: friend class ACE_Future<T>; + /** + * Set the result value. The specified <caller> represents the + * future that invoked this <set> method, which is used to notify + * the list of future observers. Returns 0 for success, -1 on error. + * This function only has an effect the first time it is called for + * the object. Subsequent calls return 0 (success) but have no effect. + */ int set (const T &r, ACE_Future<T> &caller); - // Set the result value. The specified <caller> represents the - // future that invoked this <set> method, which is used to notify - // the list of future observers. Returns 0 for success, -1 on error. - // This function only has an effect the first time it is called for - // the object. Subsequent calls return 0 (success) but have no effect. + /// Wait up to <tv> time to get the <value>. Note that <tv> must be + /// specified in absolute time rather than relative time. int get (T &value, ACE_Time_Value *tv); - // Wait up to <tv> time to get the <value>. Note that <tv> must be - // specified in absolute time rather than relative time. + /** + * Attaches the specified observer to a subject (i.e. the + * <ACE_Future_Rep>). The update method of the specified subject will + * be invoked with a copy of the written-to <ACE_Future> as input when + * the result gets set. + * + * Returns 0 if the observer is successfully attached, 1 if the + * observer is already attached, and -1 if failures occur. + */ int attach (ACE_Future_Observer<T> *observer, ACE_Future<T> &caller); - // Attaches the specified observer to a subject (i.e. the - // <ACE_Future_Rep>). The update method of the specified subject will - // be invoked with a copy of the written-to <ACE_Future> as input when - // the result gets set. - // - // Returns 0 if the observer is successfully attached, 1 if the - // observer is already attached, and -1 if failures occur. + /** + * Detaches the specified observer from a subject (i.e. the + * <ACE_Future_Rep>). The update method of the specified subject will + * not be invoked when the <ACE_Future_Rep>s result gets set. Returns + * 1 if the specified observer was actually attached to the subject + * prior to this call and 0 if was not. + * + * Returns 0 if the observer was successfully detached, and -1 if the + * observer was not attached in the first place. + */ int detach (ACE_Future_Observer<T> *observer); - // Detaches the specified observer from a subject (i.e. the - // <ACE_Future_Rep>). The update method of the specified subject will - // not be invoked when the <ACE_Future_Rep>s result gets set. Returns - // 1 if the specified observer was actually attached to the subject - // prior to this call and 0 if was not. - // - // Returns 0 if the observer was successfully detached, and -1 if the - // observer was not attached in the first place. + /** + * Type conversion. will block forever until the result is + * available. 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...). The <get> method should be used instead since it + * separates the error value from the result, and also permits + * timeouts. + */ operator T (); - // Type conversion. will block forever until the result is - // available. 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...). The <get> method should be used instead since it - // separates the error value from the result, and also permits - // timeouts. + /// Dump the state of an object. void dump (void) const; - // Dump the state of an object. + /// Declare the dynamic allocation hooks. ACE_ALLOC_HOOK_DECLARE; - // Declare the dynamic allocation hooks. // = Encapsulate reference count and object lifetime of instances. // These methods must go after the others to work around a bug with // Borland's C++ Builder... + /// Create a ACE_Future_Rep<T> and initialize the reference count. static ACE_Future_Rep<T> *create (void); - // Create a ACE_Future_Rep<T> and initialize the reference count. + /** + * Increase the reference count and return argument. Uses the + * attribute "value_ready_mutex_" to synchronize reference count + * updating. + * + * Precondition (rep != 0). + */ static ACE_Future_Rep<T> *attach (ACE_Future_Rep<T> *&rep); - // Increase the reference count and return argument. Uses the - // attribute "value_ready_mutex_" to synchronize reference count - // updating. - // - // Precondition (rep != 0). + /** + * Decreases the reference count and and deletes rep if there are no + * more references to rep. + * + * Precondition (rep != 0) + */ static void detach (ACE_Future_Rep<T> *&rep); - // Decreases the reference count and and deletes rep if there are no - // more references to rep. - // - // Precondition (rep != 0) + /** + * Decreases the rep's reference count and and deletes rep if there + * are no more references to rep. Then assigns new_rep to rep. + * + * Precondition (rep != 0 && new_rep != 0) + */ static void assign (ACE_Future_Rep<T> *&rep, ACE_Future_Rep<T> *new_rep); - // Decreases the rep's reference count and and deletes rep if there - // are no more references to rep. Then assigns new_rep to rep. - // - // Precondition (rep != 0 && new_rep != 0) + /// Is result available? int ready (void); - // Is result available? + /// Pointer to the result. T *value_; - // Pointer to the result. + /// Reference count. int ref_count_; - // Reference count. typedef ACE_Future_Observer<T> OBSERVER; @@ -189,8 +206,8 @@ private: typedef ACE_Unbounded_Set<OBSERVER *> OBSERVER_COLLECTION; + /// Keep a list of ACE_Future_Observers unread by client's reader thread. OBSERVER_COLLECTION observer_collection_; - // Keep a list of ACE_Future_Observers unread by client's reader thread. // = Condition variable and mutex that protect the <value_>. ACE_Condition_Thread_Mutex value_ready_; @@ -202,123 +219,140 @@ private: ~ACE_Future_Rep (void); }; +/** + * @class ACE_Future + * + * @brief This class implements a ``single write, multiple read'' + * pattern that can be used to return results from asynchronous + * method invocations. + */ template <class T> class ACE_Future { - // = TITLE - // This class implements a ``single write, multiple read'' - // pattern that can be used to return results from asynchronous - // method invocations. public: // = Initialization and termination methods. + /// Constructor. ACE_Future (void); - // Constructor. + /// Copy constructor binds <this> and <r> to the same + /// <ACE_Future_Rep>. An <ACE_Future_Rep> is created if necessary. 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. + /// Constructor that initialises an <ACE_Future> to point to the + /// result <r> immediately. ACE_Future (const T &r); - // Constructor that initialises an <ACE_Future> to point to the - // result <r> immediately. + /// Destructor. ~ACE_Future (void); - // Destructor. + /// Assignment operator that binds <this> and <r> to the same + /// <ACE_Future_Rep>. An <ACE_Future_Rep> is created if necessary. 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. + /// Cancel an <ACE_Future> and assign the value <r>. It is used if a + /// client does not want to wait for <T> to be produced. 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 <T> to be produced. + /** + * 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<T>. But remember, the ACE_Future<T> + * is now bound to a new ACE_Future_Rep<T>. + */ int 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<T>. But remember, the ACE_Future<T> - // is now bound to a new ACE_Future_Rep<T>. + /** + * Equality operator that returns 1 if both ACE_Future<T> objects + * point to the same ACE_Future_Rep<T> object. Attention: It also + * returns 1 if both objects have just been instantiated and not + * used yet. + */ int operator == (const ACE_Future<T> &r) const; - // Equality operator that returns 1 if both ACE_Future<T> objects - // point to the same ACE_Future_Rep<T> object. Attention: It also - // returns 1 if both objects have just been instantiated and not - // used yet. + /// Inequality operator, which is the opposite of equality. int operator != (const ACE_Future<T> &r) const; - // Inequality operator, which is the opposite of equality. + /** + * 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. + */ int 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. + /// Wait up to <tv> time to get the <value>. Note that <tv> must be + /// specified in absolute time rather than relative time. int get (T &value, ACE_Time_Value *tv = 0); - // Wait up to <tv> time to get the <value>. Note that <tv> must be - // specified in absolute time rather than relative time. + /** + * Type conversion, which obtains the result of the asynchronous + * method invocation. Will block forever. 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...). The <get> method should be + * used instead since it separates the error value from the result, + * and also permits timeouts. + */ operator T (); - // Type conversion, which obtains the result of the asynchronous - // method invocation. Will block forever. 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...). The <get> method should be - // used instead since it separates the error value from the result, - // and also permits timeouts. + /// Check if the result is available. int ready (void); - // Check if the result is available. + /** + * Attaches the specified observer to a subject (i.e. the + * <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. + * + * Returns 0 if the observer is successfully attached, 1 if the + * observer is already attached, and -1 if failures occur. + */ int attach (ACE_Future_Observer<T> *observer); - // Attaches the specified observer to a subject (i.e. the - // <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. - // - // Returns 0 if the observer is successfully attached, 1 if the - // observer is already attached, and -1 if failures occur. + /** + * Detaches the specified observer from a subject (i.e. the + * <ACE_Future_Rep>). The update method of the specified subject will + * not be invoked when the <ACE_Future_Reps> result gets set. Returns + * 1 if the specified observer was actually attached to the subject + * prior to this call and 0 if was not. + * + * Returns 0 if the observer was successfully detached, and -1 if the + * observer was not attached in the first place. + */ int detach (ACE_Future_Observer<T> *observer); - // Detaches the specified observer from a subject (i.e. the - // <ACE_Future_Rep>). The update method of the specified subject will - // not be invoked when the <ACE_Future_Reps> result gets set. Returns - // 1 if the specified observer was actually attached to the subject - // prior to this call and 0 if was not. - // - // Returns 0 if the observer was successfully detached, and -1 if the - // observer was not attached in the first place. + /// Dump the state of an object. void dump (void) const; - // Dump the state of an object. + /** + * Get the underlying <ACE_Future_Rep>*. Note that this method should + * rarely, if ever, be used and that modifying the undlerlying <ACE_Future_Rep>* + * should be done with extreme caution. + */ ACE_Future_Rep<T> *get_rep (void); - // Get the underlying <ACE_Future_Rep>*. Note that this method should - // rarely, if ever, be used and that modifying the undlerlying <ACE_Future_Rep>* - // should be done with extreme caution. + /// Declare the dynamic allocation hooks. ACE_ALLOC_HOOK_DECLARE; - // Declare the dynamic allocation hooks. private: + /// Do not allow new operator. void *operator new (size_t nbytes); - // Do not allow new operator. + /// Do not allow delete operator void operator delete (void *); - // Do not allow delete operator + /// Do not allow address-of operator. void operator & (); - // Do not allow address-of operator. // the ACE_Future_Rep + /// Protect operations on the <Future>. typedef ACE_Future_Rep<T> FUTURE_REP; FUTURE_REP *future_rep_; - // Protect operations on the <Future>. }; #if defined (ACE_TEMPLATES_REQUIRE_SOURCE) |