path: root/ace/Token_Collection.h

/* -*- C++ -*- */

//=============================================================================
/**
 *  @file    Token_Collection.h
 *
 *  $Id$
 *
 *  The ACE_Token class offers methods for acquiring, renewing,
 *  and releasing a synchronization token on a per-token basis.  The
 *  ACE_Token_Collection offers an interface for performing
 *  operations on groups of tokens as a whole, or on a single token
 *  within the collection.
 *
 *  The atomic group operations are not yet implemented.
 *
 *
 *  @author Douglas C. Schmidt (schmidt@cs.wustl.edu)
 *  @author Tim Harrison (harrison@cs.wustl.edu)
 */
//=============================================================================

#ifndef ACE_TOKEN_COLLECTION_H
#define ACE_TOKEN_COLLECTION_H
#include "ace/pre.h"

#include "ace/Map_Manager.h"

#if !defined (ACE_LACKS_PRAGMA_ONCE)
# pragma once
#endif /* ACE_LACKS_PRAGMA_ONCE */

#include "ace/Local_Tokens.h"
#include "ace/SString.h"

#if defined (ACE_HAS_TOKENS_LIBRARY)

/**
 * @class ACE_Token_Collection
 *
 * @brief 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.
 */
class ACE_Export ACE_Token_Collection : public ACE_Token_Proxy
{

  // = BUGS
  //   Although ACE_Token_Collection inherits from ACE_Token_Proxy, it
  //   can not be including in a collection.  This is because <clone>
  //   returns zero for now.
public:
  /**
   * <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.
   */
  ACE_Token_Collection (int debug = 0,
                        const ACE_TCHAR *name = 0);

// Collection Management operations

  int 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, <token> 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.

  /**
   * 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.
   */
  int extract (const ACE_TCHAR *token_name, ACE_Token_Proxy *&proxy);

  /// returns the proxy if true.  0 otherwise.
  ACE_Token_Proxy *is_member (const ACE_TCHAR *token_name);

  /**
   * Is the specified token in the collection?
   * 1, yes.
   * 0, no.
   */
  int is_member (const ACE_Token_Proxy &token);

// = Collective operation semantics.

//   For acquire, renew, and release, there are two interfaces.  Once
//   interface allows an operation on a single token in the
//   collection.  The collective interfaces perform atomic operations
//   on the entire collection.  For instance, a collective acquire
//   will perform an acquire for each and every token in the
//   collection or the operation will fail.  Currently, these
//   operations are performed with no ordering heuristics.  That is,
//   the Collection steps through the tokens in the order they were
//   inserted.  For each one it performs the operation (acquire,
//   renew, or release).

  /**
   * 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.
   */
  virtual int acquire (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.
  virtual int acquire (const ACE_TCHAR *token_name,
                       int notify = 0,
                       void (*sleep_hook)(void *) = 0,
                       ACE_Synch_Options &options =
                       ACE_Synch_Options::defaults);

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

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

  /**
   * 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.
   */
  virtual int renew (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.
  virtual int renew (const ACE_TCHAR *token_name,
                     int requeue_position = 0,
                     ACE_Synch_Options &options =
                     ACE_Synch_Options::defaults);

  /**
   * 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.
   */
  virtual int release (ACE_Synch_Options &options =
                       ACE_Synch_Options::defaults);


  /// Release the token corresponding to <token_name>.  The other
  /// parameters are passed to <token>::release.
  virtual int release (const ACE_TCHAR *token_name,
                       ACE_Synch_Options &options =
                       ACE_Synch_Options::defaults);

  ~ACE_Token_Collection (void);

  /// Dump the state of the class.
  void dump (void) const;

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

protected:

  typedef ACE_Token_Name TOKEN_NAME;

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

  /// Allows iterations through collection_
  typedef ACE_Map_Iterator<TOKEN_NAME, ACE_Token_Proxy *, ACE_Null_Mutex>
    COLLECTION_ITERATOR;

  /// Allows iterations through collection_
  typedef ACE_Map_Entry<TOKEN_NAME, ACE_Token_Proxy *>
    COLLECTION_ENTRY;

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

  /// Whether to print out debug messages or not.
  int debug_;

  /// Name of the collection.
  ACE_TCHAR name_[ACE_MAXTOKENNAMELEN];

  // = I'm not sure what these mean, but they have to be defined since they're
  //   pure virtual in ACE_Token_Proxy.
  virtual ACE_Token_Proxy *clone (void) const;
  virtual ACE_Tokens *create_token (const ACE_TCHAR *name);
};

#endif /* ACE_HAS_TOKENS_LIBRARY */

#if defined (__ACE_INLINE__)
#include "ace/Token_Collection.i"
#endif /* __ACE_INLINE__ */

#include "ace/post.h"
#endif /* ACE_TOKEN_COLLECTION_H */