ACE/netsvcs/lib/Token_Handler.h

   1 /* -*- C++ -*- */
   2
   3 //=============================================================================
   4 /**
   5  *  @file    Token_Handler.h
   6  *
   7  *  @author Douglas C. Schmidt (d.schmidt@vanderbilt.edu)
   8  *          Tim Harrison (harrison@cs.wustl.edu)
   9  */
  10 //=============================================================================
  11
  12 #ifndef ACE_TOKEN_HANDLER_H
  13 #define ACE_TOKEN_HANDLER_H
  14
  15 #include "ace/Acceptor.h"
  16
  17 #if !defined (ACE_LACKS_PRAGMA_ONCE)
  18 # pragma once
  19 #endif /* ACE_LACKS_PRAGMA_ONCE */
  20
  21 #include "ace/SOCK_Acceptor.h"
  22 #include "ace/Local_Tokens.h"
  23 #include "ace/Token_Collection.h"
  24 #include "ace/Token_Request_Reply.h"
  25 #include "ace/svc_export.h"
  26
  27 #if defined (ACE_HAS_TOKENS_LIBRARY)
  28
  29 /**
  30  * @class ACE_Token_Handler
  31  *
  32  * @brief Product object created by an <ACE_Token_Acceptor>.  A
  33  * <Token_Handler> exchanges messages with a <Token_Proxy> object
  34  * on the client-side.
  35  *
  36  * This class is the main workhorse of the ACE Token service.  It
  37  * receives token operation requests from remote clients and turns
  38  * them into calls on local tokens (acquire, release, renew, and
  39  * remove).  In OMG CORBA terms, it is an object adapter. It also
  40  * schedules and handles timeouts that are used to support "timed
  41  * waits."  Clients used timed waits to bound the amount of time
  42  * they block trying to get a token.
  43  */
  44 class ACE_Svc_Export ACE_Token_Handler : public ACE_Svc_Handler<ACE_SOCK_STREAM, ACE_NULL_SYNCH>
  45 {
  46
  47 public:
  48   /// Default constructor.
  49   ACE_Token_Handler (ACE_Thread_Manager * = 0);
  50
  51   // = Accessor and mutator methods.
  52
  53   // = Remote operations "exported" to a client.
  54   /**
  55    * Try to acquire the token.
  56    * Precondition: client *may* hold the token already (i.e.,
  57    * supports recursive acquisitions).
  58    */
  59   virtual int acquire (ACE_Token_Proxy *proxy);
  60
  61   /// Try to acquire the token.
  62   virtual int try_acquire (ACE_Token_Proxy *proxy);
  63
  64   /// Release the token and allow the next client that is waiting to
  65   /// proceed.  Preconditions: client must hold the token.
  66   virtual int release (ACE_Token_Proxy *proxy);
  67
  68   /// Yield the token if any clients are waiting, otherwise keep the
  69   /// token.  Preconditions: client must hold the token.
  70   virtual int renew (ACE_Token_Proxy *proxy);
  71
  72   /**
  73    * Remove the specified token from the Token_Map.  Preconditions:
  74    * ACE_Token must exist.  @@ Any other preconditions, e.g., must
  75    * client hold token, must there be no waiters, etc.?
  76    */
  77   virtual int remove (ACE_Token_Proxy *proxy);
  78
  79   /// Called by TS_[Mutex,RLock,WLock] when we hold the mutex and
  80   /// someone wants it.
  81   void sleep_hook (void);
  82
  83   /// Called by TS_[Mutex,RLock,WLock] when we are waiting and acquire
  84   /// the mutex.
  85   void token_acquired (ACE_TPQ_Entry *);
  86
  87 protected:
  88   // = Low level routines for framing requests, dispatching
  89   // operations, and returning replies.
  90
  91   /// Our connection has been closed.
  92   virtual int abandon (int send_error);
  93
  94   /// Receive, frame, and decode the client's request.
  95   virtual int recv_request (void);
  96
  97   /// Dispatch the appropriate operation to handle the client's
  98   /// request.
  99   virtual int dispatch (void);
 100
 101   /// Create and send a reply to the client.
 102   virtual int send_reply (ACE_UINT32 errnum);
 103
 104   // = Demultiplexing hooks.
 105   /// Callback method invoked by the <ACE_Reactor> when client events
 106   /// arrive.
 107   virtual int handle_input (ACE_HANDLE);
 108
 109   // = Timer hook.
 110   /// Enable clients to limit the amount of time they wait for a token.
 111   virtual int handle_timeout (const ACE_Time_Value &tv, const void *arg);
 112
 113   /// return a proxy for the calling client_id and token name.
 114   ACE_Token_Proxy *get_proxy (void);
 115
 116 private:
 117
 118   /// Switches on the type of token_request_ and creates a new
 119   /// Token_Proxy.
 120   virtual ACE_Token_Proxy *create_proxy (void);
 121
 122   /// Keeps track of the synchronization options (i.e., the timeout
 123   /// interval).
 124   ACE_Synch_Options request_options_;
 125
 126   /// collection of the client's token proxies.
 127   ACE_Token_Collection collection_;
 128
 129   /// ID returned by the Reactor that is used to kill registered timers
 130   /// when a token operation times out.
 131   long timeout_id_;
 132
 133   /// Cache request from the client.
 134   ACE_Token_Request token_request_;
 135
 136   /// Cache reply to the client.
 137   ACE_Token_Reply token_reply_;
 138 };
 139
 140 // = DESCRIPTION of ACE_TS_* classes:
 141 //     When Tokens are released, waiting token proxies are notified
 142 //     when the releasing thread calls token_acquired on the waiting
 143 //     proxy.  The Token Server specializes ACE_Token_Proxy to
 144 //     redefine the implementation of token_acquired.  When
 145 //     token_acquired is called, the Token_Handler can then send the
 146 //     response back over the socket connection to unblock the
 147 //     client side.
 148 //     Since only the Token_Handler uses ACE_TS_Mutex, we've moved
 149 //     the definition to the .cpp file.
 150
 151 /**
 152  * @class ACE_TS_Mutex
 153  *
 154  * @brief ACE_TS_Mutex  -- ACE_*T*oken_*S*erver_Mutex
 155  */
 156 class ACE_TS_Mutex : public ACE_Local_Mutex
 157 {
 158
 159 public:
 160   /// Creation.
 161   ACE_TS_Mutex (const ACE_TCHAR *name,
 162                 ACE_Token_Handler *th);
 163
 164 protected:
 165   /// Somebody wants our token!
 166   virtual void sleep_hook (void);
 167
 168   /**
 169    * We've been taken off the waiters list and given the token!  Call
 170    * the Token_Handler associated at construction, so it can tell the
 171    * remote client.
 172    */
 173   virtual void token_acquired (ACE_TPQ_Entry *);
 174
 175   /// Duplication.
 176   ACE_TS_Mutex (const ACE_TS_Mutex &);
 177
 178   /// Return a deep copy.
 179   virtual ACE_Token_Proxy *clone (void) const;
 180
 181 private:
 182   /// The Token Handler associated with this proxy.  Set at
 183   /// construction and notified when blocking acquires succeed.
 184   ACE_Token_Handler* th_;
 185 };
 186
 187 /**
 188  * @class ACE_TS_RLock
 189  *
 190  * @brief ACE_TS_RLock  -- ACE_*T*oken_*S*erver_RLock
 191  */
 192 class ACE_TS_RLock : public ACE_Local_RLock
 193 {
 194 public:
 195   /// Creation.
 196   ACE_TS_RLock (const ACE_TCHAR *name,
 197                 ACE_Token_Handler *th);
 198
 199 protected:
 200   /// Somebody wants our token!
 201   virtual void sleep_hook (void);
 202
 203   /**
 204    * We've been taken off the waiters list and given the token!  Call
 205    * the Token_Handler associated at construction, so it can tell the
 206    * remote client.
 207    */
 208   virtual void token_acquired (ACE_TPQ_Entry *);
 209
 210   /// Duplication.
 211   ACE_TS_RLock (const ACE_TS_RLock&);
 212
 213   /// Return a deep copy.
 214   virtual ACE_Token_Proxy *clone (void) const;
 215
 216 private:
 217   /// the Token Handler associated with this proxy.  Set at
 218   /// construction and notified when blocking acquires succeed.
 219   ACE_Token_Handler* th_;
 220 };
 221
 222 /**
 223  * @class ACE_TS_WLock
 224  *
 225  * @brief ACE_TS_WLock  -- ACE_*T*oken_*S*erver_WLock
 226  */
 227 class ACE_TS_WLock : public ACE_Local_WLock
 228 {
 229 public:
 230   /// Creation.
 231   ACE_TS_WLock (const ACE_TCHAR *name,
 232                 ACE_Token_Handler *th);
 233
 234 protected:
 235   /// Somebody wants our token!
 236   virtual void sleep_hook (void);
 237
 238   /**
 239    * We've been taken off the waiters list and given the token!  Call
 240    * the Token_Handler associated at construction, so it can tell the
 241    * remote client.
 242    */
 243   virtual void token_acquired (ACE_TPQ_Entry *);
 244
 245   /// Duplication.
 246   ACE_TS_WLock (const ACE_TS_WLock&);
 247
 248   /// Return a deep copy.
 249   virtual ACE_Token_Proxy *clone (void) const;
 250
 251 private:
 252   /// the Token Handler associated with this proxy.  Set at
 253   /// construction and notified when blocking acquires succeed.
 254   ACE_Token_Handler* th_;
 255 };
 256
 257 /**
 258  * @class ACE_Token_Acceptor
 259  *
 260  * @brief This class contains the service-specific methods that can't
 261  * easily be factored into the <ACE_Strategy_Acceptor>.
 262  */
 263 class ACE_Token_Acceptor : public ACE_Strategy_Acceptor<ACE_Token_Handler, ACE_SOCK_ACCEPTOR>
 264 {
 265 public:
 266   /// Dynamic linking hook.
 267   virtual int init (int argc, ACE_TCHAR *argv[]);
 268
 269   /// Parse svc.conf arguments.
 270   int parse_args (int argc, ACE_TCHAR *argv[]);
 271
 272 private:
 273   /// The scheduling strategy is designed for Reactive services.
 274   ACE_Schedule_All_Reactive_Strategy<ACE_Token_Handler> scheduling_strategy_;
 275 };
 276
 277 ACE_SVC_FACTORY_DECLARE (ACE_Token_Acceptor)
 278
 279 #endif /* ACE_HAS_TOKENS_LIBRARY */
 280 #endif /* ACE_TOKEN_HANDLER_H */