Main Page   Class Hierarchy   Alphabetical List   Compound List   File List   Compound Members   File Members   Related Pages  

Service_Config.h

Go to the documentation of this file.
00001 // -*- C++ -*-
00002 
00003 //=============================================================================
00004 /**
00005  *  @file    Service_Config.h
00006  *
00007  *  $Id: Service_Config.h,v 1.1.1.4 2003/02/21 18:36:32 chad Exp $
00008  *
00009  *  @author Douglas C. Schmidt <schmidt@cs.wustl.edu>
00010  */
00011 //=============================================================================
00012 
00013 #ifndef ACE_SERVICE_CONFIG_H
00014 #define ACE_SERVICE_CONFIG_H
00015 
00016 #include "ace/pre.h"
00017 
00018 #include "ace/config-all.h"
00019 
00020 #if !defined (ACE_LACKS_PRAGMA_ONCE)
00021 # pragma once
00022 #endif /* ACE_LACKS_PRAGMA_ONCE */
00023 
00024 #include "ace/Service_Types.h"
00025 #include "ace/Signal.h"
00026 #include "ace/Unbounded_Queue.h"
00027 #include "ace/Unbounded_Set.h"
00028 #include "ace/SString.h"
00029 #include "ace/XML_Svc_Conf.h"
00030 
00031 // Forward decl.
00032 class ACE_Service_Repository;
00033 class ACE_Allocator;
00034 class ACE_Reactor;
00035 class ACE_Thread_Manager;
00036 class ACE_DLL;
00037 
00038 #if (ACE_USES_CLASSIC_SVC_CONF == 1)
00039 class ACE_Svc_Conf_Param;
00040 #endif /* ACE_USES_CLASSIC_SVC_CONF ==1 */
00041 
00042 extern "C"
00043 {
00044   typedef ACE_Service_Object *(*ACE_SERVICE_ALLOCATOR) (ACE_Service_Object_Exterminator *);
00045 }
00046 
00047 /**
00048  * @class ACE_Static_Svc_Descriptor
00049  *
00050  * @brief Holds the information necessary to describe a statically linked
00051  * Svc.
00052  */
00053 class ACE_Static_Svc_Descriptor
00054 {
00055 public:
00056   /// Name of the service.
00057   const ACE_TCHAR *name_;
00058 
00059   /// Type of service.
00060   int type_;
00061 
00062   /// Factory function that allocates the service.
00063   ACE_SERVICE_ALLOCATOR alloc_;
00064 
00065   /// Bitmask flags indicating how the framework should delete memory.
00066   u_int flags_;
00067 
00068   /// Flag indicating whether the service starts out active.
00069   int active_;
00070 
00071   /// Dump the state of an object.
00072   void dump (void) const;
00073 
00074   /// Declare the dynamic allocation hooks.
00075   ACE_ALLOC_HOOK_DECLARE;
00076 
00077 public:
00078   /// Compare two service descriptors for equality.
00079   int operator== (ACE_Static_Svc_Descriptor &) const;
00080 
00081   /// Compare two service descriptors for inequality.
00082   int operator!= (ACE_Static_Svc_Descriptor &) const;
00083 };
00084 
00085 // Maintain a set of the statically linked service descriptors.
00086 typedef ACE_Unbounded_Set<ACE_Static_Svc_Descriptor *>
00087         ACE_STATIC_SVCS;
00088 typedef ACE_Unbounded_Set_Iterator<ACE_Static_Svc_Descriptor *>
00089         ACE_STATIC_SVCS_ITERATOR;
00090 
00091 // Maintain a queue of services to be configured from the
00092 // command-line.
00093 typedef ACE_Unbounded_Queue<ACE_TString>
00094         ACE_SVC_QUEUE;
00095 typedef ACE_Unbounded_Queue_Iterator<ACE_TString>
00096         ACE_SVC_QUEUE_ITERATOR;
00097 
00098 #define ACE_Component_Config ACE_Service_Config
00099 /**
00100  * @class ACE_Service_Config
00101  *
00102  * @brief Supplies common server operations for dynamic and static
00103  * configuration of services.
00104  *
00105  * The <ACE_Service_Config> uses the Monostate pattern.  Therefore,
00106  * you can only have one of these instantiated per-process.
00107  * NOTE: the signal_handler_ static member is allocated by the
00108  * <ACE_Object_Manager>.  The <ACE_Service_Config> constructor
00109  * uses signal_handler_.  Therefore, if the program has any
00110  * static <ACE_Service_Config> objects, there might be
00111  * initialization order problems.  They can be minimized, but
00112  * not eliminated, by _not_ #defining
00113  * <ACE_HAS_NONSTATIC_OBJECT_MANAGER>.
00114  */
00115 class ACE_Export ACE_Service_Config
00116 {
00117 public:
00118   enum
00119   {
00120     MAX_SERVICES = ACE_DEFAULT_SERVICE_REPOSITORY_SIZE
00121   };
00122 
00123   // = Initialization and termination methods.
00124 
00125   /// Initialize the Service Repository.
00126   ACE_Service_Config (int ignore_static_svcs = 1,
00127                       size_t size = ACE_Service_Config::MAX_SERVICES,
00128                       int signum = SIGHUP);
00129 
00130   /**
00131    * Performs an open without parsing command-line arguments.  The
00132    * @a logger_key indicates where to write the logging output, which
00133    * is typically either a STREAM pipe or a socket address.
00134    */
00135   ACE_Service_Config (const ACE_TCHAR program_name[],
00136                       const ACE_TCHAR *logger_key = ACE_DEFAULT_LOGGER_KEY);
00137 
00138   /**
00139    * Performs an open without parsing command-line arguments.  The
00140    * <logger_key> indicates where to write the logging output, which
00141    * is typically either a STREAM pipe or a socket address.  If
00142    * <ignore_default_svc_conf_file> is non-0 then the "svc.conf" file
00143    * will be ignored.  If <ignore_debug_flag> is non-0 then the
00144    * application is responsible for setting the
00145    * <ACE_Log_Msg::priority_mask> appropriately.  Returns number of
00146    * errors that occurred on failure and 0 otherwise.
00147    */
00148   static int open_i (const ACE_TCHAR program_name[],
00149                      const ACE_TCHAR *logger_key = ACE_DEFAULT_LOGGER_KEY,
00150                      int ignore_default_svc_conf_file = 0,
00151                      int ignore_debug_flag = 0);
00152 
00153   /**
00154    * Performs an open without parsing command-line arguments.  The
00155    * <logger_key> indicates where to write the logging output, which
00156    * is typically either a STREAM pipe or a socket address.  If
00157    * <ignore_static_svcs> is 1 then static services are not loaded,
00158    * otherwise, they are loaded.  If <ignore_default_svc_conf_file> is
00159    * non-0 then the <svc.conf> configuration file will be ignored.
00160    * Returns zero upon success, -1 if the file is not found or cannot
00161    * be opened (errno is set accordingly), otherwise returns the
00162    * number of errors encountered loading the services in the
00163    * specified svc.conf configuration file.  If <ignore_debug_flag> is
00164    * non-0 then the application is responsible for setting the
00165    * <ACE_Log_Msg::priority_mask> appropriately.
00166    */
00167   static int open (const ACE_TCHAR program_name[],
00168                    const ACE_TCHAR *logger_key = ACE_DEFAULT_LOGGER_KEY,
00169                    int ignore_static_svcs = 1,
00170                    int ignore_default_svc_conf_file = 0,
00171                    int ignore_debug_flag = 0);
00172 
00173   /**
00174    * This is the primary entry point into the ACE_Service_Config (the
00175    * constructor just handles simple initializations).  It parses
00176    * arguments passed in from @a argc and @a argv parameters.  The
00177    * arguments that are valid in a call to this method include:
00178    *
00179    * - '-b' Option to indicate that we should be a daemon. Note that when
00180    *        this option is used, the process will be daemonized before the
00181    *        service configuration file(s) are read. During daemonization,
00182    *        (on POSIX systems) the current directory will be changed to "/"
00183    *        so the caller should either fully specify the file names, or
00184    *        execute a @c chroot() to the appropriate directory.
00185    *        @sa ACE::daemonize().
00186    * - '-d' Turn on debugging mode
00187    * - '-f' Option to read in the list of svc.conf file names
00188    * - '-k' Option to read a wide string where in the logger output can
00189    *        be written
00190    * - '-y' Option required to use statically linked services.
00191    *        A static service repostory will be constructed if the flag
00192    *        is used.  Use this flag to override the default
00193    *        <ignore_static_svcs> flag at run-time.
00194    * - '-n' Option to avoid using any statically linked services, which
00195    *        eliminates the need to construct the static service repository.
00196    * - '-S' Option to read in the list of services on the command-line
00197    *        Please observe the difference between options '-f' that looks
00198    *        for a list of files and here a list of services.
00199    *
00200    * @param argc The number of commandline arguments.
00201    * @param argv The array with commandline arguments
00202    * @param logger_key   Indicates where to write the logging output,
00203    *                     which is typically either a STREAM pipe or a
00204    *                     socket address.
00205    * @param ignore_static_svcs   If 1 then static services are not loaded,
00206    *                             otherwise, they are loaded.
00207    * @param ignore_default_svc_conf_file  If non-0 then the @c svc.conf
00208    *                                      configuration file will be ignored.
00209    * @param ignore_debug_flag If non-0 then the application is responsible
00210    *                          for setting the @c ACE_Log_Msg::priority_mask
00211    *                          appropriately.
00212    *
00213    * @retval -1   the configuration file is not found or cannot
00214    *              be opened (errno is set accordingly).
00215    * @retval  0   Success.
00216    * @retval  >0  The number of errors encountered while processing
00217    *              the service configuration file(s).
00218    */
00219   static int open (int argc,
00220                    ACE_TCHAR *argv[],
00221                    const ACE_TCHAR *logger_key = ACE_DEFAULT_LOGGER_KEY,
00222                    int ignore_static_svcs = 1,
00223                    int ignore_default_svc_conf_file = 0,
00224                    int ignore_debug_flag = 0);
00225 
00226   /// Perform user-specified close activities and remove dynamic
00227   /// memory.
00228   virtual ~ACE_Service_Config (void);
00229 
00230   /// Tidy up and perform last rites when ACE_Service_Config is shut
00231   /// down.  This method calls <close_svcs>.  Returns 0.
00232   static int close (void);
00233 
00234   /// Perform user-specified close hooks and possibly delete all of the
00235   /// configured services in the <Service_Repository>.
00236   static int fini_svcs (void);
00237 
00238   /**
00239    * Perform user-specified close hooks on all of the configured
00240    * services in the <Service_Repository>, then delete the
00241    * <Service_Repository> itself.  Returns 0.
00242    */
00243   static int close_svcs (void);
00244 
00245   /// True if reconfiguration occurred.
00246   static int reconfig_occurred (void);
00247 
00248   /// Indicate that reconfiguration occurred.
00249   static void reconfig_occurred (int);
00250 
00251   /// Perform the reconfiguration process.
00252   static void reconfigure (void);
00253 
00254   // = The following methods are static in order to enforce Singleton
00255   // semantics for the Reactor, Service_Repository, Thread_Manager,
00256   // and Acceptor/Connector Strategy factory.  Other portions of the
00257   // system may need to access them at some point or another...
00258 
00259   // = Accessors and mutators for process-wide Singletons.
00260 
00261   /// Returns a pointer to the list of statically linked services.
00262   static ACE_STATIC_SVCS *static_svcs (void);
00263 
00264   // = Utility methods.
00265   /// Dynamically link the shared object file and retrieve a pointer to
00266   /// the designated shared object in this file.
00267   static int initialize (const ACE_Service_Type *,
00268                          const ACE_TCHAR *parameters);
00269 
00270   /// Initialize and activate a statically <svc_name> service.
00271   static int initialize (const ACE_TCHAR *svc_name,
00272                          const ACE_TCHAR *parameters);
00273 
00274   /// Resume a <svc_name> that was previously suspended or has not yet
00275   /// been resumed (e.g., a static service).
00276   static int resume (const ACE_TCHAR svc_name[]);
00277 
00278   /**
00279    * Suspend <svc_name>.  Note that this will not unlink the service
00280    * from the daemon if it was dynamically linked, it will mark it as
00281    * being suspended in the Service Repository and call the <suspend>
00282    * member function on the appropriate <ACE_Service_Object>.  A
00283    * service can be resumed later on by calling the <RESUME> member
00284    * function...
00285    */
00286   static int suspend (const ACE_TCHAR svc_name[]);
00287 
00288   /// Totally remove <svc_name> from the daemon by removing it
00289   /// from the ACE_Reactor, and unlinking it if necessary.
00290   static int remove (const ACE_TCHAR svc_name[]);
00291 
00292 #if defined (ACE_HAS_WINCE)
00293   // We must provide these function to bridge the Svc_Conf parser
00294   // with ACE.
00295   static int initialize (const ACE_Service_Type *, char parameters[]);
00296   static int initialize (const char svc_name[], char parameters[]);
00297   static int resume (const char svc_name[]);
00298   static int suspend (const char svc_name[]);
00299   static int remove (const char svc_name[]);
00300 #endif /* ACE_HAS_WINCE */
00301 
00302   /// Dump the state of an object.
00303   void dump (void) const;
00304 
00305   /// Set the signal_handler;for internal use by ACE_Object_Manager only.
00306   static ACE_INLINE void signal_handler (ACE_Sig_Adapter *);
00307 
00308   /// Declare the dynamic allocation hooks.
00309   ACE_ALLOC_HOOK_DECLARE;
00310 
00311   /// Process a file containing a list of service configuration
00312   /// directives.
00313   static int process_file (const ACE_TCHAR file[]);
00314 
00315   /// Process one service configuration <directive>, which is passed as
00316   /// a string.  Returns the number of errors that occurred.
00317   static int process_directive (const ACE_TCHAR directive[]);
00318 
00319   /// Process one static service definition.
00320   /**
00321    * Load a new static service into the ACE_Service_Repository.
00322    *
00323    * @param ssd Service descriptor, see the document of
00324    *        ACE_Static_Svc_Descriptor for more details.
00325    *
00326    * @param force_replace If set the new service descriptor replaces
00327    *        any previous instance in the ACE_Service_Repository.
00328    *
00329    * @return Returns -1 if the service cannot be 'loaded'.
00330    */
00331   static int process_directive (const ACE_Static_Svc_Descriptor &ssd,
00332                                 int force_replace = 0);
00333 
00334   /**
00335    * Process (or re-process) service configuration requests that are
00336    * provided in the svc.conf file(s).  Returns the number of errors
00337    * that occurred.
00338    */
00339   static int process_directives (void);
00340 
00341   /// Handles signals to trigger reconfigurations.
00342   static void handle_signal (int sig, siginfo_t *, ucontext_t *);
00343 
00344   /**
00345    * Handle the command-line options intended for the
00346    * <ACE_Service_Config>.  Note that <argv[0]> is assumed to be the
00347    * program name.
00348    * The arguments that are valid in a call to this method are
00349    * - '-b' Option to indicate that we should be a daemon
00350    * - '-d' Turn on debugging mode
00351    * - '-f' Option to read in the list of svc.conf file names
00352    * - '-k' Option to read a wide string where in the logger output can
00353    *        be written
00354    * - '-y' Turn on the flag for a  repository of statically
00355    *        linked services
00356    * - '-n' Need not have a repository of statically linked services
00357    * - '-S' Option to read in the list of services on the command-line
00358    *        Please observe the difference between options '-f' that looks
00359    *        for a list of files and here a list of services.
00360    */
00361   static int parse_args (int, ACE_TCHAR *argv[]);
00362 #if (ACE_USES_CLASSIC_SVC_CONF == 0)
00363   static ACE_Service_Type *create_service_type  (const ACE_TCHAR *n,
00364                                                  ACE_Service_Type_Impl *o,
00365                                                  ACE_DLL &dll,
00366                                                  int active);
00367 #endif /* ACE_USES_CLASSIC_SVC_CONF == 0 */
00368 
00369   static ACE_Service_Type_Impl *create_service_type_impl (const ACE_TCHAR *name,
00370                                                           int type,
00371                                                           void *symbol,
00372                                                           u_int flags,
00373                                                           ACE_Service_Object_Exterminator gobbler);
00374 protected:
00375   /// Process service configuration requests that were provided on the
00376   /// command-line.  Returns the number of errors that occurred.
00377   static int process_commandline_directives (void);
00378 
00379 #if (ACE_USES_CLASSIC_SVC_CONF == 1)
00380   /// This is the implementation function that process_directives()
00381   /// and process_directive() both call.  Returns the number of errors
00382   /// that occurred.
00383   static int process_directives_i (ACE_Svc_Conf_Param *param);
00384 #else
00385   /// Helper function to dynamically link in the XML Service Configurator parser.
00386   static ACE_XML_Svc_Conf *get_xml_svc_conf (ACE_DLL &d);
00387 #endif /* ACE_USES_CLASSIC_SVC_CONF == 1 */
00388 
00389   /// Become a daemon.
00390   static int start_daemon (void);
00391 
00392   /// Add the default statically-linked services to the
00393   /// <ACE_Service_Repository>.
00394   static int load_static_svcs (void);
00395 
00396 private:
00397   /// Indicates where to write the logging output.  This is typically
00398   /// either a STREAM pipe or a socket address.
00399   static const ACE_TCHAR *logger_key_;
00400 
00401   /// Singleton repository of statically linked services.
00402   static ACE_STATIC_SVCS *static_svcs_;
00403 
00404   /// Queue of services specified on the command-line.
00405   static ACE_SVC_QUEUE *svc_queue_;
00406 
00407   /// Queue of svc.conf files specified on the command-line.
00408   /// @@ This should probably be made to handle unicode filenames...
00409   static ACE_SVC_QUEUE *svc_conf_file_queue_;
00410 
00411   /// Initialize the <svc_conf_file_queue_> if necessary.
00412   static int init_svc_conf_file_queue (void);
00413 
00414   /// True if reconfiguration occurred.
00415   static sig_atomic_t reconfig_occurred_;
00416 
00417   // = Set by command-line options.
00418   /// Shall we become a daemon process?
00419   static int be_a_daemon_;
00420 
00421   /// Should we avoid loading the static services?
00422   static int no_static_svcs_;
00423 
00424   /// Number of the signal used to trigger reconfiguration.
00425   static int signum_;
00426 
00427   /// Handles the reconfiguration signals.
00428   static ACE_Sig_Adapter *signal_handler_;
00429 
00430   /**
00431    * Keep track of whether the <ACE_Service_Config> is already
00432    * initialized.  If so, we can't allow <yyparse> to be called since
00433    * it's not reentrant.  This variable is incremented by the
00434    * <ACE_Service_Config::open> method and decremented by the
00435    * <ACE_Service_Config::close> method.
00436    */
00437   static int is_initialized_;
00438 };
00439 
00440 #if defined (__ACE_INLINE__)
00441 #include "ace/Service_Config.i"
00442 #endif /* __ACE_INLINE__ */
00443 
00444 // These must go here to avoid circular includes...  (only left here
00445 // for to not break applications which rely on this - no real need any
00446 // longer)
00447 #include "ace/Reactor.h"
00448 #include "ace/Svc_Conf_Tokens.h"
00449 
00450 #include "ace/post.h"
00451 
00452 #endif /* ACE_SERVICE_CONFIG_H */

Generated on Mon Jun 16 11:21:11 2003 for ACE by doxygen1.2.14 written by Dimitri van Heesch, © 1997-2002