ACE/ace/Token_Collection.h

   1 // -*- C++ -*-
   2
   3 //=============================================================================
   4 /**
   5  *  @file    Token_Collection.h
   6  *
   7  *  The ACE_Token class offers methods for acquiring, renewing,
   8  *  and releasing a synchronization token on a per-token basis.  The
   9  *  ACE_Token_Collection offers an interface for performing
  10  *  operations on groups of tokens as a whole, or on a single token
  11  *  within the collection.
  12  *
  13  *  The atomic group operations are not yet implemented.
  14  *
  15  *  @author Douglas C. Schmidt (d.schmidt@vanderbilt.edu)
  16  *  @author Tim Harrison (harrison@cs.wustl.edu)
  17  */
  18 //=============================================================================
  19
  20 #ifndef ACE_TOKEN_COLLECTION_H
  21 #define ACE_TOKEN_COLLECTION_H
  22 #include /**/ "ace/pre.h"
  23
  24 #include "ace/Map_Manager.h"
  25
  26 #if !defined (ACE_LACKS_PRAGMA_ONCE)
  27 # pragma once
  28 #endif /* ACE_LACKS_PRAGMA_ONCE */
  29
  30 #if defined (ACE_HAS_TOKENS_LIBRARY)
  31
  32 #include "ace/Local_Tokens.h"
  33 #include "ace/Null_Mutex.h"
  34
  35 ACE_BEGIN_VERSIONED_NAMESPACE_DECL
  36
  37 /**
  38  * @class ACE_Token_Collection
  39  *
  40  * @brief Allows atomic token group operations AND
  41  * provides a ACE_Token manager interface.
  42  *
  43  * There are two types of operations offered by
  44  * ACE_Token_Collection.  The first is atomic operations on
  45  * collections of Token_Proxies.  In this respect, the
  46  * ACE_Token_Collection can be thought of as a single token
  47  * consisting of multiple Token_Proxies.  The second role of the
  48  * ACE_Token_Collection is as a ACE_Token manager.
  49  * ACE_Token_Collection allows individual operations on single
  50  * members of a collection of Token_Proxies.  This provides a
  51  * single access point for operations on multiple tokens.
  52  *
  53  * @bug Although ACE_Token_Collection inherits from ACE_Token_Proxy, it
  54  * can not be including in a collection.  This is because <clone>
  55  * returns zero for now.
  56  */
  57 class ACE_Export ACE_Token_Collection : public ACE_Token_Proxy
  58 {
  59 public:
  60   /**
  61    * @a debug print out verbose debugging messages. @a name will give a
  62    * name to the collection.  Collections don't really need names, but
  63    * are sometimes useful for debugging.
  64    */
  65   ACE_Token_Collection (bool debug = false,
  66                         const ACE_TCHAR *name = 0);
  67
  68 // Collection Management operations
  69
  70   /**
  71    * Insert a Token into the collection.  All ACE_Token type
  72    * operations performed on the collection will also be performed on
  73    * the new_proxy until it is removed.  Note that no operations
  74    * performed prior to the insertion will be performed.  Returns: 0
  75    * on success, -1 on failure with @c errno == problem.  If a token
  76    * proxy already exists in the collection with the same name, the
  77    * insertion will fail.  Also, <token> is copied.  Note that during
  78    * the copy, client_id's are *not* inherited.  The client ID of the
  79    * thread using the collection will be used.  Client ID's can be
  80    * changed explicity on each proxy using is_member.
  81    */
  82   int insert (ACE_Token_Proxy &token);
  83
  84   /**
  85    * Removes the ACE_Token matching the given token_name from the
  86    * collection.  On success, extract returns 0. On failure
  87    * (token_name was not in the collection,) extract returns -1.  On
  88    * success, the state of the token found is copied into proxy.
  89    * The returned ACE_Token_Proxy* must be deleted by the user.
  90    */
  91   int extract (const ACE_TCHAR *token_name, ACE_Token_Proxy *&proxy);
  92
  93   /// Returns the proxy if true.  0 otherwise.
  94   ACE_Token_Proxy *is_member (const ACE_TCHAR *token_name);
  95
  96   /**
  97    * Is the specified token in the collection?
  98    * 1, yes.
  99    * 0, no.
 100    */
 101   int is_member (const ACE_Token_Proxy &token);
 102
 103 // = Collective operation semantics.
 104
 105 //   For acquire, renew, and release, there are two interfaces.  Once
 106 //   interface allows an operation on a single token in the
 107 //   collection.  The collective interfaces perform atomic operations
 108 //   on the entire collection.  For instance, a collective acquire
 109 //   will perform an acquire for each and every token in the
 110 //   collection or the operation will fail.  Currently, these
 111 //   operations are performed with no ordering heuristics.  That is,
 112 //   the Collection steps through the tokens in the order they were
 113 //   inserted.  For each one it performs the operation (acquire,
 114 //   renew, or release).
 115
 116   /**
 117    * Acquire "atomically" all resources in the collection.  This is
 118    * only successfull if all tokens in the collection could be
 119    * acquired.  options contains the blocking semantics, timeout
 120    * value, etc.  Returns: 0 on success, -1 on failure with @c errno ==
 121    * problem.  If and error or deadlock occurs for one of the tokens,
 122    * all the tokens will be released and the method will return -1.
 123    * Note that returning on detection of deadlock prevents livelock
 124    * between competing collections.  If a collection returns after
 125    * detecting deadlock, it is the application's responsibility to not
 126    * to blindly loop on the collection::acquire operation.  In other
 127    * words, once the collection reports deadlock, it is out of our
 128    * hands.
 129    */
 130   virtual int acquire (int notify = 0,
 131                        void (*sleep_hook)(void *) = 0,
 132                        ACE_Synch_Options &options =
 133                        ACE_Synch_Options::defaults);
 134
 135   /// Acquire the token corresponding to @a token_name.  The other
 136   /// parameters are passed to <token>::acquire.
 137   virtual int acquire (const ACE_TCHAR *token_name,
 138                        int notify = 0,
 139                        void (*sleep_hook)(void *) = 0,
 140                        ACE_Synch_Options &options =
 141                        ACE_Synch_Options::defaults);
 142
 143   /// Try to acquire all tokens in collection.
 144   virtual int tryacquire (void (*sleep_hook)(void *) = 0);
 145
 146   /// Try to acquire @a token_name.
 147   virtual int tryacquire (const ACE_TCHAR *token_name,
 148                           void (*sleep_hook)(void *) = 0);
 149
 150   /**
 151    * Renews "atomically" all resources in the collection.  This is
 152    * only successfull if all tokens in the collection could be
 153    * renewed.  options contains the blocking semantics, timeout
 154    * value, etc.  Returns: 0 on success, -1 on failure with @c errno ==
 155    * problem.
 156    */
 157   virtual int renew (int requeue_position = 0,
 158                      ACE_Synch_Options &options =
 159                      ACE_Synch_Options::defaults);
 160
 161
 162   /// Renew the token corresponding to @a token_name.  The other
 163   /// parameters are passed to <token>::renew.
 164   virtual int renew (const ACE_TCHAR *token_name,
 165                      int requeue_position = 0,
 166                      ACE_Synch_Options &options =
 167                      ACE_Synch_Options::defaults);
 168
 169   /**
 170    * Releases "atomically" all resources in the collection.  This is
 171    * only successfull if all tokens in the collection could be
 172    * released.  options contains the blocking semantics, timeout
 173    * value, etc.  Returns: 0 on success, -1 on failure with @c errno ==
 174    * problem.
 175    */
 176   virtual int release (ACE_Synch_Options &options =
 177                        ACE_Synch_Options::defaults);
 178
 179
 180   /// Release the token corresponding to <token_name>.  The other
 181   /// parameters are passed to <token>::release.
 182   virtual int release (const ACE_TCHAR *token_name,
 183                        ACE_Synch_Options &options =
 184                        ACE_Synch_Options::defaults);
 185
 186   ~ACE_Token_Collection ();
 187
 188   /// Dump the state of the class.
 189   void dump () const;
 190
 191   /// Return the name of the collection.  Not very functionally
 192   /// important, but sometimes a useful debugging tool.
 193   virtual const ACE_TCHAR *name () const;
 194
 195 protected:
 196   typedef ACE_Token_Name TOKEN_NAME;
 197
 198   /// COLLECTION maintains a mapping from token names to ACE_Tokens*
 199   typedef ACE_Map_Manager<TOKEN_NAME, ACE_Token_Proxy *, ACE_Null_Mutex>
 200     COLLECTION;
 201
 202   /// COLLECTION maintains a mapping from token names to ACE_Tokens*.
 203   COLLECTION collection_;
 204
 205   /// Whether to print out debug messages or not.
 206   bool debug_;
 207
 208   /// Name of the collection.
 209   ACE_TCHAR name_[ACE_MAXTOKENNAMELEN];
 210
 211   // = I'm not sure what these mean, but they have to be defined since they're
 212   //   pure virtual in ACE_Token_Proxy.
 213   virtual ACE_Token_Proxy *clone () const;
 214   virtual ACE_Tokens *create_token (const ACE_TCHAR *name);
 215 };
 216
 217 ACE_END_VERSIONED_NAMESPACE_DECL
 218
 219 #if defined (__ACE_INLINE__)
 220 #include "ace/Token_Collection.inl"
 221 #endif /* __ACE_INLINE__ */
 222
 223 #endif /* ACE_HAS_TOKENS_LIBRARY */
 224
 225 #include /**/ "ace/post.h"
 226 #endif /* ACE_TOKEN_COLLECTION_H */