00001 // -*- C++ -*- 00002 00003 //============================================================================= 00004 /** 00005 * @file Future.h 00006 * 00007 * $Id: Future.h 77114 2007-02-14 08:55:20Z johnnyw $ 00008 * 00009 * @author Andres Kruse <Andres.Kruse@cern.ch> 00010 * @author Douglas C. Schmidt <schmidt@cs.wustl.edu> 00011 * @author Per Andersson <Per.Andersson@hfera.ericsson.se> and 00012 * @author John Tucker <johnny_tucker@yahoo.com> 00013 */ 00014 //============================================================================= 00015 00016 #ifndef ACE_FUTURE_H 00017 #define ACE_FUTURE_H 00018 00019 #include /**/ "ace/pre.h" 00020 00021 #include "ace/Unbounded_Set.h" 00022 #include "ace/Strategies_T.h" 00023 00024 #if !defined (ACE_LACKS_PRAGMA_ONCE) 00025 # pragma once 00026 #endif /* ACE_LACKS_PRAGMA_ONCE */ 00027 00028 #if defined (ACE_HAS_THREADS) 00029 00030 #include "ace/Recursive_Thread_Mutex.h" 00031 #include "ace/Condition_Recursive_Thread_Mutex.h" 00032 00033 ACE_BEGIN_VERSIONED_NAMESPACE_DECL 00034 00035 // Forward decl. 00036 template <class T> class ACE_Future_Holder; 00037 template <class T> class ACE_Future_Observer; 00038 template <class T> class ACE_Future_Rep; 00039 template <class T> class ACE_Future; 00040 00041 /** 00042 * @class ACE_Future_Holder 00043 * 00044 * @brief Implementation of object that holds an ACE_Future. 00045 */ 00046 template <class T> 00047 class ACE_Future_Holder 00048 { 00049 public: 00050 ACE_Future_Holder (const ACE_Future<T> &future); 00051 ~ACE_Future_Holder (void); 00052 00053 /// Declare the dynamic allocation hooks. 00054 ACE_ALLOC_HOOK_DECLARE; 00055 00056 ACE_Future<T> item_; 00057 00058 protected: 00059 ACE_Future_Holder (void); 00060 }; 00061 00062 /** 00063 * @class ACE_Future_Observer 00064 * 00065 * @brief ACE_Future_Observer<T> 00066 * 00067 * An ACE_Future_Observer object implements an object that is 00068 * subscribed with an ACE_Future object so that it may be notified 00069 * when the value of the ACE_Future object is written to by a writer 00070 * thread. It uses the Observer pattern. 00071 */ 00072 template <class T> 00073 class ACE_Future_Observer 00074 { 00075 public: 00076 /// Destructor 00077 virtual ~ACE_Future_Observer (void); 00078 00079 /// Called by the ACE_Future in which we are subscribed to when 00080 /// its value is written to. 00081 virtual void update (const ACE_Future<T> &future) = 0; 00082 00083 /// Declare the dynamic allocation hooks. 00084 ACE_ALLOC_HOOK_DECLARE; 00085 protected: 00086 00087 /// Constructor 00088 ACE_Future_Observer (void); 00089 }; 00090 00091 /** 00092 * @class ACE_Future_Rep 00093 * 00094 * @internal 00095 * 00096 * @brief ACE_Future_Rep<T> 00097 * 00098 * An ACE_Future_Rep<T> object encapsules a pointer to an object 00099 * of class T which is the result of an asynchronous method 00100 * invocation. It is pointed to by ACE_Future<T> object[s] and 00101 * only accessible through them. 00102 */ 00103 template <class T> 00104 class ACE_Future_Rep 00105 { 00106 private: 00107 friend class ACE_Future<T>; 00108 00109 /** 00110 * Set the result value. The specified <caller> represents the 00111 * future that invoked this <set> method, which is used to notify 00112 * the list of future observers. Returns 0 for success, -1 on error. 00113 * This function only has an effect the first time it is called for 00114 * the object. Subsequent calls return 0 (success) but have no effect. 00115 */ 00116 int set (const T &r, 00117 ACE_Future<T> &caller); 00118 00119 /// Wait up to @a tv time to get the @a value. Note that @a tv must be 00120 /// specified in absolute time rather than relative time. 00121 int get (T &value, 00122 ACE_Time_Value *tv) const; 00123 00124 /** 00125 * Attaches the specified observer to a subject (i.e., the <ACE_Future_Rep>). 00126 * The update method of the specified subject will be invoked with a copy of 00127 * the written-to ACE_Future as input when the result gets set. 00128 * 00129 * Returns 0 if the observer is successfully attached, 1 if the 00130 * observer is already attached, and -1 if failures occur. 00131 */ 00132 int attach (ACE_Future_Observer<T> *observer, 00133 ACE_Future<T> &caller); 00134 00135 /** 00136 * Detaches the specified observer from a subject (i.e., the <ACE_Future_Rep>). 00137 * The update method of the specified subject will not be invoked when the 00138 * <ACE_Future_Rep>s result gets set. Returns 1 if the specified observer was 00139 * actually attached to the subject prior to this call and 0 if was not. 00140 * 00141 * Returns 0 if the observer was successfully detached, and -1 if the 00142 * observer was not attached in the first place. 00143 */ 00144 int detach (ACE_Future_Observer<T> *observer); 00145 00146 /** 00147 * Type conversion. will block forever until the result is 00148 * available. Note that this method is going away in a subsequent 00149 * release since it doesn't distinguish between failure results and 00150 * success results (exceptions should be used, but they aren't 00151 * portable...). The <get> method should be used instead since it 00152 * separates the error value from the result, and also permits 00153 * timeouts. 00154 */ 00155 operator T (); 00156 00157 /// Dump the state of an object. 00158 void dump (void) const; 00159 00160 /// Declare the dynamic allocation hooks. 00161 ACE_ALLOC_HOOK_DECLARE; 00162 00163 // = Encapsulate reference count and object lifetime of instances. 00164 00165 // These methods must go after the others to work around a bug with 00166 // Borland's C++ Builder... 00167 00168 /// Allocate a new ACE_Future_Rep<T> instance, returning NULL if it 00169 /// cannot be created. 00170 static ACE_Future_Rep<T> *internal_create (void); 00171 00172 /// Create a ACE_Future_Rep<T> and initialize the reference count. 00173 static ACE_Future_Rep<T> *create (void); 00174 00175 /** 00176 * Increase the reference count and return argument. Uses the 00177 * attribute "value_ready_mutex_" to synchronize reference count 00178 * updating. 00179 * 00180 * Precondition (rep != 0). 00181 */ 00182 static ACE_Future_Rep<T> *attach (ACE_Future_Rep<T> *&rep); 00183 00184 /** 00185 * Decreases the reference count and deletes rep if there are no 00186 * more references to rep. 00187 * 00188 * Precondition (rep != 0) 00189 */ 00190 static void detach (ACE_Future_Rep<T> *&rep); 00191 00192 /** 00193 * Decreases the rep's reference count and deletes rep if there 00194 * are no more references to rep. Then assigns new_rep to rep. 00195 * 00196 * Precondition (rep != 0 && new_rep != 0) 00197 */ 00198 static void assign (ACE_Future_Rep<T> *&rep, 00199 ACE_Future_Rep<T> *new_rep); 00200 00201 /// Is result available? 00202 int ready (void) const; 00203 00204 /// Pointer to the result. 00205 T *value_; 00206 00207 /// Reference count. 00208 int ref_count_; 00209 00210 typedef ACE_Future_Observer<T> 00211 OBSERVER; 00212 00213 typedef ACE_Unbounded_Set<OBSERVER *> 00214 OBSERVER_COLLECTION; 00215 00216 /// Keep a list of ACE_Future_Observers unread by client's reader thread. 00217 OBSERVER_COLLECTION observer_collection_; 00218 00219 // = Condition variable and mutex that protect the <value_>. 00220 mutable ACE_Recursive_Thread_Mutex value_ready_mutex_; 00221 mutable ACE_Condition_Recursive_Thread_Mutex value_ready_; 00222 00223 private: 00224 00225 ACE_Future_Rep (void); 00226 00227 protected: 00228 00229 ~ACE_Future_Rep (void); 00230 00231 }; 00232 00233 /** 00234 * @class ACE_Future 00235 * 00236 * @brief This class implements a ``single write, multiple read'' 00237 * pattern that can be used to return results from asynchronous 00238 * method invocations. 00239 */ 00240 template <class T> 00241 class ACE_Future 00242 { 00243 public: 00244 // = Initialization and termination methods. 00245 /// Constructor. 00246 ACE_Future (void); 00247 00248 /// Copy constructor binds @a this and @a r to the same 00249 /// ACE_Future_Rep. An ACE_Future_Rep is created if necessary. 00250 ACE_Future (const ACE_Future<T> &r); 00251 00252 /// Constructor that initialises an ACE_Future to point to the 00253 /// result @a r immediately. 00254 ACE_Future (const T &r); 00255 00256 /// Destructor. 00257 ~ACE_Future (void); 00258 00259 /// Assignment operator that binds @a this and @a r to the same 00260 /// ACE_Future_Rep. An ACE_Future_Rep is created if necessary. 00261 void operator = (const ACE_Future<T> &r); 00262 00263 /// Cancel an ACE_Future and assign the value @a r. It is used if a 00264 /// client does not want to wait for the value to be produced. 00265 int cancel (const T &r); 00266 00267 /** 00268 * Cancel an ACE_Future. Put the future into its initial 00269 * state. Returns 0 on succes and -1 on failure. It is now possible 00270 * to reuse the ACE_Future. But remember, the ACE_Future 00271 * is now bound to a new ACE_Future_Rep. 00272 */ 00273 int cancel (void); 00274 00275 /** 00276 * Equality operator that returns @c true if both ACE_Future objects 00277 * point to the same ACE_Future_Rep object. 00278 * 00279 * @note It also returns @c true if both objects have just been 00280 * instantiated and not used yet. 00281 */ 00282 bool operator == (const ACE_Future<T> &r) const; 00283 00284 /// Inequality operator, which is the opposite of equality. 00285 bool operator != (const ACE_Future<T> &r) const; 00286 00287 /** 00288 * Make the result available. Is used by the server thread to give 00289 * the result to all waiting clients. Returns 0 for success, -1 on failure. 00290 * This function only has an effect the first time it is called for 00291 * the object (actually, the first time the underlying ACE_Future_Rep has a 00292 * value assigned to it). Subsequent calls return 0 (success) but have no 00293 * effect. 00294 */ 00295 int set (const T &r); 00296 00297 /** 00298 * Wait to get the object's value. 00299 * 00300 * @param value Receives the value of this ACE_Future when it is set. 00301 * @param tv Pointer to an ACE_Time_Value containing the absolute 00302 * time to wait until for the value to be set. If @a tv 00303 * is 0, the call waits indefinitely for the value to be 00304 * set, unless an error occurs. 00305 * 00306 * @retval 0 Success; @a value contains the value of the ACE_Future. 00307 * @retval -1 Error; check ACE_OS::last_error() for an error code. 00308 */ 00309 int get (T &value, 00310 ACE_Time_Value *tv = 0) const; 00311 00312 /** 00313 * @deprecated Note that this method is going away in a subsequent 00314 * release since it doesn't distinguish between failure 00315 * results and success results (exceptions should be 00316 * used, but they aren't portable...). 00317 * Type conversion, which obtains the result of the asynchronous 00318 * method invocation. Will block forever. The get() method should be 00319 * used instead since it separates the error value from the result, 00320 * and also permits timeouts. 00321 */ 00322 operator T (); 00323 00324 /// Check if the result is available. 00325 int ready (void) const; 00326 00327 /** 00328 * Attaches the specified observer to a subject (this ACE_Future). 00329 * The update method of the specified subject will be invoked with a copy of 00330 * the associated ACE_Future as input when the result gets set. If the 00331 * result is already set when this method gets invoked, then the update 00332 * method of the specified subject will be invoked immediately. 00333 * 00334 * @param observer The observer to attach to the subject. 00335 * 00336 * @retval 0 Success. 00337 * @retval 1 The observer was already attached. 00338 * @retval -1 Error; check ACE_OS::last_error() for an error code. 00339 */ 00340 int attach (ACE_Future_Observer<T> *observer); 00341 00342 /** 00343 * Detaches the specified observer from a subject (this ACE_Future). 00344 * The update method of the specified subject will not be invoked when the 00345 * ACE_Future_Rep result gets set. 00346 * 00347 * @param observer The observer to attach to the subject. 00348 * 00349 * @retval 0 The observer was successfully detached. 00350 * @retval -1 Error, including the observer not attached prior 00351 * to calling this method. 00352 */ 00353 int detach (ACE_Future_Observer<T> *observer); 00354 00355 /// Dump the state of an object. 00356 void dump (void) const; 00357 00358 /** 00359 * Get the underlying ACE_Future_Rep pointer. Note that this method should 00360 * rarely, if ever, be used and that modifying the underlying 00361 * ACE_Future_Rep should be done with extreme caution. 00362 */ 00363 ACE_Future_Rep<T> *get_rep (void); 00364 00365 /// Declare the dynamic allocation hooks. 00366 ACE_ALLOC_HOOK_DECLARE; 00367 00368 private: 00369 00370 // the ACE_Future_Rep 00371 /// Protect operations on the <Future>. 00372 typedef ACE_Future_Rep<T> FUTURE_REP; 00373 FUTURE_REP *future_rep_; 00374 }; 00375 00376 ACE_END_VERSIONED_NAMESPACE_DECL 00377 00378 #if defined (ACE_TEMPLATES_REQUIRE_SOURCE) 00379 #include "ace/Future.cpp" 00380 #endif /* ACE_TEMPLATES_REQUIRE_SOURCE */ 00381 00382 #if defined (ACE_TEMPLATES_REQUIRE_PRAGMA) 00383 #pragma implementation ("Future.cpp") 00384 #endif /* ACE_TEMPLATES_REQUIRE_PRAGMA */ 00385 00386 #endif /* ACE_HAS_THREADS */ 00387 00388 #include /**/ "ace/post.h" 00389 00390 #endif /* ACE_FUTURE_H */