Main Page | Namespace List | Class Hierarchy | Alphabetical List | Class List | File List | Namespace Members | Class Members | File Members | Related Pages | Search for 

ACE_Token_Collection Class Reference

Allows atomic token group operations AND provides a ACE_Token manager interface. More...

#include <Token_Collection.h>

Collaboration diagram for ACE_Token_Collection:

Collaboration graph
[legend]
List of all members.

Public Member Functions

 ACE_Token_Collection (bool debug=false, const ACE_TCHAR *name=0)
int insert (ACE_Token_Proxy &token)
int extract (const ACE_TCHAR *token_name, ACE_Token_Proxy *&proxy)
ACE_Token_Proxy * is_member (const ACE_TCHAR *token_name)
 Returns the proxy if true. 0 otherwise.

int is_member (const ACE_Token_Proxy &token)
virtual int acquire (int notify=0, void(*sleep_hook)(void *)=0, ACE_Synch_Options &options=ACE_Synch_Options::defaults)
virtual int acquire (const ACE_TCHAR *token_name, int notify=0, void(*sleep_hook)(void *)=0, ACE_Synch_Options &options=ACE_Synch_Options::defaults)
virtual int tryacquire (void(*sleep_hook)(void *)=0)
 Try to acquire all tokens in collection.

virtual int tryacquire (const ACE_TCHAR *token_name, void(*sleep_hook)(void *)=0)
 Try to acquire token_name.

virtual int renew (int requeue_position=0, ACE_Synch_Options &options=ACE_Synch_Options::defaults)
virtual int renew (const ACE_TCHAR *token_name, int requeue_position=0, ACE_Synch_Options &options=ACE_Synch_Options::defaults)
virtual int release (ACE_Synch_Options &options=ACE_Synch_Options::defaults)
virtual int release (const ACE_TCHAR *token_name, ACE_Synch_Options &options=ACE_Synch_Options::defaults)
 ~ACE_Token_Collection (void)
void dump (void) const
 Dump the state of the class.

virtual const ACE_TCHAR * name (void) const

Protected Types

typedef ACE_Token_Name TOKEN_NAME
typedef ACE_Map_Manager< TOKEN_NAME,
ACE_Token_Proxy *, ACE_Null_Mutex > 		COLLECTION
 COLLECTION maintains a mapping from token names to ACE_Tokens*.

typedef COLLECTION::ITERATOR COLLECTION_ITERATOR
 Allows iterations through collection_.

typedef COLLECTION::ENTRY COLLECTION_ENTRY
 Allows iterations through collection_.


Protected Member Functions

virtual ACE_Token_Proxy * clone (void) const
virtual ACE_Tokens * create_token (const ACE_TCHAR *name)

Protected Attributes

COLLECTION collection_
 COLLECTION maintains a mapping from token names to ACE_Tokens*.

bool debug_
 Whether to print out debug messages or not.

ACE_TCHAR name_ [ACE_MAXTOKENNAMELEN]
 Name of the collection.

Detailed Description

Allows atomic token group operations AND provides a ACE_Token manager interface.

There are two types of operations offered by ACE_Token_Collection. The first is atomic operations on collections of Token_Proxies. In this respect, the ACE_Token_Collection can be thought of as a single token consisting of multiple Token_Proxies. The second role of the ACE_Token_Collection is as a ACE_Token manager. ACE_Token_Collection allows individual operations on single members of a collection of Token_Proxies. This provides a single access point for operations on multiple tokens.

Bug:
Although ACE_Token_Collection inherits from ACE_Token_Proxy, it can not be including in a collection. This is because returns zero for now.

Definition at line 61 of file Token_Collection.h.

Member Typedef Documentation

typedef ACE_Map_Manager<TOKEN_NAME, ACE_Token_Proxy *, ACE_Null_Mutex> ACE_Token_Collection::COLLECTION [protected]
 

COLLECTION maintains a mapping from token names to ACE_Tokens*.

Definition at line 205 of file Token_Collection.h.

typedef COLLECTION::ENTRY ACE_Token_Collection::COLLECTION_ENTRY [protected]
 

Allows iterations through collection_.

Deprecated:
Deprecated typedef. Use COLLECTION::ENTRY trait instead.

Definition at line 217 of file Token_Collection.h.

typedef COLLECTION::ITERATOR ACE_Token_Collection::COLLECTION_ITERATOR [protected]
 

Allows iterations through collection_.

Deprecated:
Deprecated typedef. Use COLLECTION::ITERATOR trait instead.

Definition at line 211 of file Token_Collection.h.

typedef ACE_Token_Name ACE_Token_Collection::TOKEN_NAME [protected]
 

Definition at line 201 of file Token_Collection.h.

Referenced by acquire(), extract(), insert(), is_member(), release(), renew(), and tryacquire().

Constructor & Destructor Documentation

ACE_BEGIN_VERSIONED_NAMESPACE_DECL ACE_Token_Collection::ACE_Token_Collection (  bool  debug = false,
const ACE_TCHAR *  name = 0
) 
 

debug print out verbose debugging messages. name will give a name to the collection. Collections don't really need names, but are sometimes useful for debugging.

Definition at line 16 of file Token_Collection.cpp.

References ACE_MAXTOKENNAMELEN, ACE_TCHAR, ACE_TEXT, ACE_TRACE, and ACE_OS::strsncpy(). 

00018 : debug_ (debug)
00019 {
00020   ACE_TRACE ("ACE_Token_Collection::ACE_Token_Collection");
00021 
00022   if (name == 0)
00023     name = ACE_TEXT ("no name");
00024 
00025   ACE_OS::strsncpy (this->name_,
00026                     const_cast<ACE_TCHAR *> (name),
00027                     ACE_MAXTOKENNAMELEN);
00028 }

ACE_Token_Collection::~ACE_Token_Collection (  void   ) 
 

Definition at line 244 of file Token_Collection.cpp.

References ACE_TRACE, and collection_. 

00245 {
00246   ACE_TRACE ("ACE_Token_Collection::~ACE_Token_Collection");
00247   COLLECTION::ITERATOR iterator (collection_);
00248 
00249   for (COLLECTION::ENTRY *temp = 0;
00250        iterator.next (temp) != 0;
00251        iterator.advance ())
00252     {
00253       delete temp->int_id_;
00254       // The ext_id_'s delete themselves when the array of
00255       // COLLECTION::ENTRYs goes away.
00256     }
00257 }

Member Function Documentation

int ACE_Token_Collection::acquire (  const ACE_TCHAR *  token_name,
int  notify = 0,
void(*  sleep_hook)(void *) = 0,
ACE_Synch_Options &  options = ACE_Synch_Options::defaults
)  [virtual]
 

Acquire the token corresponding to token_name. The other parameters are passed to ::acquire.

Definition at line 108 of file Token_Collection.cpp.

References ACE_TCHAR, ACE_TRACE, collection_, ACE_Map_Manager< EXT_ID, INT_ID, ACE_LOCK >::find(), name(), and TOKEN_NAME. 

00112 {
00113   ACE_TRACE ("ACE_Token_Collection::acquire");
00114   TOKEN_NAME name (token_name);
00115   ACE_Token_Proxy *temp;
00116   // Get the token from the collection.
00117   int result = collection_.find (name, temp);
00118   // did we find it?
00119   if (result == -1)
00120     return result;
00121   // perform the operation
00122   return temp->acquire (notify, sleep_hook, options);
00123 }

int ACE_Token_Collection::acquire (  int  notify = 0,
void(*  sleep_hook)(void *) = 0,
ACE_Synch_Options &  options = ACE_Synch_Options::defaults
)  [virtual]
 

Acquire "atomically" all resources in the collection. This is only successfull if all tokens in the collection could be acquired. options contains the blocking semantics, timeout value, etc. Returns: 0 on success, -1 on failure with errno == problem. If and error or deadlock occurs for one of the tokens, all the tokens will be released and the method will return -1. Note that returning on detection of deadlock prevents livelock between competing collections. If a collection returns after detecting deadlock, it is the application's responsibility to not to blindly loop on the collection::acquire operation. In other words, once the collection reports deadlock, it is out of our hands.

Definition at line 77 of file Token_Collection.cpp.

References ACE_DEBUG, ACE_RETURN, ACE_TEXT, ACE_TRACE, collection_, LM_DEBUG, and release(). 

00080 {
00081   ACE_TRACE ("ACE_Token_Collection::acquire");
00082 
00083   COLLECTION::ITERATOR iterator (collection_);
00084 
00085   for (COLLECTION::ENTRY *temp = 0;
00086        iterator.next (temp) != 0;
00087        iterator.advance ())
00088     {
00089       if (debug_)
00090         ACE_DEBUG ((LM_DEBUG,
00091                     ACE_TEXT ("collection acquiring %s\n"),
00092                     temp->int_id_->name ()));
00093       if (temp->int_id_->acquire (notify,
00094                                   sleep_hook,
00095                                   options) == -1)
00096         {
00097           // Save/restore errno.
00098           ACE_Errno_Guard error (errno);
00099           this->release ();
00100           ACE_RETURN (-1);
00101         }
00102     }
00103 
00104   return 0;
00105 }

ACE_Token_Proxy * ACE_Token_Collection::clone (  void   )  const [protected, virtual]
 

Definition at line 262 of file Token_Collection.cpp.

References ACE_TRACE. 

00263 {
00264   ACE_TRACE ("ACE_Token_Collection::clone");
00265   return (ACE_Token_Proxy *) 0;
00266 }

ACE_Tokens * ACE_Token_Collection::create_token (  const ACE_TCHAR *  name  )  [protected, virtual]
 

Definition at line 270 of file Token_Collection.cpp.

References ACE_TCHAR, and ACE_TRACE. 

00271 {
00272   ACE_TRACE ("ACE_Token_Collection::create_token");
00273   return (ACE_Tokens *) 0;
00274 }

void ACE_Token_Collection::dump (  void   )  const
 

Dump the state of the class.

Definition at line 277 of file Token_Collection.cpp.

References ACE_BEGIN_DUMP, ACE_DEBUG, ACE_END_DUMP, ACE_TEXT, ACE_TRACE, collection_, ACE_Map_Manager< EXT_ID, INT_ID, ACE_LOCK >::dump(), and LM_DEBUG. 

00278 {
00279 #if defined (ACE_HAS_DUMP)
00280   ACE_TRACE ("ACE_Token_Collection::dump");
00281   ACE_DEBUG ((LM_DEBUG, ACE_BEGIN_DUMP, this));
00282   ACE_DEBUG ((LM_DEBUG,  ACE_TEXT ("ACE_Token_Collection::dump:\n")
00283               ACE_TEXT (" debug_ = %d\n"), debug_));
00284   ACE_DEBUG ((LM_DEBUG,  ACE_TEXT ("collection_\n")));
00285   collection_.dump ();
00286   ACE_DEBUG ((LM_DEBUG,  ACE_TEXT ("base:\n")));
00287   ACE_Token_Proxy::dump ();
00288   ACE_DEBUG ((LM_DEBUG, ACE_END_DUMP));
00289 #endif /* ACE_HAS_DUMP */
00290 }

int ACE_Token_Collection::extract (  const ACE_TCHAR *  token_name,
ACE_Token_Proxy *&  proxy
) 
 

Removes the ACE_Token matching the given token_name from the collection. On success, extract returns 0. On failure (token_name was not in the collection,) extract returns -1. On success, the state of the token found is copied into proxy. The returned ACE_Token_Proxy* must be deleted by the user.

Definition at line 51 of file Token_Collection.cpp.

References ACE_TCHAR, ACE_TRACE, collection_, name(), TOKEN_NAME, and ACE_Map_Manager< EXT_ID, INT_ID, ACE_LOCK >::unbind(). 

00052 {
00053   ACE_TRACE ("ACE_Token_Collection::extract");
00054   TOKEN_NAME name (token_name);
00055   return collection_.unbind (token_name, proxy);
00056 }

int ACE_Token_Collection::insert (  ACE_Token_Proxy &  token  ) 
 

Insert a Token into the collection. All ACE_Token type operations performed on the collection will also be performed on the new_proxy until it is removed. Note that no operations performed prior to the insertion will be performed. Returns: 0 on success, -1 on failure with errno == problem. If a token proxy already exists in the collection with the same name, the insertion will fail. Also, is copied. Note that during the copy, client_id's are *not* inherited. The client ID of the thread using the collection will be used. Client ID's can be changed explicity on each proxy using is_member.

Definition at line 31 of file Token_Collection.cpp.

References ACE_ERROR_RETURN, ACE_TEXT, ACE_TRACE, ACE_Map_Manager< EXT_ID, INT_ID, ACE_LOCK >::bind(), collection_, ACE_Map_Manager< EXT_ID, INT_ID, ACE_LOCK >::find(), LM_ERROR, name(), and TOKEN_NAME. 

00032 {
00033   ACE_TRACE ("ACE_Token_Collection::insert");
00034 
00035   TOKEN_NAME name (new_token.name ());
00036 
00037   // Check if the new_proxy is already in the list.
00038   if (collection_.find (name) == 1)
00039     // One already exists, so fail.
00040     return -1;
00041 
00042   // Clone the new token.
00043   ACE_Token_Proxy *temp = new_token.clone ();
00044 
00045   if (collection_.bind (name, temp) == -1)
00046     ACE_ERROR_RETURN ((LM_ERROR, ACE_TEXT ("bind failed\n")), -1);
00047   return 0;
00048 }

int ACE_Token_Collection::is_member (  const ACE_Token_Proxy &  token  ) 
 

Is the specified token in the collection? 1, yes. 0, no.

Definition at line 69 of file Token_Collection.cpp.

References ACE_TRACE, collection_, ACE_Map_Manager< EXT_ID, INT_ID, ACE_LOCK >::find(), and TOKEN_NAME. 

00070 {
00071   ACE_TRACE ("ACE_Token_Collection::is_member");
00072   TOKEN_NAME token_name (token.name ());
00073   return collection_.find (token_name) == 0;
00074 }

ACE_Token_Proxy * ACE_Token_Collection::is_member (  const ACE_TCHAR *  token_name  ) 
 

Returns the proxy if true. 0 otherwise.

Definition at line 59 of file Token_Collection.cpp.

References ACE_TCHAR, ACE_TRACE, collection_, ACE_Map_Manager< EXT_ID, INT_ID, ACE_LOCK >::find(), name(), and TOKEN_NAME. 

00060 {
00061   ACE_TRACE ("ACE_Token_Collection::is_member");
00062   TOKEN_NAME name (token_name);
00063   ACE_Token_Proxy *temp;
00064   // Get the token from the collection.
00065   return collection_.find (name, temp) == -1 ? 0 : temp;
00066 }

virtual const ACE_TCHAR* ACE_Token_Collection::name (  void   )  const [virtual]
 

Return the name of the collection. Not very functionally important, but sometimes a useful debugging tool.

Referenced by acquire(), extract(), insert(), is_member(), release(), renew(), and tryacquire().

int ACE_Token_Collection::release (  const ACE_TCHAR *  token_name,
ACE_Synch_Options &  options = ACE_Synch_Options::defaults
)  [virtual]
 

Release the token corresponding to . The other parameters are passed to ::release.

Definition at line 229 of file Token_Collection.cpp.

References ACE_TCHAR, ACE_TRACE, collection_, ACE_Map_Manager< EXT_ID, INT_ID, ACE_LOCK >::find(), name(), and TOKEN_NAME. 

00231 {
00232   ACE_TRACE ("ACE_Token_Collection::release");
00233   TOKEN_NAME name (token_name);
00234   ACE_Token_Proxy *temp;
00235   // get the token from the collection
00236   int result = collection_.find (name, temp);
00237   // did we find it?
00238   if (result != 0)
00239     return result;
00240   // perform the operation
00241   return temp->release (options);
00242 }

int ACE_Token_Collection::release (  ACE_Synch_Options &  options = ACE_Synch_Options::defaults  )  [virtual]
 

Releases "atomically" all resources in the collection. This is only successfull if all tokens in the collection could be released. options contains the blocking semantics, timeout value, etc. Returns: 0 on success, -1 on failure with errno == problem.

Definition at line 209 of file Token_Collection.cpp.

References ACE_DEBUG, ACE_TEXT, ACE_TRACE, collection_, and LM_DEBUG.

Referenced by acquire(). 

00211 {
00212   ACE_TRACE ("ACE_Token_Collection::release");
00213   COLLECTION::ITERATOR iterator (collection_);
00214 
00215   for (COLLECTION::ENTRY *temp = 0;
00216        iterator.next (temp) != 0;
00217        iterator.advance ())
00218     {
00219       if (debug_)
00220         ACE_DEBUG ((LM_DEBUG,  ACE_TEXT ("collection releasing %s\n"),
00221                     temp->int_id_->name ()));
00222       temp->int_id_->release ();
00223     }
00224 
00225   return 0;
00226 }

int ACE_Token_Collection::renew (  const ACE_TCHAR *  token_name,
int  requeue_position = 0,
ACE_Synch_Options &  options = ACE_Synch_Options::defaults
)  [virtual]
 

Renew the token corresponding to token_name. The other parameters are passed to ::renew.

Definition at line 188 of file Token_Collection.cpp.

References ACE_ERROR_RETURN, ACE_TCHAR, ACE_TEXT, ACE_TRACE, collection_, ACE_Map_Manager< EXT_ID, INT_ID, ACE_LOCK >::find(), LM_DEBUG, name(), and TOKEN_NAME. 

00191 {
00192   ACE_TRACE ("ACE_Token_Collection::renew");
00193   TOKEN_NAME name (token_name);
00194   ACE_Token_Proxy *temp;
00195 
00196   // Get the token from the collection.
00197   int result = collection_.find (name, temp);
00198 
00199   // Did we find it?
00200   if (result == -1)
00201     ACE_ERROR_RETURN ((LM_DEBUG, ACE_TEXT ("%p %s\n"),
00202                        ACE_TEXT ("not in collection "),
00203                        token_name), -1);
00204   // perform the operation
00205   return temp->renew (requeue_position, options);
00206 }

int ACE_Token_Collection::renew (  int  requeue_position = 0,
ACE_Synch_Options &  options = ACE_Synch_Options::defaults
)  [virtual]
 

Renews "atomically" all resources in the collection. This is only successfull if all tokens in the collection could be renewed. options contains the blocking semantics, timeout value, etc. Returns: 0 on success, -1 on failure with errno == problem.

Definition at line 166 of file Token_Collection.cpp.

References ACE_DEBUG, ACE_TEXT, ACE_TRACE, collection_, and LM_DEBUG. 

00168 {
00169   ACE_TRACE ("ACE_Token_Collection::renew");
00170 
00171   COLLECTION::ITERATOR iterator (collection_);
00172 
00173   for (COLLECTION::ENTRY *temp = 0;
00174        iterator.next (temp) != 0;
00175        iterator.advance ())
00176     {
00177       if (debug_)
00178         ACE_DEBUG ((LM_DEBUG,  ACE_TEXT ("collection renewing %s\n"),
00179                     temp->int_id_->name ()));
00180       if (temp->int_id_->renew (requeue_position, options) == -1)
00181         return -1;
00182     }
00183 
00184   return 0;
00185 }

int ACE_Token_Collection::tryacquire (  const ACE_TCHAR *  token_name,
void(*  sleep_hook)(void *) = 0
)  [virtual]
 

Try to acquire token_name.

Definition at line 127 of file Token_Collection.cpp.

References ACE_TCHAR, ACE_TRACE, collection_, ACE_Map_Manager< EXT_ID, INT_ID, ACE_LOCK >::find(), name(), and TOKEN_NAME. 

00129 {
00130   ACE_TRACE ("ACE_Token_Collection::tryacquire");
00131   TOKEN_NAME name (token_name);
00132   ACE_Token_Proxy *temp;
00133   // Get the token from the collection.
00134   int result = collection_.find (name, temp);
00135   // did we find it?
00136   if (result == -1)
00137     return result;
00138 
00139   // perform the operation
00140   return temp->tryacquire (sleep_hook);
00141 }

int ACE_Token_Collection::tryacquire (  void(*  sleep_hook)(void *) = 0  )  [virtual]
 

Try to acquire all tokens in collection.

Definition at line 144 of file Token_Collection.cpp.

References ACE_DEBUG, ACE_TEXT, ACE_TRACE, collection_, and LM_DEBUG. 

00145 {
00146   ACE_TRACE ("ACE_Token_Collection::tryacquire");
00147 
00148   COLLECTION::ITERATOR iterator (collection_);
00149 
00150   for (COLLECTION::ENTRY *temp = 0;
00151        iterator.next (temp) != 0;
00152        iterator.advance ())
00153     {
00154       if (debug_)
00155         ACE_DEBUG ((LM_DEBUG,  ACE_TEXT ("collection acquiring %s\n"),
00156                     temp->int_id_->name ()));
00157       // We will fail if _any_ token is not free.
00158       if (temp->int_id_->tryacquire (sleep_hook) == -1)
00159         return -1;
00160     }
00161 
00162   return 0;
00163 }

Member Data Documentation

COLLECTION ACE_Token_Collection::collection_ [protected]
 

COLLECTION maintains a mapping from token names to ACE_Tokens*.

Definition at line 220 of file Token_Collection.h.

Referenced by acquire(), dump(), extract(), insert(), is_member(), release(), renew(), tryacquire(), and ~ACE_Token_Collection().

bool ACE_Token_Collection::debug_ [protected]
 

Whether to print out debug messages or not.

Definition at line 223 of file Token_Collection.h.

ACE_TCHAR ACE_Token_Collection::name_[ACE_MAXTOKENNAMELEN] [protected]
 

Name of the collection.

Definition at line 226 of file Token_Collection.h.

The documentation for this class was generated from the following files:
Generated on Sun Jan 27 12:59:08 2008 for ACE by doxygen 1.3.6