ACE/ace/Remote_Tokens.h

   1 // -*- C++ -*-
   2
   3 //=============================================================================
   4 /**
   5  *  @file    Remote_Tokens.h
   6  *
   7  *  @author Douglas C. Schmidt (d.schmidt@vanderbilt.edu)
   8  *  @author Tim Harrison (harrison@cs.wustl.edu)
   9  */
  10 //=============================================================================
  11
  12 #ifndef ACE_REMOTE_MUTEX_H
  13 #define ACE_REMOTE_MUTEX_H
  14
  15 #include /**/ "ace/pre.h"
  16
  17 #include "ace/INET_Addr.h"
  18
  19 #if !defined (ACE_LACKS_PRAGMA_ONCE)
  20 # pragma once
  21 #endif /* ACE_LACKS_PRAGMA_ONCE */
  22
  23 #include "ace/SOCK_Connector.h"
  24 #include "ace/SOCK_Stream.h"
  25 #include "ace/Synch_Options.h"
  26 #include "ace/Local_Tokens.h"
  27 #include "ace/Token_Request_Reply.h"
  28
  29 #if defined (ACE_HAS_TOKENS_LIBRARY)
  30
  31 ACE_BEGIN_VERSIONED_NAMESPACE_DECL
  32
  33 /**
  34  * @class ACE_Remote_Token_Proxy
  35  *
  36  * @brief Proxy for acquiring, renewing, and releasing a distributed
  37  * synchronization token.
  38  *
  39  * The Remote_Token_Proxy class implements the mechanisms for
  40  * distributed token operations.  It is similar to the
  41  * ACE_Token_Proxy.
  42  * @todo
  43  * Distributed sleep_hooks have not been implemented. <owner_id>
  44  * is not implemented.
  45  */
  46 class ACE_Export ACE_Remote_Token_Proxy : public ACE_Token_Proxy
  47 {
  48 public:
  49   /// Null construction.
  50   ACE_Remote_Token_Proxy ();
  51
  52   /// Death.
  53   virtual ~ACE_Remote_Token_Proxy ();
  54
  55   /**
  56    * Same as Token_Proxy. @a name is the string uniquely identifying
  57    * the token.  @a ignore_deadlock can be 1 to disable deadlock
  58    * notifications.  @a debug prints debug messages.
  59    */
  60   int open (const ACE_TCHAR *name,
  61             int ignore_deadlock = 0,
  62             int debug = 0);
  63
  64
  65   /**
  66    * Open a connection with the token server.  This only need be used
  67    * when the user wishes to explicitly open a connection to check if
  68    * the server exists.  Connections are stored in the
  69    * ACE_Token_Connections singleton as thread-specific data.  That
  70    * is, every thread has only one connection that is used for all
  71    * remote tokens.
  72    */
  73   int initiate_connection ();
  74
  75   /**
  76    * Acquire the distributed token.  If notify is specified and the
  77    * token is already held, the owner is notified.  options contains
  78    * the timeout value for the acquire call.  The timer is kept at the
  79    * token server.  Asynchronous operations are not supported.
  80    * Returns 0 on success, -1 on failure with @c errno == problem.
  81    */
  82   virtual int acquire (int notify = 0,
  83                        void (*sleep_hook)(void *) = 0,
  84                        ACE_Synch_Options &options =
  85                        ACE_Synch_Options::synch);
  86
  87   /**
  88    * Try to acquire the distributed token.  If the token is already
  89    * held, the call returns without queuing the caller as a waiter.
  90    * Returns 0 on success (the token was acquired), and -1 with
  91    * EWOULDBLOCK if the token was already held.
  92    */
  93   virtual int tryacquire (void (*sleep_hook)(void *) = 0);
  94
  95   /**
  96    * Renew the token by offering to release it if there are any other
  97    * waiters, otherwise get the token back immediately.  This renew
  98    * has the same semantics as ACE_Local_Mutex release.  It is
  99    * semantically equivalent to release() followed by acquire(), but
 100    * it is faster.  options contains the timeout value used if renew
 101    * blocks.  As with acquire, the timer is maintained at the token
 102    * server.  If there are waiters and requeue_position == -1, the
 103    * caller is queued at the rear of the waiter list.  Otherwise,
 104    * requeue_position specifies the number of waiters to "let by"
 105    * before reacquiring the token (effectively, the position in the
 106    * waiter list.)
 107    */
 108   virtual int renew (int requeue_position = 0,
 109                      ACE_Synch_Options &options =
 110                      ACE_Synch_Options::synch);
 111
 112   /**
 113    * Release the distributed token. Similar to ACE_Local_Mutex, if the
 114    * caller is not the owner, it is removed from the waiter list (if
 115    * applicable.) Returns 0 on success, -1 on failure with @c errno ==
 116    * problem.
 117    */
 118   virtual int release (ACE_Synch_Options &options =
 119                        ACE_Synch_Options::synch);
 120
 121   /// Become interface compliant for our guards.  This has no
 122   /// functionality.
 123   virtual int remove (ACE_Synch_Options &options = ACE_Synch_Options::synch);
 124
 125   /// Override the default to do nothing.
 126   virtual void token_acquired (ACE_TPQ_Entry *);
 127
 128   /// The client id of the current token holder
 129   virtual const ACE_TCHAR* owner_id ();
 130
 131   /**
 132    * Sets the server address for all instances of ACE_Remote_Token_Proxy
 133    * If this isn't called, the environment variable TOKEN_SERVER is
 134    * checked for the server address.  If that is not specified, all
 135    * ACE_Remote_** operations will fail.
 136    */
 137   static void set_server_address (const ACE_INET_Addr &server_address);
 138
 139   /// Dump the state of the class.
 140   void dump () const;
 141
 142 protected:
 143   /// If shadows report deadlock, go remote anyway
 144   int ignore_shadow_deadlock_;
 145
 146   /// Perform the request and wait for the reply.
 147   int request_reply (ACE_Token_Request &request,
 148                      ACE_Synch_Options &options);
 149 };
 150
 151 /**
 152  * @class ACE_Remote_Mutex
 153  *
 154  * @brief Proxy for acquiring, renewing, and releasing a distributed
 155  * mutex.
 156  *
 157  * This is the remote equivalent to ACE_Local_Mutex.  The
 158  * Remote_Mutex class offers methods for acquiring, renewing, and
 159  * releasing a distributed synchronization mutex.  Similar to
 160  * ACE_Local_Mutex, ACE_Remote_Token_Proxy offers recursive
 161  * acquisition, FIFO waiter ordering, and deadlock detection.  It
 162  * depends on the Token Server for its distributed synchronization
 163  * semantics.
 164  */
 165 class ACE_Export ACE_Remote_Mutex : public ACE_Remote_Token_Proxy
 166 {
 167 public:
 168   /// Null creation.  Remote_Token_Proxy::open must be called.
 169   ACE_Remote_Mutex ();
 170
 171   /// Calls Remote_Token_Proxy::open for you.
 172   ACE_Remote_Mutex (const ACE_TCHAR *token_name,
 173                     int ignore_deadlock = 0,
 174                     int debug = 0);
 175
 176   /// Dump the state of the class.
 177   void dump () const;
 178
 179   /// Return deep copy.
 180   virtual ACE_Token_Proxy *clone () const;
 181
 182 protected:
 183   /// Make the correct type of ACE_Tokens.
 184   /// This is called by the ACE_Token_Manager.
 185   virtual ACE_Tokens *create_token (const ACE_TCHAR *name);
 186 };
 187
 188 /**
 189  * @class ACE_Remote_RLock
 190  *
 191  * @brief Proxy for acquiring, renewing, and releasing a distributed
 192  * readers lock.
 193  *
 194  * This is the remote equivalent to ACE_Local_RLock. Multiple
 195  * readers can hold the lock simultaneously when no writers have
 196  * the lock.  Alternatively, when a writer holds the lock, no other
 197  * participants (readers or writers) may hold the lock.
 198  * ACE_Remote_RLock depends on the ACE Token Server for its
 199  * distributed synchronization semantics.
 200  */
 201 class ACE_Export ACE_Remote_RLock : public ACE_Remote_Token_Proxy
 202 {
 203 public:
 204   ACE_Remote_RLock ();
 205
 206   ACE_Remote_RLock (const ACE_TCHAR *token_name,
 207                     int ignore_deadlock = 0,
 208                     int debug = 0);
 209
 210   ACE_Remote_RLock (const ACE_Remote_RLock &mutex);
 211
 212   /// Dump the state of the class.
 213   void dump () const;
 214
 215   /// Returns ACE_RW_Token::RLOCK;
 216   virtual int type () const;
 217
 218   /// Return deep copy.
 219   virtual ACE_Token_Proxy *clone () const;
 220
 221 protected:
 222   /// Make the correct type of ACE_Tokens.  This is called by the Token
 223   /// Manager.
 224   virtual ACE_Tokens *create_token (const ACE_TCHAR *name);
 225 };
 226
 227 /**
 228  * @class ACE_Remote_WLock
 229  *
 230  * @brief Proxy for acquiring, renewing, and releasing a distributed
 231  * writers lock.
 232  *
 233  * Shields applications from details of interacting with the
 234  * ACE_Token_Server.  The token_name_ is just the string that the
 235  * Token Server uses to identify the token.  The client_id_ (also
 236  * used by the Token Server,) identifies the owner of the token and
 237  * is used for deadlock detection.
 238  */
 239 class ACE_Export ACE_Remote_WLock : public ACE_Remote_Token_Proxy
 240 {
 241 public:
 242   ACE_Remote_WLock ();
 243
 244   ACE_Remote_WLock (const ACE_TCHAR *token_name,
 245                     int ignore_deadlock = 0,
 246                     int debug = 0);
 247
 248   ACE_Remote_WLock (const ACE_Remote_WLock &mutex);
 249
 250   /// Dump the state of the class.
 251   void dump () const;
 252
 253   /// Returns ACE_RW_Token::WLOCK;
 254   virtual int type () const;
 255
 256   /// Return deep copy.
 257   virtual ACE_Token_Proxy *clone () const;
 258
 259 protected:
 260   /// Make the correct type of ACE_Tokens.  This is called by the Token
 261   /// Manager.
 262   virtual ACE_Tokens *create_token (const ACE_TCHAR *name);
 263 };
 264
 265 /**
 266  * @class ACE_TSS_Connection
 267  *
 268  * @brief Class for providing a connection per thread.
 269  *
 270  * ACE_TSS_Connection provides a single access point for all
 271  * threads to access thread-specific connections.  This prevents
 272  * resource-sharing problems such as thread serialization.
 273  */
 274 class ACE_Export ACE_TSS_Connection : public ACE_TSS<ACE_SOCK_Stream>
 275 {
 276 public:
 277   // Necessary to make some compilers work...
 278   ACE_TSS_Connection ();
 279   ~ACE_TSS_Connection ();
 280
 281   /// Retrieve the thread's connection
 282   ACE_SOCK_Stream *get_connection ();
 283
 284   /// Factory Method that creates a new SOCK Stream.
 285   virtual ACE_SOCK_Stream *make_TSS_TYPE () const;
 286
 287   /// Inheritance and operator overloading don't mix.  Redefine this
 288   /// from ACE_TSS so that we can use it.
 289   operator ACE_SOCK_Stream *();
 290
 291   /// Set the server address.
 292   static void set_server_address (const ACE_INET_Addr &server_address);
 293
 294   /// Dump the state of the class.
 295   void dump () const;
 296
 297 protected:
 298   /// The address of the Token Server used by all instances of
 299   /// Token_Proxy.
 300   static ACE_INET_Addr server_address_;
 301
 302 private:
 303   ACE_TSS_Connection (const ACE_TSS_Connection &) = delete;
 304   void operator= (const ACE_TSS_Connection &) = delete;
 305 };
 306
 307 ACE_END_VERSIONED_NAMESPACE_DECL
 308
 309 #endif /* ACE_HAS_TOKENS_LIBRARY */
 310
 311 #if defined (__ACE_INLINE__)
 312 #include "ace/Remote_Tokens.inl"
 313 #endif /* __ACE_INLINE__ */
 314
 315 #include /**/ "ace/post.h"
 316
 317 #endif /* ACE_REMOTE_TOKEN_H */