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

ACE_Token_Collection Class Reference

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

#include <Token_Collection.h>

Inheritance diagram for ACE_Token_Collection:

Inheritance graph
[legend]
Collaboration diagram for ACE_Token_Collection:

Collaboration graph
[legend]
List of all members.

Public Methods

 ACE_Token_Collection (int debug=0, 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. More...

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)
 Acquire the token corresponding to <token_name>. The other parameters are passed to <token>acquire. More...

virtual int tryacquire (void(*sleep_hook)(void *)=0)
 Try to acquire all tokens in collection. More...

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

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)
 Renew the token corresponding to <token_name>. The other parameters are passed to <token>renew. More...

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)
 Release the token corresponding to <token_name>. The other parameters are passed to <token>release. More...

 ~ACE_Token_Collection (void)
void dump (void) const
 Dump the state of the class. More...

virtual const ACE_TCHAR * name (void) const
 Return the name of the collection. Not very functionally important, but sometimes a useful debugging tool. More...


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*. More...

typedef ACE_Map_Iterator<
TOKEN_NAME, ACE_Token_Proxy *,
ACE_Null_Mutex > 		COLLECTION_ITERATOR
 Allows iterations through collection_. More...

typedef ACE_Map_Entry< TOKEN_NAME,
ACE_Token_Proxy * > 		COLLECTION_ENTRY
 Allows iterations through collection_. More...


Protected Methods

virtual ACE_Token_Proxy * clone (void) const
 Return a dynamically allocated clone of the derived class. More...

virtual ACE_Tokens * create_token (const ACE_TCHAR *name)
 Make the correct type of ACE_Tokens. This is called by the Token Manager. More...


Protected Attributes

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

int debug_
 Whether to print out debug messages or not. More...

ACE_TCHAR name_ [ACE_MAXTOKENNAMELEN]
 Name of the collection. More...

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.

Definition at line 54 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 202 of file Token_Collection.h.

typedef ACE_Map_Entry<TOKEN_NAME, ACE_Token_Proxy *> ACE_Token_Collection::COLLECTION_ENTRY [protected]
 

Allows iterations through collection_.

Definition at line 210 of file Token_Collection.h.

typedef ACE_Map_Iterator<TOKEN_NAME, ACE_Token_Proxy *, ACE_Null_Mutex> ACE_Token_Collection::COLLECTION_ITERATOR [protected]
 

Allows iterations through collection_.

Definition at line 206 of file Token_Collection.h.

typedef ACE_Token_Name ACE_Token_Collection::TOKEN_NAME [protected]
 

Definition at line 198 of file Token_Collection.h.

Constructor & Destructor Documentation

ACE_Token_Collection::ACE_Token_Collection (  int    debug = 0,
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 14 of file Token_Collection.cpp.

References ACE_LIB_TEXT, ACE_MAXTOKENNAMELEN, ACE_TCHAR, ACE_TRACE, name, and ACE_OS_String::strsncpy. 

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

ACE_Token_Collection::~ACE_Token_Collection (  void    ) 
 

Definition at line 243 of file Token_Collection.cpp.

References ACE_TRACE, ACE_Map_Iterator::advance, collection_, ACE_Map_Entry< TOKEN_NAME, ACE_Token_Proxy * >::int_id_, and ACE_Map_Iterator_Base::next. 

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

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 <token>acquire.

Definition at line 107 of file Token_Collection.cpp.

References ACE_TCHAR, ACE_TRACE, ACE_Token_Proxy::acquire, collection_, ACE_Map_Manager< TOKEN_NAME, ACE_Token_Proxy *, ACE_Null_Mutex >::find, name, and ACE_Token_Proxy::sleep_hook. 

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

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.

Reimplemented from ACE_Token_Proxy.

Definition at line 76 of file Token_Collection.cpp.

References ACE_DEBUG, ACE_LIB_TEXT, ACE_RETURN, ACE_TRACE, ACE_Token_Proxy::acquire, ACE_Map_Iterator::advance, collection_, ACE_Map_Entry< TOKEN_NAME, ACE_Token_Proxy * >::int_id_, LM_DEBUG, ACE_Token_Proxy::name, ACE_Map_Iterator_Base::next, release, and ACE_Token_Proxy::sleep_hook. 

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

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

Return a dynamically allocated clone of the derived class.

Implements ACE_Token_Proxy.

Definition at line 261 of file Token_Collection.cpp.

References ACE_TRACE. 

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

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

Make the correct type of ACE_Tokens. This is called by the Token Manager.

Implements ACE_Token_Proxy.

Definition at line 269 of file Token_Collection.cpp.

References ACE_TCHAR, and ACE_TRACE. 

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

void ACE_Token_Collection::dump (  void    )  const
 

Dump the state of the class.

Reimplemented from ACE_Token_Proxy.

Definition at line 276 of file Token_Collection.cpp.

References ACE_BEGIN_DUMP, ACE_DEBUG, ACE_END_DUMP, ACE_LIB_TEXT, ACE_TRACE, collection_, debug_, ACE_Token_Proxy::dump, ACE_Map_Manager< TOKEN_NAME, ACE_Token_Proxy *, ACE_Null_Mutex >::dump, and LM_DEBUG. 

00277 {
00278   ACE_TRACE ("ACE_Token_Collection::dump");
00279   ACE_DEBUG ((LM_DEBUG, ACE_BEGIN_DUMP, this));
00280   ACE_DEBUG ((LM_DEBUG,  ACE_LIB_TEXT ("ACE_Token_Collection::dump:\n")
00281               ACE_LIB_TEXT (" debug_ = %d\n"), debug_));
00282   ACE_DEBUG ((LM_DEBUG,  ACE_LIB_TEXT ("collection_\n")));
00283   collection_.dump ();
00284   ACE_DEBUG ((LM_DEBUG,  ACE_LIB_TEXT ("base:\n")));
00285   ACE_Token_Proxy::dump ();
00286   ACE_DEBUG ((LM_DEBUG, ACE_END_DUMP));
00287 }

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 50 of file Token_Collection.cpp.

References ACE_TCHAR, ACE_TRACE, collection_, name, and ACE_Map_Manager< TOKEN_NAME, ACE_Token_Proxy *, ACE_Null_Mutex >::unbind. 

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

int ACE_Token_Collection::insert (  ACE_Token_Proxy &    token ) 
 

Definition at line 30 of file Token_Collection.cpp.

References ACE_ERROR_RETURN, ACE_LIB_TEXT, ACE_TRACE, ACE_Map_Manager< TOKEN_NAME, ACE_Token_Proxy *, ACE_Null_Mutex >::bind, ACE_Token_Proxy::clone, collection_, ACE_Map_Manager< TOKEN_NAME, ACE_Token_Proxy *, ACE_Null_Mutex >::find, LM_ERROR, ACE_Token_Proxy::name, and name. 

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

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 68 of file Token_Collection.cpp.

References ACE_TRACE, collection_, ACE_Map_Manager< TOKEN_NAME, ACE_Token_Proxy *, ACE_Null_Mutex >::find, and ACE_Token_Proxy::name. 

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

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

returns the proxy if true. 0 otherwise.

Definition at line 58 of file Token_Collection.cpp.

References ACE_TCHAR, ACE_TRACE, collection_, ACE_Map_Manager< TOKEN_NAME, ACE_Token_Proxy *, ACE_Null_Mutex >::find, and name. 

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

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.

Reimplemented from ACE_Token_Proxy.

Referenced by ACE_Token_Collection, 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 <token_name>. The other parameters are passed to <token>release.

Definition at line 228 of file Token_Collection.cpp.

References ACE_TCHAR, ACE_TRACE, collection_, ACE_Map_Manager< TOKEN_NAME, ACE_Token_Proxy *, ACE_Null_Mutex >::find, name, and ACE_Token_Proxy::release. 

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

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.

Reimplemented from ACE_Token_Proxy.

Definition at line 208 of file Token_Collection.cpp.

References ACE_DEBUG, ACE_LIB_TEXT, ACE_TRACE, ACE_Map_Iterator::advance, collection_, ACE_Map_Entry< TOKEN_NAME, ACE_Token_Proxy * >::int_id_, LM_DEBUG, ACE_Token_Proxy::name, ACE_Map_Iterator_Base::next, and ACE_Token_Proxy::release.

Referenced by acquire. 

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

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 <token>renew.

Definition at line 187 of file Token_Collection.cpp.

References ACE_ERROR_RETURN, ACE_LIB_TEXT, ACE_TCHAR, ACE_TRACE, collection_, ACE_Map_Manager< TOKEN_NAME, ACE_Token_Proxy *, ACE_Null_Mutex >::find, LM_DEBUG, name, and ACE_Token_Proxy::renew. 

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

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.

Reimplemented from ACE_Token_Proxy.

Definition at line 165 of file Token_Collection.cpp.

References ACE_DEBUG, ACE_LIB_TEXT, ACE_TRACE, ACE_Map_Iterator::advance, collection_, ACE_Map_Entry< TOKEN_NAME, ACE_Token_Proxy * >::int_id_, LM_DEBUG, ACE_Token_Proxy::name, ACE_Map_Iterator_Base::next, and ACE_Token_Proxy::renew. 

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

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

Try to acquire <token_name>.

Definition at line 126 of file Token_Collection.cpp.

References ACE_TCHAR, ACE_TRACE, collection_, ACE_Map_Manager< TOKEN_NAME, ACE_Token_Proxy *, ACE_Null_Mutex >::find, name, ACE_Token_Proxy::sleep_hook, and ACE_Token_Proxy::tryacquire. 

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

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

Try to acquire all tokens in collection.

Reimplemented from ACE_Token_Proxy.

Definition at line 143 of file Token_Collection.cpp.

References ACE_DEBUG, ACE_LIB_TEXT, ACE_TRACE, ACE_Map_Iterator::advance, collection_, ACE_Map_Entry< TOKEN_NAME, ACE_Token_Proxy * >::int_id_, LM_DEBUG, ACE_Token_Proxy::name, ACE_Map_Iterator_Base::next, ACE_Token_Proxy::sleep_hook, and ACE_Token_Proxy::tryacquire. 

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

Member Data Documentation

COLLECTION ACE_Token_Collection::collection_ [protected]
 

COLLECTION maintains a mapping from token names to ACE_Tokens*.

Definition at line 213 of file Token_Collection.h.

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

int ACE_Token_Collection::debug_ [protected]
 

Whether to print out debug messages or not.

Reimplemented from ACE_Token_Proxy.

Definition at line 216 of file Token_Collection.h.

Referenced by dump.

ACE_TCHAR ACE_Token_Collection::name_[ACE_MAXTOKENNAMELEN] [protected]
 

Name of the collection.

Definition at line 219 of file Token_Collection.h.

The documentation for this class was generated from the following files:
Generated on Mon Jun 16 12:58:25 2003 for ACE by doxygen1.2.14 written by Dimitri van Heesch, © 1997-2002