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 ();
  68
  69   /// Close down the repository and free up dynamically allocated
  70   /// resources.
  71   int close ();
  72
  73   /// Finalize all the services by calling fini() and deleting
  74   /// dynamically allocated services.
  75   int fini ();
  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 ();
  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 () const;
 130
 131   /// Dump the state of an object.
 132   void dump () const;
 133
 134   /// Returns a reference to the lock used by the ACE_Service_Repository
 135   ACE_SYNCH_RECURSIVE_MUTEX &lock () const;
 136
 137   /// Declare the dynamic allocation hooks.
 138   ACE_ALLOC_HOOK_DECLARE;
 139
 140 protected:
 141   friend class ACE_Service_Type_Dynamic_Guard;
 142
 143   /// Remove an existing service record. It requires @a sr != 0, which
 144   /// receives the service record pointer and the caller is
 145   /// responsible for properly disposing of it.
 146   int remove_i (const ACE_TCHAR[], ACE_Service_Type **sr);
 147
 148   /**
 149    * Locate a named entry in the service table, optionally ignoring
 150    * suspended entries.
 151    *
 152    * @param service_name The name of the service to search for.
 153    * @param slot         Receives the position index of the service if it
 154    *                     is found. Contents are meaningless if this method
 155    *                     returns -1.
 156    * @param srp          Optional; if not 0, it is a pointer to a location
 157    *                     to receive the ACE_Service_Type pointer for the
 158    *                     located service. Meaningless if this method
 159    *                     returns -1.
 160    * @param ignore_suspended If true, the search ignores suspended services.
 161    *
 162    * @retval  0 Named service was located; index in the table is set in
 163    *            @a slot.
 164    * @retval -1 Named service was not found.
 165    * @retval -2 Named service was found, but is suspended and
 166    *            @a ignore_suspended is true.
 167    */
 168   int find_i (const ACE_TCHAR service_name[],
 169               size_t &slot,
 170               const ACE_Service_Type **srp = 0,
 171               bool ignore_suspended = true) const;
 172
 173   /// @brief Relocate (static) services to another DLL.
 174   ///
 175   /// If any have been registered in the context of a "forward
 176   /// declaration" guard, those really aren't static services. Their
 177   /// code is in the DLL's code segment, or in one of the dependent
 178   /// DLLs. Therefore, such services need to be associated with the
 179   /// proper DLL in order to prevent failures upon finalization. The
 180   /// method locks the repo.
 181   ///
 182   /// Works by having the service type keep a reference to a specific
 183   /// DLL. No locking, caller makes sure calling it is safe. You can
 184   /// forcefully relocate any DLLs in the given range, not only the
 185   /// static ones - but that will cause Very Bad Things (tm) to happen.
 186   int relocate_i (size_t begin,
 187                   size_t end,
 188                   const ACE_DLL &adll);
 189
 190   /// The typedef of the array used to store the services.
 191 #if defined (ACE_HAS_ALLOC_HOOKS)
 192   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;
 193 #else
 194   typedef ACE_Array_Map<size_t, const ACE_Service_Type*> array_type;
 195 #endif /* ACE_HAS_ALLOC_HOOKS */
 196
 197   /// Contains all the configured services.
 198   array_type service_array_;
 199
 200   /// Pointer to a process-wide ACE_Service_Repository.
 201   static ACE_Service_Repository *svc_rep_;
 202
 203   /// Must delete the @c svc_rep_ if true.
 204   static bool delete_svc_rep_;
 205
 206   /// Synchronization variable for the ACE_Service_Repository.
 207   mutable ACE_SYNCH_RECURSIVE_MUTEX lock_;
 208 };
 209
 210 /**
 211  * @class ACE_Service_Repository_Iterator
 212  *
 213  * @brief Iterate through the ACE_Service_Repository.
 214  *
 215  * Make sure not to delete entries as the iteration is going on
 216  * since this class is not designed as a robust iterator.
 217  */
 218 class ACE_Export ACE_Service_Repository_Iterator
 219 {
 220 public:
 221   /// Constructor initializes the iterator.
 222   ACE_Service_Repository_Iterator (ACE_Service_Repository &sr,
 223                                    bool ignored_suspended = true);
 224
 225   /// Destructor.
 226   ~ACE_Service_Repository_Iterator ();
 227
 228
 229 public:
 230   // = Iteration methods.
 231
 232   /// Pass back the @a next_item that hasn't been seen in the repository.
 233   /// Returns 0 when all items have been seen, else 1.
 234   int next (const ACE_Service_Type *&next_item);
 235
 236   /// Returns 1 when all items have been seen, else 0.
 237   int done () const;
 238
 239   /// Move forward by one element in the repository.  Returns 0 when all the
 240   /// items in the set have been seen, else 1.
 241   int advance ();
 242
 243   /// Dump the state of an object.
 244   void dump () const;
 245
 246   /// Declare the dynamic allocation hooks.
 247   ACE_ALLOC_HOOK_DECLARE;
 248
 249 private:
 250   bool valid () const;
 251
 252 private:
 253   ACE_Service_Repository_Iterator (const ACE_Service_Repository_Iterator&);
 254
 255   /// Reference to the Service Repository we are iterating over.
 256   ACE_Service_Repository &svc_rep_;
 257
 258   /// Next index location that we haven't yet seen.
 259   size_t next_;
 260
 261   /// Are we ignoring suspended services?
 262   bool const ignore_suspended_;
 263 };
 264
 265 ACE_END_VERSIONED_NAMESPACE_DECL
 266
 267 #if defined (__ACE_INLINE__)
 268 #include "ace/Service_Repository.inl"
 269 #endif /* __ACE_INLINE__ */
 270
 271 #include /**/ "ace/post.h"
 272
 273 #endif /* _SERVICE_REPOSITORY_H */