ACE/ace/Framework_Component.h

   1 // -*- C++ -*-
   2
   3 //=============================================================================
   4 /**
   5  *  @file    Framework_Component.h
   6  *
   7  * A prototype mechanism that allows framework components, singletons
   8  * such as ACE_Reactor, ACE_Proactor, etc, to be registered with a
   9  * central repository managed by the ACE_Object_Manager or
  10  * ACE_Service_Config that will handle destruction.
  11  *
  12  * This technique obviates changing ACE_Object_Manager and
  13  * ACE_Service_Config everytime a new framework is added.  Which also
  14  * means that unused framework components don't need to linked into
  15  * the final application which is important for applications with
  16  * stringent footprint requirements.
  17  *
  18  * Framework components need only provide a static method,
  19  * close_singleton() and add the ACE_REGISTER_FRAMEWORK_COMPONENT macro
  20  * call to their instance() methods in order to participate.  Components
  21  * that don't have a close_singleton() method can also participate via
  22  * template specialization of ACE_Framework_Component_T.
  23  *
  24  * This design uses the External Polymorphism pattern to avoid having
  25  * to derive all framework components from a common base class that
  26  * has virtual methods (this is crucial to avoid unnecessary overhead),
  27  * and is based on the dump debugging implementation found in
  28  * <ace/Dump.h>.
  29  *
  30  *  @author Don Hinton <dhinton@ieee.org>.
  31  */
  32 //=============================================================================
  33
  34 #ifndef ACE_FRAMEWORK_COMPONENT_H
  35 #define ACE_FRAMEWORK_COMPONENT_H
  36 #include /**/ "ace/pre.h"
  37
  38 #include /**/ "ace/ACE_export.h"
  39
  40 #if !defined (ACE_LACKS_PRAGMA_ONCE)
  41 # pragma once
  42 #endif /* ACE_LACKS_PRAGMA_ONCE */
  43
  44 #include "ace/os_include/os_signal.h"
  45 #include "ace/Thread_Mutex.h"
  46 #include "ace/Copy_Disabled.h"
  47 #include "ace/Synch_Traits.h"
  48
  49 #define ACE_DEFAULT_FRAMEWORK_REPOSITORY_SIZE 1024
  50
  51 ACE_BEGIN_VERSIONED_NAMESPACE_DECL
  52
  53 /**
  54  * @class ACE_Framework_Component
  55  *
  56  * @brief Base class that defines a uniform interface for all managed
  57  * framework components.
  58  */
  59 class ACE_Export ACE_Framework_Component : private ACE_Copy_Disabled
  60 {
  61 public:
  62   friend class ACE_Framework_Repository;
  63
  64   /// Constructor.
  65   ACE_Framework_Component (void *_this,
  66                            const ACE_TCHAR *dll_name = 0,
  67                            const ACE_TCHAR *name = 0);
  68
  69   /// Close the contained singleton.
  70   virtual void close_singleton () = 0;
  71
  72 protected:
  73   /// Destructor.
  74   virtual ~ACE_Framework_Component ();
  75
  76 private:
  77   /// Pointer to the actual component.
  78   const void *this_;
  79
  80   /// Library associated with this component
  81   const ACE_TCHAR *dll_name_;
  82
  83   /// Component name
  84   const ACE_TCHAR *name_;
  85 };
  86
  87 /**
  88  * @class ACE_Framework_Repository
  89  *
  90  * @brief Contains all framework components used by an application.
  91  *
  92  * This class contains a vector of ACE_Framework_Component *'s.  On
  93  * destruction, framework components are destroyed in the reverse order
  94  * that they were added originally.
  95  */
  96 class ACE_Export ACE_Framework_Repository : private ACE_Copy_Disabled
  97 {
  98 public:
  99   // This is just to silence a compiler warning about no public ctors
 100   friend class ACE_Framework_Component;
 101
 102   enum
 103   {
 104     DEFAULT_SIZE = ACE_DEFAULT_FRAMEWORK_REPOSITORY_SIZE
 105   };
 106
 107   /// Close down the repository and free up dynamically allocated
 108   /// resources.
 109   ~ACE_Framework_Repository ();
 110
 111   /// Initialize the repository.
 112   int open (int size = DEFAULT_SIZE);
 113
 114   /// Close down the repository and free up dynamically allocated
 115   /// resources, also called by dtor.
 116   int close ();
 117
 118   /// Get pointer to a process-wide ACE_Framework_Repository.
 119   static ACE_Framework_Repository *instance
 120     (int size = ACE_Framework_Repository::DEFAULT_SIZE);
 121
 122   /// Delete the dynamically allocated Singleton.
 123   static void close_singleton ();
 124
 125   // = Search structure operations (all acquire locks as necessary).
 126
 127   /// Insert a new component.  Returns -1 when the repository is full
 128   /// and 0 on success.
 129   int register_component (ACE_Framework_Component *fc);
 130
 131   /// Remove a component.  Returns -1 on error or if component not found
 132   /// and 0 on success.
 133   int remove_component (const ACE_TCHAR *name);
 134
 135   /// Remove all components associated with a particular dll.
 136   int remove_dll_components (const ACE_TCHAR *dll_name);
 137
 138   /// Return the current size of the repository.
 139   int current_size () const;
 140
 141   /// Return the total size of the repository.
 142   int total_size () const;
 143
 144   /// Dump the state of an object.
 145   void dump () const;
 146
 147   /// Declare the dynamic allocation hooks.
 148   ACE_ALLOC_HOOK_DECLARE;
 149
 150 protected:
 151   /// Initialize the repository.
 152   ACE_Framework_Repository (int size = ACE_Framework_Repository::DEFAULT_SIZE);
 153
 154 private:
 155   /// Actually removes the dll components, must be called with locks held.
 156   int remove_dll_components_i (const ACE_TCHAR *dll_name);
 157
 158   /// Compact component_vector_ after components have been removed__maintains
 159   /// order.
 160   void compact ();
 161
 162 private:
 163   /// Contains all the framework components.
 164   ACE_Framework_Component **component_vector_ {};
 165
 166   /// Current number of components.
 167   int current_size_;
 168
 169   /// Maximum number of components.
 170   int total_size_;
 171
 172   /// Pointer to a process-wide ACE_Framework_Repository.
 173   static ACE_Framework_Repository *repository_;
 174
 175   /// Flag set when repository is the process of shutting down.  This
 176   /// is necessary to keep from self-deadlocking since some of
 177   /// the components might make calls back to the repository to
 178   /// unload their components, e.g., ACE_DLL_Manager.
 179   static sig_atomic_t shutting_down_;
 180
 181   /// Synchronization variable for the repository
 182   ACE_SYNCH_MUTEX lock_;
 183 };
 184
 185 ACE_END_VERSIONED_NAMESPACE_DECL
 186
 187 #if defined (__ACE_INLINE__)
 188 #include "ace/Framework_Component.inl"
 189 #endif /* __ACE_INLINE__ */
 190
 191 // Include the templates classes at this point.
 192 #include "ace/Framework_Component_T.h"
 193
 194 #include /**/ "ace/post.h"
 195 #endif /* ACE_FRAMEWORK_COMPONENT_H */