ACE/ace/Service_Repository.h

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