dep/ACE_wrappers/ace/Service_Repository.h

   1 // -*- C++ -*-
   2
   3 //=============================================================================
   4 /**
   5  *  @file    Service_Repository.h
   6  *
   7  *  $Id: Service_Repository.h 81388 2008-04-23 14:02:05Z johnnyw $
   8  *
   9  *  @author Douglas C. Schmidt <schmidt@cs.wustl.edu>
  10  */
  11 //=============================================================================
  12
  13 #ifndef ACE_SERVICE_REPOSITORY_H
  14 #define ACE_SERVICE_REPOSITORY_H
  15
  16 #include /**/ "ace/pre.h"
  17
  18 #include /**/ "ace/ACE_export.h"
  19
  20 #if !defined (ACE_LACKS_PRAGMA_ONCE)
  21 # pragma once
  22 #endif /* ACE_LACKS_PRAGMA_ONCE */
  23
  24 #include "ace/Default_Constants.h"
  25 #include "ace/Recursive_Thread_Mutex.h"
  26
  27 ACE_BEGIN_VERSIONED_NAMESPACE_DECL
  28
  29 class ACE_Service_Type;
  30 class ACE_DLL;
  31
  32 #define ACE_Component_Repository ACE_Service_Repository
  33 /**
  34  * @class ACE_Service_Repository
  35  *
  36  * @brief Contains all the services offered by a Service
  37  * Configurator-based application.
  38  *
  39  * This class contains a vector of <ACE_Service_Types> *'s and
  40  * allows an administrative entity to centrally manage and
  41  * control the behavior of application services.  Note that if
  42  * services are removed from the middle of the repository the
  43  * order won't necessarily be maintained since the <remove>
  44  * method performs compaction.  However, the common case is not
  45  * to remove services, so typically they are deleted in the
  46  * reverse order that they were added originally.
  47  */
  48 class ACE_Export ACE_Service_Repository
  49 {
  50 public:
  51   friend class ACE_Service_Repository_Iterator;
  52
  53   enum
  54   {
  55     DEFAULT_SIZE = ACE_DEFAULT_SERVICE_REPOSITORY_SIZE
  56   };
  57
  58   // = Initialization and termination methods.
  59   /// Initialize the repository.
  60   ACE_Service_Repository (void);
  61
  62   /// Initialize the repository.
  63   ACE_Service_Repository (size_t size);
  64
  65   /// Initialize the repository.
  66   int open (size_t size = DEFAULT_SIZE);
  67
  68   /// Close down the repository and free up dynamically allocated
  69   /// resources.
  70   ~ACE_Service_Repository (void);
  71
  72   /// Close down the repository and free up dynamically allocated
  73   /// resources.
  74   int close (void);
  75
  76   /// Finalize all the services by calling <fini> and deleting
  77   /// dynamically allocated services.
  78   int fini (void);
  79
  80   /// Get pointer to a process-wide ACE_Service_Repository.
  81   static ACE_Service_Repository * instance
  82     (size_t size = ACE_Service_Repository::DEFAULT_SIZE);
  83
  84   /// Set pointer to a process-wide ACE_Service_Repository and return
  85   /// existing pointer.
  86   static ACE_Service_Repository *instance (ACE_Service_Repository *);
  87
  88   /// Delete the dynamically allocated Singleton.
  89   static void close_singleton (void);
  90
  91   // = Search structure operations (all acquire locks as necessary).
  92
  93   /// Insert a new service record.  Returns -1 when the service repository
  94   /// is full and 0 on success.
  95   int insert (const ACE_Service_Type *);
  96
  97   /**
  98    * Locate a named entry in the service table, optionally ignoring
  99    * suspended entries.
 100    *
 101    * @param service_name The name of the service to search for.
 102    * @param srp          Optional; if not 0, it is a pointer to a location
 103    *                     to receive the ACE_Service_Type pointer for the
 104    *                     located service. Meaningless if this method
 105    *                     returns -1.
 106    * @param ignore_suspended If true, the search ignores suspended services.
 107    *
 108    * @retval  0 Named service was located.
 109    * @retval -1 Named service was not found.
 110    * @retval -2 Named service was found, but is suspended and
 111    *            @a ignore_suspended is true.
 112    */
 113   int find (const ACE_TCHAR name[],
 114             const ACE_Service_Type **srp = 0,
 115             bool ignore_suspended = true) const;
 116
 117   /// Remove an existing service record. If @a sr == 0, the service record
 118   /// is deleted before control is returned to the caller. If @a sr != 0,
 119   /// the service's record is removed from the repository, but not deleted;
 120   /// *sr receives the service record pointer and the caller is responsible
 121   /// for properly disposing of it.
 122   int remove (const ACE_TCHAR[], ACE_Service_Type **sr = 0);
 123
 124   // = Liveness control
 125   /// Resume a service record.
 126   int resume (const ACE_TCHAR[], const ACE_Service_Type ** = 0);
 127
 128   /// Suspend a service record.
 129   int suspend (const ACE_TCHAR[], const ACE_Service_Type ** = 0);
 130
 131   /// Return the current size of the repository.
 132   size_t current_size (void) const;
 133
 134   /// Return the total size of the repository.
 135   size_t total_size (void) const;
 136
 137   /// Dump the state of an object.
 138   void dump (void) const;
 139
 140   /// Declare the dynamic allocation hooks.
 141   ACE_ALLOC_HOOK_DECLARE;
 142
 143 private:
 144
 145   friend class ACE_Service_Type_Dynamic_Guard;
 146
 147   /// Remove an existing service record. It requires @a sr != 0, which
 148   /// receives the service record pointer and the caller is
 149   /// responsible for properly disposing of it.
 150   int remove_i (const ACE_TCHAR[], ACE_Service_Type **sr);
 151
 152   /**
 153    * Locate a named entry in the service table, optionally ignoring
 154    * suspended entries.
 155    *
 156    * @param service_name The name of the service to search for.
 157    * @param slot         Receives the position index of the service if it
 158    *                     is found. Contents are meaningless if this method
 159    *                     returns -1.
 160    * @param srp          Optional; if not 0, it is a pointer to a location
 161    *                     to receive the ACE_Service_Type pointer for the
 162    *                     located service. Meaningless if this method
 163    *                     returns -1.
 164    * @param ignore_suspended If true, the search ignores suspended services.
 165    *
 166    * @retval  0 Named service was located; index in the table is set in
 167    *            @a slot.
 168    * @retval -1 Named service was not found.
 169    * @retval -2 Named service was found, but is suspended and
 170    *            @a ignore_suspended is true.
 171    */
 172   int find_i (const ACE_TCHAR service_name[],
 173               size_t &slot,
 174               const ACE_Service_Type **srp = 0,
 175               bool ignore_suspended = true) const;
 176
 177   /// @brief Relocate (static) services to another DLL.
 178   ///
 179   /// If any have been registered in the context of a "forward
 180   /// declaration" guard, those really aren't static services. Their
 181   /// code is in the DLL's code segment, or in one of the dependent
 182   /// DLLs. Therefore, such services need to be associated with the
 183   /// proper DLL in order to prevent failures upon finalization. The
 184   /// method locks the repo.
 185   ///
 186   /// Works by having the service type keep a reference to a specific
 187   /// DLL. No locking, caller makes sure calling it is safe. You can
 188   /// forcefully relocate any DLLs in the given range, not only the
 189   /// static ones - but that will cause Very Bad Things (tm) to happen.
 190
 191   int relocate_i (size_t begin,
 192                   size_t end,
 193                   const ACE_DLL &adll);
 194
 195   /// Contains all the configured services.
 196   const ACE_Service_Type **service_vector_;
 197
 198   /// Current number of services.
 199   size_t current_size_;
 200
 201   /// Maximum number of services.
 202   size_t total_size_;
 203
 204   /// Pointer to a process-wide ACE_Service_Repository.
 205   static ACE_Service_Repository *svc_rep_;
 206
 207   /// Must delete the <svc_rep_> if true.
 208   static bool delete_svc_rep_;
 209
 210 #if defined (ACE_MT_SAFE) && (ACE_MT_SAFE != 0)
 211   /// Synchronization variable for the MT_SAFE Repository
 212   mutable ACE_Recursive_Thread_Mutex lock_;
 213 #endif /* ACE_MT_SAFE */
 214 };
 215
 216 /**
 217  * @class ACE_Service_Repository_Iterator
 218  *
 219  * @brief Iterate through the ACE_Service_Repository.
 220  *
 221  * Make sure not to delete entries as the iteration is going on
 222  * since this class is not designed as a robust iterator.
 223  */
 224 class ACE_Export ACE_Service_Repository_Iterator
 225 {
 226 public:
 227   // = Initialization and termination methods.
 228   /// Constructor initializes the iterator.
 229   ACE_Service_Repository_Iterator (ACE_Service_Repository &sr,
 230                                    int ignored_suspended = 1);
 231
 232   /// Destructor.
 233   ~ACE_Service_Repository_Iterator (void);
 234
 235
 236 public:
 237   // = Iteration methods.
 238
 239   /// Pass back the <next_item> that hasn't been seen in the repository.
 240   /// Returns 0 when all items have been seen, else 1.
 241   int next (const ACE_Service_Type *&next_item);
 242
 243   /// Returns 1 when all items have been seen, else 0.
 244   int done (void) const;
 245
 246   /// Move forward by one element in the repository.  Returns 0 when all the
 247   /// items in the set have been seen, else 1.
 248   int advance (void);
 249
 250   /// Dump the state of an object.
 251   void dump (void) const;
 252
 253   /// Declare the dynamic allocation hooks.
 254   ACE_ALLOC_HOOK_DECLARE;
 255
 256 private:
 257   bool valid (void) const;
 258
 259 private:
 260   ACE_Service_Repository_Iterator (const ACE_Service_Repository_Iterator&);
 261
 262   /// Reference to the Service Repository we are iterating over.
 263   ACE_Service_Repository &svc_rep_;
 264
 265   /// Next index location that we haven't yet seen.
 266   size_t next_;
 267
 268   /// Are we ignoring suspended services?
 269   bool ignore_suspended_;
 270 };
 271
 272 ACE_END_VERSIONED_NAMESPACE_DECL
 273
 274 #if defined (__ACE_INLINE__)
 275 #include "ace/Service_Repository.inl"
 276 #endif /* __ACE_INLINE__ */
 277
 278 #include /**/ "ace/post.h"
 279
 280 #endif /* _SERVICE_REPOSITORY_H */