ACE_Service_Config Class Reference

Supplies common server operations for dynamic and static configuration of service. More...

#include <Service_Config.h>

Collaboration diagram for ACE_Service_Config:

List of all members.

Public Member Functions

ACE_Service_Config (bool ignore_static_svcs=true, size_t size=ACE_DEFAULT_SERVICE_REPOSITORY_SIZE, int signum=SIGHUP)

ACE_Service_Config (const ACE_TCHAR program_name[], const ACE_TCHAR *logger_key=ACE_DEFAULT_LOGGER_KEY)

virtual ~ACE_Service_Config (void)

Perform user-specified close activities and remove dynamic memory.

void dump (void) const

Dump the state of an object.

Static Public Member Functions

static ACE_Service_Config * singleton (void)

= Static interfaces

static void current (ACE_Service_Gestalt *)

A mutator to set the "current" (TSS) gestalt instance.

static ACE_Service_Gestalt * current (void)

static ACE_Service_Gestalt * instance (void)

static ACE_Service_Gestalt * global (void)

static int open (const ACE_TCHAR program_name[], const ACE_TCHAR *logger_key=ACE_DEFAULT_LOGGER_KEY, bool ignore_static_svcs=true, bool ignore_default_svc_conf_file=false, bool ignore_debug_flag=false)

static int open (int argc, ACE_TCHAR *argv[], const ACE_TCHAR *logger_key=ACE_DEFAULT_LOGGER_KEY, bool ignore_static_svcs=true, bool ignore_default_svc_conf_file=false, bool ignore_debug_flag=false)

static int close (void)

static int fini_svcs (void)

static int reconfig_occurred (void)

True if reconfiguration occurred.

static void reconfig_occurred (int)

Indicate that reconfiguration occurred.

static void reconfigure (void)

Perform the reconfiguration process.

static ACE_Service_Gestalt * static_svcs (void)

static int insert (ACE_Static_Svc_Descriptor *svc)

static int initialize (const ACE_Service_Type *, const ACE_TCHAR *parameters)

static int initialize (const ACE_TCHAR *svc_name, const ACE_TCHAR *parameters)

Initialize and activate a statically svc_name service.

static int resume (const ACE_TCHAR svc_name[])

static int suspend (const ACE_TCHAR svc_name[])

static int remove (const ACE_TCHAR svc_name[])

static ACE_INLINE void signal_handler (ACE_Sig_Adapter *)

Set the signal_handler;for internal use by ACE_Object_Manager only.

static int process_file (const ACE_TCHAR file[])

static int process_directive (const ACE_TCHAR directive[])

static int process_directive (const ACE_Static_Svc_Descriptor &ssd, bool force_replace=false)

static int process_directives (void)

static void handle_signal (int sig, siginfo_t *, ucontext_t *)

Handles signals to trigger reconfigurations.

static int parse_args (int, ACE_TCHAR *argv[])

static ACE_Service_Type_Impl * create_service_type_impl (const ACE_TCHAR *name, int type, void *symbol, u_int flags, ACE_Service_Object_Exterminator gobbler)

static int process_commandline_directives (void)

static int start_daemon (void)

Become a daemon.

static int load_static_svcs (void)

Public Attributes

ACE_ALLOC_HOOK_DECLARE

Declare the dynamic allocation hooks.

Static Protected Member Functions

static int process_directives_i (ACE_Svc_Conf_Param *param)

Private Member Functions

virtual int open_i (const ACE_TCHAR program_name[], const ACE_TCHAR *logger_key, bool ignore_static_svcs, bool ignore_default_svc_conf_file, bool ignore_debug_flag)

virtual int parse_args_i (int argc, ACE_TCHAR *argv[])

Private Attributes

ACE_Intrusive_Auto_Ptr
< ACE_Service_Gestalt > instance_

ACE_Threading_Helper
< ACE_SYNCH_MUTEX > threadkey_

Static Private Attributes

static sig_atomic_t reconfig_occurred_ = 0

True if reconfiguration occurred.

static bool be_a_daemon_ = false

Shall we become a daemon process?

static ACE_TCHAR * pid_file_name_ = 0

Pathname of file to write process id.

static int signum_ = SIGHUP

Number of the signal used to trigger reconfiguration.

static ACE_Sig_Adapter * signal_handler_ = 0

Handles the reconfiguration signals.

Friends

class ACE_Service_Config_Guard

class ACE_Threading_Helper< ACE_Thread_Mutex >

The helper needs intimate access (when building with no threads).

class ACE_Threading_Helper< ACE_Null_Mutex >

Detailed Description

Supplies common server operations for dynamic and static configuration of service.

The ACE_Service_Config uses the Monostate pattern. Therefore, you can only have one of these instantiated per-process. It represents the process-wide collection of services, which is typicaly shared among all other configurable entities. The only ACE_Service_Config instance is registered with and owned by the ACE_Object_Manager.

By contrast, the ACE_Service_Gestalt represents the collection of services, pertaining to a configurable entity. Typicaly, a "configurable entity" is an instance, which owns an instance of ACE_Service_Gestalt in order to ensure full controll over the services it needs.

Another facet of ACE_Service_Config is that for a given thread, it provides access to its current, process-global ACE_Service_Gestalt instance through its curent() method.

Note:: The signal_handler_ static member is allocated by the ACE_Object_Manager. The ACE_Service_Config constructor uses signal_handler_. Therefore, if the program has any static ACE_Service_Config objects, there might be initialization order problems. They can be minimized, but not eliminated, by _not_ defining ACE_HAS_NONSTATIC_OBJECT_MANAGER.

Constructor & Destructor Documentation

ACE_Service_Config::ACE_Service_Config	(	bool	ignore_static_svcs = `true`,
		size_t	size = `ACE_DEFAULT_SERVICE_REPOSITORY_SIZE`,
		int	signum = `SIGHUP`
	)

Initialize the Service Repository. Note that initialising signum to a negative number will prevent a signal handler being registered when the repository is opened.

ACE_Service_Config::ACE_Service_Config	(	const ACE_TCHAR	program_name[],
		const ACE_TCHAR *	logger_key = `ACE_DEFAULT_LOGGER_KEY`
	)

Performs an open without parsing command-line arguments. The logger_key indicates where to write the logging output, which is typically either a STREAM pipe or a socket address.

ACE_Service_Config::~ACE_Service_Config ( void ) [virtual]

Perform user-specified close activities and remove dynamic memory.

Member Function Documentation

int ACE_Service_Config::open_i	(	const ACE_TCHAR	program_name[],
		const ACE_TCHAR *	logger_key,
		bool	ignore_static_svcs,
		bool	ignore_default_svc_conf_file,
		bool	ignore_debug_flag
	)			`[private, virtual]`

Performs an open without parsing command-line arguments. Implements whats different in the opening sequence for this class, as opposed to the base class.

The logger_key indicates where to write the logging output, which is typically either a STREAM pipe or a socket address. If ignore_default_svc_conf_file is non-0 then the "svc.conf" file will be ignored. If ignore_debug_flag is non-0 then the application is responsible for setting the ACE_Log_Msg::priority_mask() appropriately. Returns number of errors that occurred on failure and 0 otherwise.

int ACE_Service_Config::parse_args_i	(	int	argc,
		ACE_TCHAR *	argv[]
	)			`[private, virtual]`

Implements whats different in the command line parameter processing for this class, as opposed to the base class.

ACE_Service_Config * ACE_Service_Config::singleton ( void ) [static]

= Static interfaces

Returns the process-wide global singleton instance. It would have been created and will be managed by the Object Manager.

Return the global configuration instance. Always returns the same instance

void ACE_Service_Config::current ( ACE_Service_Gestalt * newcurrent ) [static]

A mutator to set the "current" (TSS) gestalt instance.

Mutator for the currently active configuration context instance (gestalt). Intended for use by helper classes like

See also:: ACE_Service_Config_Guard. Stack-based instances can be used to temporarily change which gestalt is seen as global by static initializers (especially those in DLLs loaded at run-time).

ACE_Service_Gestalt * ACE_Service_Config::current ( void ) [static]

Accessor for the "current" service gestalt

Return the "global" configuration instance, for the current thread. This may be the same as instance(), but on some occasions, it may be a different one. For example, ACE_Service_Config_Guard provides a way of temporarily replacing the "current" configuration instance in the context of a thread.

ACE_INLINE ACE_Service_Gestalt * ACE_Service_Config::instance ( void ) [static]

This is what the static service initializators are hard-wired to use, so in order to avoid interface changes this method merely forwards to ACE_Service_Config::current. This enables us to enforce which Service Gestalt is used for services registering through static initializers. Especially important for DLL-based dynamic services, which can contain their own static services and static initializers.

Deprecated:: Use current() instead.

Return the configuration instance, considered "global" in the current thread. This may be the same as instance(), but on some occasions, it may be a different one. For example, ACE_Service_Config_Guard provides a way of temporarily replacing the "current" configuration instance in the context of a thread.

ACE_INLINE ACE_Service_Gestalt * ACE_Service_Config::global ( void ) [static]

Returns a process-wide global singleton instance in contrast with current (), which may return a different instance at different times, dependent on the context. Modifying this method's return value is strongly discouraged as it will circumvent the mechanism for dynamically loading services. If you must, use with extreme caution!

Return the global configuration instance. Allways returns the same instance

ACE_BEGIN_VERSIONED_NAMESPACE_DECL ACE_INLINE int ACE_Service_Config::open	(	const ACE_TCHAR	program_name[],
		const ACE_TCHAR *	logger_key = `ACE_DEFAULT_LOGGER_KEY`,
		bool	ignore_static_svcs = `true`,
		bool	ignore_default_svc_conf_file = `false`,
		bool	ignore_debug_flag = `false`
	)			`[static]`

Performs an open without parsing command-line arguments. The logger_key indicates where to write the logging output, which is typically either a STREAM pipe or a socket address. If ignore_static_svcs is true then static services are not loaded, otherwise, they are loaded. If ignore_default_svc_conf_file is non-0 then the <svc.conf> configuration file will be ignored. Returns zero upon success, -1 if the file is not found or cannot be opened (errno is set accordingly), otherwise returns the number of errors encountered loading the services in the specified svc.conf configuration file. If ignore_debug_flag is non-0 then the application is responsible for setting the ACE_Log_Msg::priority_mask appropriately.

ACE_INLINE int ACE_Service_Config::open	(	int	argc,
		ACE_TCHAR *	argv[],
		const ACE_TCHAR *	logger_key = `ACE_DEFAULT_LOGGER_KEY`,
		bool	ignore_static_svcs = `true`,
		bool	ignore_default_svc_conf_file = `false`,
		bool	ignore_debug_flag = `false`
	)			`[static]`

This is the primary entry point into the ACE_Service_Config (the constructor just handles simple initializations). It parses arguments passed in from argc and argv parameters. The arguments that are valid in a call to this method include:

'-b' Option to indicate that we should be a daemon. Note that when this option is used, the process will be daemonized before the service configuration file(s) are read. During daemonization, (on POSIX systems) the current directory will be changed to "/" so the caller should either fully specify the file names, or execute a chroot() to the appropriate directory.
See also:
ACE::daemonize().
'-d' Turn on debugging mode
'-f' Specifies a configuration file name other than the default svc.conf. Can be specified multiple times to use multiple files.
'-k' Specifies the rendezvous point to use for the ACE distributed logger.
'-y' Explicitly enables the use of static services. This flag overrides the ignore_static_svcs parameter value.
'-n' Explicitly disables the use of static services. This flag overrides the ignore_static_svcs parameter value.
'-p' Specifies a pathname which is used to store the process id.
'-s' Specifies a signal number other than SIGHUP to trigger reprocessing of the configuration file(s). Ignored for platforms that do not have POSIX signals, such as Windows.
'-S' Specifies a service directive string. Enclose the string in quotes and escape any embedded quotes with a backslash. This option specifies service directives without the need for a configuration file.

Parameters:

	argc	The number of commandline arguments.
	argv	The array with commandline arguments
	logger_key	Indicates where to write the logging output, which is typically either a STREAM pipe or a socket address.
	ignore_static_svcs	If true then static services are not loaded, otherwise, they are loaded.
	ignore_default_svc_conf_file	If non-0 then the `svc.conf` configuration file will be ignored.
	ignore_debug_flag	If true then the application is responsible for setting the `ACE_Log_Msg::priority_mask` appropriately.

Return values:

	-1	The configuration file is not found or cannot be opened (errno is set accordingly).
	0	Success.
	>0	The number of errors encountered while processing the service configuration file(s).

int ACE_Service_Config::close ( void ) [static]

Tidy up and perform last rites when ACE_Service_Config is shut down. This method calls close_svcs(). Returns 0.

int ACE_Service_Config::fini_svcs ( void ) [static]

Perform user-specified close hooks and possibly delete all of the configured services in the <Service_Repository>.

int ACE_Service_Config::reconfig_occurred ( void ) [static]

True if reconfiguration occurred.

void ACE_Service_Config::reconfig_occurred ( int config_occurred ) [static]

Indicate that reconfiguration occurred.

void ACE_Service_Config::reconfigure ( void ) [static]

Perform the reconfiguration process.

ACE_INLINE ACE_Service_Gestalt * ACE_Service_Config::static_svcs ( void ) [static]

Returns a pointer to the list of statically linked services.

Deprecated:

Same as instance(), but still useful in legacy code, (notably, one that can not be easily modified) which uses the following idiom for registering static services:

ACE_Service_Config::static_svcs ()->insert (...);

int ACE_Service_Config::insert ( ACE_Static_Svc_Descriptor * svc ) [static]

Insert a static service descriptor for processing on open_i(). The corresponding ACE_STATIC_SVC_* macros were chaged to use this method instead of obtaining a ptr to a container. See the note on static_svcs(). Added to prevent exposing the internal storage representation of the services repository and provide a better way of debugging service loading and registration problems.

ACE_INLINE int ACE_Service_Config::initialize	(	const ACE_Service_Type *	sr,
		const ACE_TCHAR *	parameters
	)			`[static]`

Dynamically link the shared object file and retrieve a pointer to the designated shared object in this file.

ACE_INLINE int ACE_Service_Config::initialize	(	const ACE_TCHAR *	svc_name,
		const ACE_TCHAR *	parameters
	)			`[static]`

Initialize and activate a statically svc_name service.

Initialize and activate a statically linked service.

int ACE_Service_Config::resume ( const ACE_TCHAR svc_name[] ) [static]

Resume a svc_name that was previously suspended or has not yet been resumed (e.g., a static service).

int ACE_Service_Config::suspend ( const ACE_TCHAR svc_name[] ) [static]

Suspend svc_name. Note that this will not unlink the service from the daemon if it was dynamically linked, it will mark it as being suspended in the Service Repository and call the <suspend> member function on the appropriate ACE_Service_Object. A service can be resumed later on by calling the <RESUME> member function...

int ACE_Service_Config::remove ( const ACE_TCHAR svc_name[] ) [static]

Totally remove svc_name from the daemon by removing it from the ACE_Reactor, and unlinking it if necessary.

void ACE_Service_Config::dump ( void ) const

Dump the state of an object.

ACE_INLINE void ACE_Service_Config::signal_handler ( ACE_Sig_Adapter * signal_handler ) [static]

Set the signal_handler;for internal use by ACE_Object_Manager only.

ACE_INLINE int ACE_Service_Config::process_file ( const ACE_TCHAR file[] ) [static]

Process a file containing a list of service configuration directives.

ACE_INLINE int ACE_Service_Config::process_directive ( const ACE_TCHAR directive[] ) [static]

Process one service configuration directive, which is passed as a string. Returns the number of errors that occurred.

ACE_INLINE int ACE_Service_Config::process_directive	(	const ACE_Static_Svc_Descriptor &	ssd,
		bool	force_replace = `false`
	)			`[static]`

Process one static service definition. Load a new static service into the ACE_Service_Repository.

Parameters:

	ssd	Service descriptor, see the document of ACE_Static_Svc_Descriptor for more details.
	force_replace	If set the new service descriptor replaces any previous instance in the ACE_Service_Repository.

Returns:: Returns -1 if the service cannot be 'loaded'.

ACE_INLINE int ACE_Service_Config::process_directives ( void ) [static]

Process (or re-process) service configuration requests that are provided in the svc.conf file(s). Returns the number of errors that occurred.

Process service configuration requests as indicated in the queue of svc.conf files.

void ACE_Service_Config::handle_signal	(	int	sig,
		siginfo_t *	,
		ucontext_t *
	)			`[static]`

Handles signals to trigger reconfigurations.

ACE_INLINE int ACE_Service_Config::parse_args	(	int	argc,
		ACE_TCHAR *	argv[]
	)			`[static]`

Handle the command-line options intended for the ACE_Service_Config. Note that argv[0] is assumed to be the program name. The arguments that are valid in a call to this method are

'-b' Option to indicate that we should be a daemon
'-d' Turn on debugging mode
'-f' Option to read in the list of svc.conf file names
'-k' Option to read a wide string where in the logger output can be written
'-y' Turn on the flag for a repository of statically linked services
'-n' Need not have a repository of statically linked services
'-S' Option to read in the list of services on the command-line Please observe the difference between options '-f' that looks for a list of files and here a list of services.

ACE_Service_Type_Impl * ACE_Service_Config::create_service_type_impl	(	const ACE_TCHAR *	name,
		int	type,
		void *	symbol,
		u_int	flags,
		ACE_Service_Object_Exterminator	gobbler
	)			`[static]`

static int ACE_Service_Config::process_commandline_directives ( void ) [static]

Deprecated:: Process service configuration requests that were provided on the command-line. Returns the number of errors that occurred.

static int ACE_Service_Config::start_daemon ( void ) [static]

Become a daemon.

static int ACE_Service_Config::load_static_svcs ( void ) [static]

static int ACE_Service_Config::process_directives_i ( ACE_Svc_Conf_Param * param ) [static, protected]

Deprecated:: This is the implementation function that process_directives() and process_directive() both call. Returns the number of errors that occurred.

Friends And Related Function Documentation

friend class ACE_Service_Config_Guard [friend]

Pointer to the Singleton (ACE_Cleanup) Gestalt instance. There is thread-specific global instance pointer, which is used to temporarily change which Gestalt instance is used for static service registrations.

A specific use case is a thread, which loads a _dynamic_ service from a DLL. If the said DLL also contains additional _static_ services, those *must* be registered with the same configuration repository as the dynamic service. Otherwise, the DLL's static services would be registered with the global Gestalt and may outlive the DLL that contains their code and perhaps the memory in which they are in. This is a problem because if the DLL gets unloaded (as it will, if it was loaded in an instance of Gestalt), the DLL's memory will be deallocated, but the global service repository will still "think" it must finalize the (DLL's) static services - with disastrous consequences, occurring in the post-main code (at_exit()). This class needs the intimate access to be able to swap the current TSS pointer for the global Gestalt.

friend class ACE_Threading_Helper< ACE_Thread_Mutex > [friend]

The helper needs intimate access (when building with no threads).

friend class ACE_Threading_Helper< ACE_Null_Mutex > [friend]

Member Data Documentation

ACE_Intrusive_Auto_Ptr<ACE_Service_Gestalt> ACE_Service_Config::instance_ [private]

The Instance, or the global (default) configuration context. The monostate would forward the calls to that instance. The TSS will point here

ACE_Threading_Helper<ACE_SYNCH_MUTEX> ACE_Service_Config::threadkey_ [private]

A helper instance to manage thread-specific key creation. Dependent on the syncronization mutex ACE uses, the corresponding partial template instantiation will perform the right services that have to do with managing thread-specific storage. Note that, for single-threaded builds they would do (next to) nothing.

ACE_Service_Config::ACE_ALLOC_HOOK_DECLARE

Declare the dynamic allocation hooks.

sig_atomic_t ACE_Service_Config::reconfig_occurred_ = 0 [static, private]

True if reconfiguration occurred.

bool ACE_Service_Config::be_a_daemon_ = false [static, private]

Shall we become a daemon process?

ACE_TCHAR * ACE_Service_Config::pid_file_name_ = 0 [static, private]

Pathname of file to write process id.

int ACE_Service_Config::signum_ = SIGHUP [static, private]

Number of the signal used to trigger reconfiguration.

ACE_Sig_Adapter * ACE_Service_Config::signal_handler_ = 0 [static, private]

Handles the reconfiguration signals.

The documentation for this class was generated from the following files:


Public Member Functions
	ACE_Service_Config (bool ignore_static_svcs=true, size_t size=ACE_DEFAULT_SERVICE_REPOSITORY_SIZE, int signum=SIGHUP)
	ACE_Service_Config (const ACE_TCHAR program_name[], const ACE_TCHAR *logger_key=ACE_DEFAULT_LOGGER_KEY)
virtual	~ACE_Service_Config (void)
	Perform user-specified close activities and remove dynamic memory.
void	dump (void) const
	Dump the state of an object.
Static Public Member Functions
static ACE_Service_Config *	singleton (void)
	= Static interfaces
static void	current (ACE_Service_Gestalt *)
	A mutator to set the "current" (TSS) gestalt instance.
static ACE_Service_Gestalt *	current (void)
static ACE_Service_Gestalt *	instance (void)
static ACE_Service_Gestalt *	global (void)
static int	open (const ACE_TCHAR program_name[], const ACE_TCHAR *logger_key=ACE_DEFAULT_LOGGER_KEY, bool ignore_static_svcs=true, bool ignore_default_svc_conf_file=false, bool ignore_debug_flag=false)
static int	open (int argc, ACE_TCHAR argv[], const ACE_TCHAR logger_key=ACE_DEFAULT_LOGGER_KEY, bool ignore_static_svcs=true, bool ignore_default_svc_conf_file=false, bool ignore_debug_flag=false)
static int	close (void)
static int	fini_svcs (void)
static int	reconfig_occurred (void)
	True if reconfiguration occurred.
static void	reconfig_occurred (int)
	Indicate that reconfiguration occurred.
static void	reconfigure (void)
	Perform the reconfiguration process.
static ACE_Service_Gestalt *	static_svcs (void)
static int	insert (ACE_Static_Svc_Descriptor *svc)
static int	initialize (const ACE_Service_Type , const ACE_TCHAR parameters)
static int	initialize (const ACE_TCHAR svc_name, const ACE_TCHAR parameters)
	Initialize and activate a statically svc_name service.
static int	resume (const ACE_TCHAR svc_name[])
static int	suspend (const ACE_TCHAR svc_name[])
static int	remove (const ACE_TCHAR svc_name[])
static ACE_INLINE void	signal_handler (ACE_Sig_Adapter *)
	Set the signal_handler;for internal use by ACE_Object_Manager only.
static int	process_file (const ACE_TCHAR file[])
static int	process_directive (const ACE_TCHAR directive[])
static int	process_directive (const ACE_Static_Svc_Descriptor &ssd, bool force_replace=false)
static int	process_directives (void)
static void	handle_signal (int sig, siginfo_t , ucontext_t )
	Handles signals to trigger reconfigurations.
static int	parse_args (int, ACE_TCHAR *argv[])
static ACE_Service_Type_Impl *	create_service_type_impl (const ACE_TCHAR name, int type, void symbol, u_int flags, ACE_Service_Object_Exterminator gobbler)
static int	process_commandline_directives (void)
static int	start_daemon (void)
	Become a daemon.
static int	load_static_svcs (void)
Public Attributes
	ACE_ALLOC_HOOK_DECLARE
	Declare the dynamic allocation hooks.
Static Protected Member Functions
static int	process_directives_i (ACE_Svc_Conf_Param *param)
Private Member Functions
virtual int	open_i (const ACE_TCHAR program_name[], const ACE_TCHAR *logger_key, bool ignore_static_svcs, bool ignore_default_svc_conf_file, bool ignore_debug_flag)
virtual int	parse_args_i (int argc, ACE_TCHAR *argv[])
Private Attributes
ACE_Intrusive_Auto_Ptr < ACE_Service_Gestalt >	instance_
ACE_Threading_Helper < ACE_SYNCH_MUTEX >	threadkey_
Static Private Attributes
static sig_atomic_t	reconfig_occurred_ = 0
	True if reconfiguration occurred.
static bool	be_a_daemon_ = false
	Shall we become a daemon process?
static ACE_TCHAR *	pid_file_name_ = 0
	Pathname of file to write process id.
static int	signum_ = SIGHUP
	Number of the signal used to trigger reconfiguration.
static ACE_Sig_Adapter *	signal_handler_ = 0
	Handles the reconfiguration signals.
Friends
class	ACE_Service_Config_Guard
class	ACE_Threading_Helper< ACE_Thread_Mutex >
	The helper needs intimate access (when building with no threads).
class	ACE_Threading_Helper< ACE_Null_Mutex >