ACE/ace/Future_Set.h

   1 // -*- C++ -*-
   2
   3 //=============================================================================
   4 /**
   5  *  @file    Future_Set.h
   6  *
   7  *  @author John Tucker <jtucker@infoglide.com>
   8  */
   9 //=============================================================================
  10
  11 #ifndef ACE_FUTURE_SET_H
  12 #define ACE_FUTURE_SET_H
  13 #include /**/ "ace/pre.h"
  14
  15 #include "ace/Thread.h"
  16 #include "ace/Message_Queue.h"
  17 #include "ace/Future.h"
  18 #include "ace/Hash_Map_Manager_T.h"
  19 #include "ace/Null_Mutex.h"
  20
  21 #if !defined (ACE_LACKS_PRAGMA_ONCE)
  22 #pragma once
  23 #endif /* ACE_LACKS_PRAGMA_ONCE */
  24
  25 #if defined (ACE_HAS_THREADS)
  26
  27 ACE_BEGIN_VERSIONED_NAMESPACE_DECL
  28
  29 /**
  30  * @class ACE_Future_Set
  31  *
  32  * @brief This class implements a mechanism that allows the values of
  33  * a collection of ACE_Future objects to be accessed by reader threads
  34  * as they become available.  The caller(s) provide the ACE_Future_Set
  35  * (i.e. the observer...) with the collection of ACE_Future objects
  36  * (i.e. the subjects...) that are to be observed using the the
  37  * ACE_Future_Set::insert() method.  The caller(s) may then iterate
  38  * over the collection in the order in which they become readable
  39  * using the ACE_Future_Set::next_readable() method.
  40  */
  41 template <class T>
  42 class ACE_Future_Set : public ACE_Future_Observer<T>,
  43                        private ACE_Copy_Disabled
  44 {
  45 public:
  46   /// Constructor.
  47   ACE_Future_Set (ACE_Message_Queue<ACE_SYNCH> *future_notification_queue_ = 0);
  48
  49   /// Destructor.
  50   ~ACE_Future_Set (void);
  51
  52   /**
  53    * Return 1 if their are no ACE_Future objects left on its queue and
  54    * 0 otherwise.
  55    *
  56    * When an ACE_Future_Set has no ACE_Future>subjects to observe it is
  57    * empty. The ACE_Future_Set is in the empty state when either the caller(s)
  58    * have retrieved every readable ACE_Future subject assigned the
  59    * ACE_Future_Set via the ACE_Future_Set::next_readable() method,
  60    * or when the ACE_Future_Set has not been assigned any subjects.
  61    */
  62   int is_empty (void) const;
  63
  64   /**
  65    * Enqueus the given ACE_Future into this objects queue when it is
  66    * readable.
  67    *
  68    * Returns 0 if the future is successfully inserted, 1 if the
  69    * future is already inserted, and -1 if failures occur.
  70    */
  71   int insert (ACE_Future<T> &future);
  72
  73   /**
  74    * Wait up to @a tv time to get the @a value.  Note that @a tv must be
  75    * specified in absolute time rather than relative time.); get the
  76    * next ACE_Future that is readable.  If @a tv = 0, the will block
  77    * forever.
  78    *
  79    * If a readable future becomes available, then the input
  80    * ACE_Future object param will be assigned with it and 1 will
  81    * be returned.  If the ACE_Future_Set is empty (i.e. see definition
  82    * of ACE_Future_Set::is_empty()), then 0 is returned.
  83    *
  84    * When a readable ACE_Future object is retrieved via the
  85    * ACE_Future_Set::next_readable() method, the ACE_Future_Set will
  86    * remove that ACE_Future object from its list of subjects.
  87    */
  88   int next_readable (ACE_Future<T> &result,
  89                      ACE_Time_Value *tv = 0);
  90
  91   /// Called by the ACE_Future subject in which we are subscribed to
  92   /// when its value is written to.
  93   virtual void update (const ACE_Future<T> &future);
  94
  95   /// Declare the dynamic allocation hooks.
  96   ACE_ALLOC_HOOK_DECLARE;
  97
  98 private:
  99   typedef ACE_Future<T> FUTURE;
 100
 101   typedef ACE_Future_Rep<T> FUTURE_REP;
 102
 103   typedef ACE_Future_Holder<T> FUTURE_HOLDER;
 104
 105   typedef ACE_Pointer_Hash<FUTURE_REP *> FUTURE_REP_HASH;
 106
 107   typedef ACE_Equal_To<FUTURE_REP *> FUTURE_REP_COMPARE;
 108
 109   typedef ACE_Hash_Map_Manager_Ex<FUTURE_REP *,
 110                                   FUTURE_HOLDER *,
 111                                   FUTURE_REP_HASH,
 112                                   FUTURE_REP_COMPARE,
 113                                   ACE_Null_Mutex> FUTURE_HASH_MAP;
 114
 115   /// Map of <ACE_Futures>, subjects, which have not been written to by
 116   /// client's writer thread.
 117   FUTURE_HASH_MAP future_map_;
 118
 119   /// Message queue for notifying the reader thread of <ACE_Futures> which
 120   /// have been written to by client's writer thread.
 121   ACE_Message_Queue<ACE_SYNCH> *future_notification_queue_;
 122
 123   /// Keeps track of whether we need to delete the message queue.
 124   bool delete_queue_;
 125 };
 126
 127 ACE_END_VERSIONED_NAMESPACE_DECL
 128
 129 #if defined (ACE_TEMPLATES_REQUIRE_SOURCE)
 130 #include "ace/Future_Set.cpp"
 131 #endif /* ACE_TEMPLATES_REQUIRE_SOURCE */
 132
 133 #if defined (ACE_TEMPLATES_REQUIRE_PRAGMA)
 134 #pragma implementation ("Future_Set.cpp")
 135 #endif /* ACE_TEMPLATES_REQUIRE_PRAGMA */
 136
 137 #endif /* ACE_HAS_THREADS */
 138 #include /**/ "ace/post.h"
 139 #endif /* ACE_FUTURE_SET_H */