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

Remote_Tokens.h

Go to the documentation of this file.
00001 /* -*- C++ -*- */
00002 
00003 //=============================================================================
00004 /**
00005  *  @file    Remote_Tokens.h
00006  *
00007  *  $Id: Remote_Tokens.h,v 1.1.1.4 2003/02/21 18:36:32 chad Exp $
00008  *
00009  *  @author Douglas C. Schmidt (schmidt@cs.wustl.edu)
00010  *  @author Tim Harrison (harrison@cs.wustl.edu)
00011  */
00012 //=============================================================================
00013 
00014 #ifndef ACE_REMOTE_MUTEX_H
00015 #define ACE_REMOTE_MUTEX_H
00016 #include "ace/pre.h"
00017 
00018 #include "ace/INET_Addr.h"
00019 
00020 #if !defined (ACE_LACKS_PRAGMA_ONCE)
00021 # pragma once
00022 #endif /* ACE_LACKS_PRAGMA_ONCE */
00023 
00024 #include "ace/SOCK_Connector.h"
00025 #include "ace/SOCK_Stream.h"
00026 #include "ace/Synch_Options.h"
00027 #include "ace/Local_Tokens.h"
00028 #include "ace/Token_Request_Reply.h"
00029 
00030 #if defined (ACE_HAS_TOKENS_LIBRARY)
00031 
00032 /**
00033  * @class ACE_Remote_Token_Proxy
00034  *
00035  * @brief Proxy for acquiring, renewing, and releasing a distributed
00036  * synchronization token.
00037  *
00038  * The Remote_Token_Proxy class implements the mechanisms for
00039  * distributed token operations.  It is similar to the
00040  * ACE_Token_Proxy.
00041  * = BUGS
00042  * Distributed sleep_hooks have not been implemented.  <owner_id>
00043  * is not implemented.
00044  */
00045 class ACE_Export ACE_Remote_Token_Proxy : public ACE_Token_Proxy
00046 {
00047 public:
00048   /// Null construction.
00049   ACE_Remote_Token_Proxy (void);
00050 
00051   /// Death.
00052   virtual ~ACE_Remote_Token_Proxy (void);
00053 
00054   /**
00055    * Same as Token_Proxy. <name> is the string uniquely identifying
00056    * the token.  <ignore_deadlock> can be 1 to disable deadlock
00057    * notifications.  <debug> prints debug messages.
00058    */
00059   int open (const ACE_TCHAR *name,
00060             int ignore_deadlock = 0,
00061             int debug = 0);
00062 
00063 
00064   /**
00065    * Open a connection with the token server.  This only need be used
00066    * when the user wishes to explicitly open a connection to check if
00067    * the server exists.  Connections are stored in the
00068    * ACE_Token_Connections singleton as thread-specific data.  That
00069    * is, every thread has only one connection that is used for all
00070    * remote tokens.
00071    */
00072   int initiate_connection (void);
00073 
00074   /**
00075    * Acquire the distributed token.  If notify is specified and the
00076    * token is already held, the owner is notified.  options contains
00077    * the timeout value for the acquire call.  The timer is kept at the
00078    * token server.  Asynchronous operations are not supported.
00079    * Returns 0 on success, -1 on failure with <errno> == problem.
00080    */
00081   virtual int acquire (int notify = 0,
00082                        void (*sleep_hook)(void *) = 0,
00083                        ACE_Synch_Options &options =
00084                        ACE_Synch_Options::synch);
00085 
00086   /**
00087    * Try to acquire the distributed token.  If the token is already
00088    * held, the call returns without queueing the caller as a waiter.
00089    * Returns 0 on success (the token was acquired), and -1 with
00090    * EWOULDBLOCK if the token was already held.
00091    */
00092   virtual int tryacquire (void (*sleep_hook)(void *) = 0);
00093 
00094   /**
00095    * Renew the token by offering to release it if there are any other
00096    * waiters, otherwise get the token back immediately.  This renew
00097    * has the same semantics as ACE_Local_Mutex release.  It is
00098    * semantically equivalent to <release> followed by <acquire>, but
00099    * it is faster.  options contains the timeout value used if renew
00100    * blocks.  As with acquire, the timer is maintained at the token
00101    * server.  If there are waiters and requeue_position == -1, the
00102    * caller is queued at the rear of the waiter list.  Otherwise,
00103    * requeue_position specifies the number of waiters to "let by"
00104    * before reacquiring the token (effectively, the position in the
00105    * waiter list.)
00106    */
00107   virtual int renew (int requeue_position = 0,
00108                      ACE_Synch_Options &options =
00109                      ACE_Synch_Options::synch);
00110 
00111   /**
00112    * Release the distributed token. Similar to ACE_Local_Mutex, if the
00113    * caller is not the owner, it is removed from the waiter list (if
00114    * applicable.) Returns 0 on success, -1 on failure with <errno> ==
00115    * problem.
00116    */
00117   virtual int release (ACE_Synch_Options &options =
00118                        ACE_Synch_Options::synch);
00119 
00120   /// Become interface compliant for ACE_Guard<>.  This has no
00121   /// functionality.
00122   virtual int remove (ACE_Synch_Options &options =
00123                       ACE_Synch_Options::synch);
00124 
00125   /// Override the default to do nothing.
00126   virtual void token_acquired (ACE_TPQ_Entry *);
00127 
00128   /// The client id of the current token holder
00129   virtual const ACE_TCHAR* owner_id (void);
00130 
00131   /**
00132    * Sets the server address for all instances of ACE_Remote_Token_Proxy
00133    * If this isn't called, the environment variable TOKEN_SERVER is
00134    * checked for the server address.  If that is not specified, all
00135    * ACE_Remote_** operations will fail.
00136    */
00137   static void set_server_address (const ACE_INET_Addr &server_address);
00138 
00139   /// Dump the state of the class.
00140   void dump (void) const;
00141 
00142 protected:
00143 
00144   /// If shadows report deadlock, go remote anyway
00145   int ignore_shadow_deadlock_;
00146 
00147   /// Perform the request and wait for the reply.
00148   int request_reply (ACE_Token_Request &request,
00149                      ACE_Synch_Options &options);
00150 };
00151 
00152 /**
00153  * @class ACE_Remote_Mutex
00154  *
00155  * @brief Proxy for acquiring, renewing, and releasing a distributed
00156  * mutex.
00157  *
00158  * This is the remote equivalent to ACE_Local_Mutex.  The
00159  * Remote_Mutex class offers methods for acquiring, renewing, and
00160  * releasing a distributed synchronization mutex.  Similar to
00161  * ACE_Local_Mutex, ACE_Remote_Token_Proxy offers recursive
00162  * acquisition, FIFO waiter ordering, and deadlock detection.  It
00163  * depends on the Token Server for its distributed synchronization
00164  * semantics.
00165  */
00166 class ACE_Export ACE_Remote_Mutex : public ACE_Remote_Token_Proxy
00167 {
00168 public:
00169   /// Null creation.  Remote_Token_Proxy::open must be called.
00170   ACE_Remote_Mutex (void);
00171 
00172   /// Calls Remote_Token_Proxy::open for you.
00173   ACE_Remote_Mutex (const ACE_TCHAR *token_name,
00174                     int ignore_deadlock = 0,
00175                     int debug = 0);
00176 
00177   /// Dump the state of the class.
00178   void dump (void) const;
00179 
00180   /// Return deep copy.
00181   virtual ACE_Token_Proxy *clone (void) const;
00182 
00183 protected:
00184   /// Make the correct type of ACE_Tokens.
00185   /// This is called by the ACE_Token_Manager.
00186   virtual ACE_Tokens *create_token (const ACE_TCHAR *name);
00187 };
00188 
00189 /**
00190  * @class ACE_Remote_RLock
00191  *
00192  * @brief Proxy for acquiring, renewing, and releasing a distributed
00193  * readers lock.
00194  *
00195  * This is the remote equivalent to ACE_Local_RLock. Multiple
00196  * readers can hold the lock simultaneously when no writers have
00197  * the lock.  Alternatively, when a writer holds the lock, no other
00198  * participants (readers or writers) may hold the lock.
00199  * ACE_Remote_RLock depends on the ACE Token Server for its
00200  * distributed synchronization semantics.
00201  */
00202 class ACE_Export ACE_Remote_RLock : public ACE_Remote_Token_Proxy
00203 {
00204 public:
00205   ACE_Remote_RLock (void);
00206 
00207   ACE_Remote_RLock (const ACE_TCHAR *token_name,
00208                     int ignore_deadlock = 0,
00209                     int debug = 0);
00210 
00211   ACE_Remote_RLock (const ACE_Remote_RLock &mutex);
00212 
00213   /// Dump the state of the class.
00214   void dump (void) const;
00215 
00216   /// Returns ACE_RW_Token::RLOCK;
00217   virtual int type (void) const;
00218 
00219   /// Return deep copy.
00220   virtual ACE_Token_Proxy *clone (void) const;
00221 
00222 protected:
00223   /// Make the correct type of ACE_Tokens.  This is called by the Token
00224   /// Manager.
00225   virtual ACE_Tokens *create_token (const ACE_TCHAR *name);
00226 };
00227 
00228 /**
00229  * @class ACE_Remote_WLock
00230  *
00231  * @brief Proxy for acquiring, renewing, and releasing a distributed
00232  * writers lock.
00233  *
00234  * Shields applications from details of interacting with the
00235  * ACE_Token_Server.  The token_name_ is just the string that the
00236  * Token Server uses to identify the token.  The client_id_ (also
00237  * used by the Token Server,) identifies the owner of the token and
00238  * is used for deadlock detection.
00239  */
00240 class ACE_Export ACE_Remote_WLock : public ACE_Remote_Token_Proxy
00241 {
00242 public:
00243   ACE_Remote_WLock (void);
00244 
00245   ACE_Remote_WLock (const ACE_TCHAR *token_name,
00246                     int ignore_deadlock = 0,
00247                     int debug = 0);
00248 
00249   ACE_Remote_WLock (const ACE_Remote_WLock &mutex);
00250 
00251   /// Dump the state of the class.
00252   void dump (void) const;
00253 
00254   /// Returns ACE_RW_Token::WLOCK;
00255   virtual int type (void) const;
00256 
00257   /// Return deep copy.
00258   virtual ACE_Token_Proxy *clone (void) const;
00259 
00260 protected:
00261   /// Make the correct type of ACE_Tokens.  This is called by the Token
00262   /// Manager.
00263   virtual ACE_Tokens *create_token (const ACE_TCHAR *name);
00264 };
00265 
00266 /**
00267  * @class ACE_TSS_Connection
00268  *
00269  * @brief Class for providing a connection per thread.
00270  *
00271  * ACE_TSS_Connection provides a single access point for all
00272  * threads to access thread-specific connections.  This prevents
00273  * resource-sharing problems such as thread serialization.
00274  */
00275 class ACE_Export ACE_TSS_Connection : public ACE_TSS<ACE_SOCK_Stream>
00276 {
00277 public:
00278   // Necessary to make some compilers work...
00279   ACE_TSS_Connection (void);
00280   ~ACE_TSS_Connection (void);
00281 
00282   /// Retrieve the thread's connection
00283   ACE_SOCK_Stream *get_connection (void);
00284 
00285   /// Factory Method that creates a new SOCK Stream.
00286   virtual ACE_SOCK_Stream *make_TSS_TYPE (void) const;
00287 
00288   /// Inheritence and operator overloading don't mix.  Redefine this
00289   /// from ACE_TSS so that we can use it.
00290   operator ACE_SOCK_Stream *(void);
00291 
00292   /// Set the server address.
00293   static void set_server_address (const ACE_INET_Addr &server_address);
00294 
00295   /// Dump the state of the class.
00296   void dump (void) const;
00297 
00298 protected:
00299   /// The address of the Token Server used by all instances of
00300   /// Token_Proxy.
00301   static ACE_INET_Addr server_address_;
00302 
00303 private:
00304   /// Private: should not be used
00305   ACE_TSS_Connection (const ACE_TSS_Connection &);
00306   void operator= (const ACE_TSS_Connection &);
00307 };
00308 
00309 #endif /* ACE_HAS_TOKENS_LIBRARY */
00310 
00311 #if defined (__ACE_INLINE__)
00312 #include "ace/Remote_Tokens.i"
00313 #endif /* __ACE_INLINE__ */
00314 
00315 #include "ace/post.h"
00316 #endif /* ACE_REMOTE_TOKEN_H */

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