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

Token_Collection.h

Go to the documentation of this file.
00001 /* -*- C++ -*- */
00002 
00003 //=============================================================================
00004 /**
00005  *  @file    Token_Collection.h
00006  *
00007  *  $Id: Token_Collection.h,v 1.1.1.3 2001/12/04 14:33:11 chad Exp $
00008  *
00009  *  The ACE_Token class offers methods for acquiring, renewing,
00010  *  and releasing a synchronization token on a per-token basis.  The
00011  *  ACE_Token_Collection offers an interface for performing
00012  *  operations on groups of tokens as a whole, or on a single token
00013  *  within the collection.
00014  *
00015  *  The atomic group operations are not yet implemented.
00016  *
00017  *
00018  *  @author Douglas C. Schmidt (schmidt@cs.wustl.edu)
00019  *  @author Tim Harrison (harrison@cs.wustl.edu)
00020  */
00021 //=============================================================================
00022 
00023 #ifndef ACE_TOKEN_COLLECTION_H
00024 #define ACE_TOKEN_COLLECTION_H
00025 #include "ace/pre.h"
00026 
00027 #include "ace/Map_Manager.h"
00028 
00029 #if !defined (ACE_LACKS_PRAGMA_ONCE)
00030 # pragma once
00031 #endif /* ACE_LACKS_PRAGMA_ONCE */
00032 
00033 #include "ace/Local_Tokens.h"
00034 #include "ace/SString.h"
00035 
00036 #if defined (ACE_HAS_TOKENS_LIBRARY)
00037 
00038 /**
00039  * @class ACE_Token_Collection
00040  *
00041  * @brief Allows atomic token group operations AND
00042  * provides a ACE_Token manager interface.
00043  *
00044  * There are two types of operations offered by
00045  * ACE_Token_Collection.  The first is atomic operations on
00046  * collections of Token_Proxies.  In this respect, the
00047  * ACE_Token_Collection can be thought of as a single token
00048  * consisting of multiple Token_Proxies.  The second role of the
00049  * ACE_Token_Collection is as a ACE_Token manager.
00050  * ACE_Token_Collection allows individual operations on single
00051  * members of a collection of Token_Proxies.  This provides a
00052  * single access point for operations on multiple tokens.
00053  */
00054 class ACE_Export ACE_Token_Collection : public ACE_Token_Proxy
00055 {
00056 
00057   // = BUGS
00058   //   Although ACE_Token_Collection inherits from ACE_Token_Proxy, it
00059   //   can not be including in a collection.  This is because <clone>
00060   //   returns zero for now.
00061 public:
00062   /**
00063    * <debug> print out verbose debugging messages. <name> will give a
00064    * name to the collection.  Collections don't really need names, but
00065    * are sometimes useful for debugging.
00066    */
00067   ACE_Token_Collection (int debug = 0,
00068                         const ACE_TCHAR *name = 0);
00069 
00070 // Collection Management operations
00071 
00072   int insert (ACE_Token_Proxy &token);
00073 
00074   // Insert a Token into the collection.  All ACE_Token type
00075   // operations performed on the collection will also be performed on
00076   // the new_proxy until it is removed.  Note that no operations
00077   // performed prior to the insertion will be performed.  Returns: 0
00078   // on success, -1 on failure with <errno> == problem.  If a token
00079   // proxy already exists in the collection with the same name, the
00080   // insertion will fail.  Also, <token> is copied.  Note that during
00081   // the copy, client_id's are *not* inherited.  The client ID of the
00082   // thread using the collection will be used.  Client ID's can be
00083   // changed explicity on each proxy using is_member.
00084 
00085   /**
00086    * removes the ACE_Token matching the given token_name from the
00087    * collection.  On success, extract returns 0. On failure
00088    * (token_name was not in the collection,) extract returns -1.  On
00089    * success, the state of the token found is copied into proxy.
00090    * The returned ACE_Token_Proxy* must be deleted by the user.
00091    */
00092   int extract (const ACE_TCHAR *token_name, ACE_Token_Proxy *&proxy);
00093 
00094   /// returns the proxy if true.  0 otherwise.
00095   ACE_Token_Proxy *is_member (const ACE_TCHAR *token_name);
00096 
00097   /**
00098    * Is the specified token in the collection?
00099    * 1, yes.
00100    * 0, no.
00101    */
00102   int is_member (const ACE_Token_Proxy &token);
00103 
00104 // = Collective operation semantics.
00105 
00106 //   For acquire, renew, and release, there are two interfaces.  Once
00107 //   interface allows an operation on a single token in the
00108 //   collection.  The collective interfaces perform atomic operations
00109 //   on the entire collection.  For instance, a collective acquire
00110 //   will perform an acquire for each and every token in the
00111 //   collection or the operation will fail.  Currently, these
00112 //   operations are performed with no ordering heuristics.  That is,
00113 //   the Collection steps through the tokens in the order they were
00114 //   inserted.  For each one it performs the operation (acquire,
00115 //   renew, or release).
00116 
00117   /**
00118    * Acquire "atomically" all resources in the collection.  This is
00119    * only successfull if all tokens in the collection could be
00120    * acquired.  options contains the blocking semantics, timeout
00121    * value, etc.  Returns: 0 on success, -1 on failure with <errno> ==
00122    * problem.  If and error or deadlock occurs for one of the tokens,
00123    * all the tokens will be released and the method will return -1.
00124    * Note that returning on detection of deadlock prevents livelock
00125    * between competing collections.  If a collection returns after
00126    * detecting deadlock, it is the application's responsibility to not
00127    * to blindly loop on the collection::acquire operation.  In other
00128    * words, once the collection reports deadlock, it is out of our
00129    * hands.
00130    */
00131   virtual int acquire (int notify = 0,
00132                        void (*sleep_hook)(void *) = 0,
00133                        ACE_Synch_Options &options =
00134                        ACE_Synch_Options::defaults);
00135 
00136   /// Acquire the token corresponding to <token_name>.  The other
00137   /// parameters are passed to <token>::acquire.
00138   virtual int acquire (const ACE_TCHAR *token_name,
00139                        int notify = 0,
00140                        void (*sleep_hook)(void *) = 0,
00141                        ACE_Synch_Options &options =
00142                        ACE_Synch_Options::defaults);
00143 
00144   /// Try to acquire all tokens in collection.
00145   virtual int tryacquire (void (*sleep_hook)(void *) = 0);
00146 
00147   /// Try to acquire <token_name>.
00148   virtual int tryacquire (const ACE_TCHAR *token_name,
00149                           void (*sleep_hook)(void *) = 0);
00150 
00151   /**
00152    * Renews "atomically" all resources in the collection.  This is
00153    * only successfull if all tokens in the collection could be
00154    * renewed.  options contains the blocking semantics, timeout
00155    * value, etc.  Returns: 0 on success, -1 on failure with <errno> ==
00156    * problem.
00157    */
00158   virtual int renew (int requeue_position = 0,
00159                      ACE_Synch_Options &options =
00160                      ACE_Synch_Options::defaults);
00161 
00162 
00163   /// Renew the token corresponding to <token_name>.  The other
00164   /// parameters are passed to <token>::renew.
00165   virtual int renew (const ACE_TCHAR *token_name,
00166                      int requeue_position = 0,
00167                      ACE_Synch_Options &options =
00168                      ACE_Synch_Options::defaults);
00169 
00170   /**
00171    * Releases "atomically" all resources in the collection.  This is
00172    * only successfull if all tokens in the collection could be
00173    * released.  options contains the blocking semantics, timeout
00174    * value, etc.  Returns: 0 on success, -1 on failure with <errno> ==
00175    * problem.
00176    */
00177   virtual int release (ACE_Synch_Options &options =
00178                        ACE_Synch_Options::defaults);
00179 
00180 
00181   /// Release the token corresponding to <token_name>.  The other
00182   /// parameters are passed to <token>::release.
00183   virtual int release (const ACE_TCHAR *token_name,
00184                        ACE_Synch_Options &options =
00185                        ACE_Synch_Options::defaults);
00186 
00187   ~ACE_Token_Collection (void);
00188 
00189   /// Dump the state of the class.
00190   void dump (void) const;
00191 
00192   /// Return the name of the collection.  Not very functionally
00193   /// important, but sometimes a useful debugging tool.
00194   virtual const ACE_TCHAR *name (void) const;
00195 
00196 protected:
00197 
00198   typedef ACE_Token_Name TOKEN_NAME;
00199 
00200   /// COLLECTION maintains a mapping from token names to ACE_Tokens*
00201   typedef ACE_Map_Manager<TOKEN_NAME, ACE_Token_Proxy *, ACE_Null_Mutex>
00202     COLLECTION;
00203 
00204   /// Allows iterations through collection_
00205   typedef ACE_Map_Iterator<TOKEN_NAME, ACE_Token_Proxy *, ACE_Null_Mutex>
00206     COLLECTION_ITERATOR;
00207 
00208   /// Allows iterations through collection_
00209   typedef ACE_Map_Entry<TOKEN_NAME, ACE_Token_Proxy *>
00210     COLLECTION_ENTRY;
00211 
00212   /// COLLECTION maintains a mapping from token names to ACE_Tokens*.
00213   COLLECTION collection_;
00214 
00215   /// Whether to print out debug messages or not.
00216   int debug_;
00217 
00218   /// Name of the collection.
00219   ACE_TCHAR name_[ACE_MAXTOKENNAMELEN];
00220 
00221   // = I'm not sure what these mean, but they have to be defined since they're
00222   //   pure virtual in ACE_Token_Proxy.
00223   virtual ACE_Token_Proxy *clone (void) const;
00224   virtual ACE_Tokens *create_token (const ACE_TCHAR *name);
00225 };
00226 
00227 #endif /* ACE_HAS_TOKENS_LIBRARY */
00228 
00229 #if defined (__ACE_INLINE__)
00230 #include "ace/Token_Collection.i"
00231 #endif /* __ACE_INLINE__ */
00232 
00233 #include "ace/post.h"
00234 #endif /* ACE_TOKEN_COLLECTION_H */

Generated on Mon Jun 16 11:21:57 2003 for ACE by doxygen1.2.14 written by Dimitri van Heesch, © 1997-2002