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

#include <Service_Gestalt.h>

Inheritance diagram for ACE_Service_Gestalt:

Collaboration diagram for ACE_Service_Gestalt:

Classes
struct	Processed_Static_Svc
Public Types
enum	{ MAX_SERVICES = ACE_DEFAULT_SERVICE_REPOSITORY_SIZE }
enum	{ DEFAULT_SIZE = ACE_DEFAULT_SERVICE_GESTALT_SIZE }
Public Member Functions
	ACE_Service_Gestalt (size_t size=DEFAULT_SIZE, bool svc_repo_is_owned=true, bool no_static_svcs=true)
	~ACE_Service_Gestalt (void)
void	dump (void) const
	Dump the state of an object.
int	open (const ACE_TCHAR program_name[], const ACE_TCHAR *logger_key=0, bool ignore_static_svcs=true, bool ignore_default_svc_conf_file=false, bool ignore_debug_flag=false)
int	open (int argc, ACE_TCHAR argv[], const ACE_TCHAR logger_key=0, bool ignore_static_svcs=true, bool ignore_default_svc_conf_file=false, bool ignore_debug_flag=false)
int	is_opened (void)
int	process_directive (const ACE_TCHAR directive[])
int	process_directive (const ACE_Static_Svc_Descriptor &ssd, bool force_replace=false)
	Process one static service definition.
int	process_file (const ACE_TCHAR file[])
int	find (const ACE_TCHAR name[], const ACE_Service_Type **srp=0, bool ignore_suspended=true) const
	Searches for a service object declaration in the local repo, only.
int	parse_args (int argc, ACE_TCHAR *argv[])
int	process_directives (bool defunct_option=false)
int	close (void)
int	insert (ACE_Static_Svc_Descriptor *stsd)
	Registers a service descriptor for a static service object.
int	initialize (const ACE_Service_Type , const ACE_TCHAR parameters)
int	initialize (const ACE_TCHAR svc_name, const ACE_TCHAR parameters)
	Initialize and activate a statically svc_name service.
int	resume (const ACE_TCHAR svc_name[])
int	suspend (const ACE_TCHAR svc_name[])
int	remove (const ACE_TCHAR svc_name[])
int	find_static_svc_descriptor (const ACE_TCHAR name, ACE_Static_Svc_Descriptor *ssd=0) const
	Find a static service descriptor by name.
ACE_Service_Repository *	current_service_repository (void)
	Get the current ACE_Service_Repository held by this object.
Static Public Member Functions
static void	intrusive_add_ref (ACE_Service_Gestalt *)
static void	intrusive_remove_ref (ACE_Service_Gestalt *)
Public Attributes
	ACE_ALLOC_HOOK_DECLARE
	Declare the dynamic allocation hooks.
Protected Types
typedef ACE_Unbounded_Queue < ACE_TString >	ACE_SVC_QUEUE
typedef ACE_Unbounded_Queue_Iterator < ACE_TString >	ACE_SVC_QUEUE_ITERATOR
typedef ACE_Unbounded_Set < ACE_Static_Svc_Descriptor * >	ACE_STATIC_SVCS
	Maintain a set of the statically linked service descriptors.
typedef ACE_Unbounded_Set_Iterator < ACE_Static_Svc_Descriptor * >	ACE_STATIC_SVCS_ITERATOR
typedef ACE_Unbounded_Set < Processed_Static_Svc * >	ACE_PROCESSED_STATIC_SVCS
typedef ACE_Unbounded_Set_Iterator < Processed_Static_Svc * >	ACE_PROCESSED_STATIC_SVCS_ITERATOR
Protected Member Functions
int	parse_args_i (int, ACE_TCHAR *argv[], bool &ignore_default_svc_conf_file)
int	open_i (const ACE_TCHAR program_name[], const ACE_TCHAR *logger_key=0, bool ignore_static_svcs=true, bool ignore_default_svc_conf_file=false, bool ignore_debug_flag=false)
int	init_svc_conf_file_queue (void)
	Initialize the `svc_conf_file_queue_` if necessary.
int	load_static_svcs (void)
int	process_commandline_directives (void)
int	process_directive_i (const ACE_Static_Svc_Descriptor &ssd, bool force_replace=false)
ACE_XML_Svc_Conf *	get_xml_svc_conf (ACE_DLL &d)
int	initialize_i (const ACE_Service_Type sr, const ACE_TCHAR parameters)
const ACE_Static_Svc_Descriptor *	find_processed_static_svc (const ACE_TCHAR *)
void	add_processed_static_svc (const ACE_Static_Svc_Descriptor *)
	Captures a list of the direcives processed (explicitely) for this Gestalt so that services can be replicated in other repositories upon their first initialization.
int	init_i (void)
Protected Attributes
bool	svc_repo_is_owned_
size_t	svc_repo_size_
int	is_opened_
const ACE_TCHAR *	logger_key_
bool	no_static_svcs_
	Should we avoid loading the static services?
ACE_SVC_QUEUE *	svc_queue_
	Queue of services specified on the command-line.
ACE_SVC_QUEUE *	svc_conf_file_queue_
ACE_Service_Repository *	repo_
	The service repository to hold the services.
ACE_STATIC_SVCS *	static_svcs_
	Repository of statically linked services.
ACE_PROCESSED_STATIC_SVCS *	processed_static_svcs_
ACE_Atomic_Op< ACE_SYNCH_MUTEX, long >	refcnt_
	Support for intrusive reference counting.
Friends
class	ACE_Dynamic_Service_Base
class	ACE_Service_Object
class	ACE_Service_Config
class	ACE_Service_Config_Guard

Detailed Description

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

The Gestalt embodies the concept of configuration context. On one hand, it is a flat namespace, where names correspond to a Service Object instance. A Gestalt owns the Service Repository instance, which in turn owns the Service Object instances.

Another aspect of a Gestalt is its responsibility for record-keeping and accounting for the meta-data, necessary for locating, removing or instantiating a service.

A repository underlies an instance of a gestalt and its lifetime may or may not be bounded by the lifetime of the gestalt, that owns it. This feature is important for the derived classes and the Service Config in particular.

Member Typedef Documentation

typedef ACE_Unbounded_Set<Processed_Static_Svc *> ACE_Service_Gestalt::ACE_PROCESSED_STATIC_SVCS [protected]

typedef ACE_Unbounded_Set_Iterator<Processed_Static_Svc *> ACE_Service_Gestalt::ACE_PROCESSED_STATIC_SVCS_ITERATOR [protected]

typedef ACE_Unbounded_Set<ACE_Static_Svc_Descriptor *> ACE_Service_Gestalt::ACE_STATIC_SVCS [protected]

Maintain a set of the statically linked service descriptors.

typedef ACE_Unbounded_Set_Iterator<ACE_Static_Svc_Descriptor *> ACE_Service_Gestalt::ACE_STATIC_SVCS_ITERATOR [protected]

typedef ACE_Unbounded_Queue<ACE_TString> ACE_Service_Gestalt::ACE_SVC_QUEUE [protected]

Maintain a queue of services to be configured from the command-line.

typedef ACE_Unbounded_Queue_Iterator<ACE_TString> ACE_Service_Gestalt::ACE_SVC_QUEUE_ITERATOR [protected]

Member Enumeration Documentation

anonymous enum

Enumerator:

MAX_SERVICES

anonymous enum

Enumerator:

DEFAULT_SIZE

Constructor & Destructor Documentation

ACE_Service_Gestalt::ACE_Service_Gestalt	(	size_t	size = `DEFAULT_SIZE`,
		bool	svc_repo_is_owned = `true`,
		bool	no_static_svcs = `true`
	)

Constructor either associates the instance with the process-wide singleton instance of ACE_Service_Repository, or creates and manages its own instance of the specified size.

ACE_Service_Gestalt::~ACE_Service_Gestalt ( void )

Perform user-specified close activities and remove dynamic memory.

Member Function Documentation

void ACE_Service_Gestalt::add_processed_static_svc ( const ACE_Static_Svc_Descriptor * assd ) [protected]

Captures a list of the direcives processed (explicitely) for this Gestalt so that services can be replicated in other repositories upon their first initialization.

This is part of the mechanism ensuring distinct local instances for static service objects, loaded in another repository.

When process_directive(Static_Svc_Descriptor&) is called, it associates a service object with the Gestalt and makes the resource (a Service Object) local to the repository. This is but the first step in using such SO. The next is the "initialization" step. It is typicaly done through a "static" service configuration directive.

In contrast a "dynamic" directive, when processed through the overloaded process_directives(string) both creates the SO locally and initializes it, where the statics directive must first locate the SO and then calls the init() method. This means that durig the "static" initialization there's no specific information about the hosting repository and the gestalt must employ some lookup strategy to find it elsewhere.

int ACE_Service_Gestalt::close ( void )

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

ACE_Service_Repository * ACE_Service_Gestalt::current_service_repository ( void ) [inline]

Get the current ACE_Service_Repository held by this object.

void ACE_Service_Gestalt::dump ( void ) const

Dump the state of an object.

int ACE_Service_Gestalt::find	(	const ACE_TCHAR	name[],
		const ACE_Service_Type **	srp = `0`,
		bool	ignore_suspended = `true`
	)		const `[inline]`

Searches for a service object declaration in the local repo, only.

Locate an entry with name in the table. If ignore_suspended is set then only consider services marked as resumed. If the caller wants the located entry, pass back a pointer to the located entry via srp. If name is not found, -1 is returned. If name is found, but it is suspended and the caller wants to ignore suspended services a -2 is returned.

const ACE_Static_Svc_Descriptor * ACE_Service_Gestalt::find_processed_static_svc ( const ACE_TCHAR * name ) [protected]

int ACE_Service_Gestalt::find_static_svc_descriptor	(	const ACE_TCHAR *	name,
		ACE_Static_Svc_Descriptor **	ssd = `0`
	)		const

Find a static service descriptor by name.

Using the supplied name, finds and (if needed) returns a pointer to a static service descriptor. Returns 0 for success and -1 for failure

ACE_XML_Svc_Conf * ACE_Service_Gestalt::get_xml_svc_conf ( ACE_DLL & d ) [protected]

Helper function to dynamically link in the XML Service Configurator parser.

int ACE_Service_Gestalt::init_i ( void ) [protected]

Performs the common initialization tasks for a new or previously closed instance. Must not be virtual, as it is called from the constructor.

Performs the common initialization tasks for a new or previously closed instance. Must not be virtual, as it is also called from the constructor.

int ACE_Service_Gestalt::init_svc_conf_file_queue ( void ) [protected]

Initialize the svc_conf_file_queue_ if necessary.

int ACE_Service_Gestalt::initialize	(	const ACE_Service_Type *	sr,
		const ACE_TCHAR *	parameters
	)

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

Deprecated:

Note:: This is error-prone in the presense of dynamic services, which in turn initialize their own static services. This method will allow those static services to register *before* the dynamic service that owns them. Upon finalization of the static services the process will typically crash, because the dynamic service's DLL may have been already released, together with the memory in which the static services reside. It may not crash, for instance, when the first static service to register is the same as the dynamic service being loaded. You should be so lucky!

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

Note:: This is obsolete (and error-prone) in the presense of dynamic services with their own static services. This method will allow those static services to register *before* the dynamic service that owns them. Upon finalization of the static services the process may crash, because the dynamic service's DLL may have been already released, together with the memory in which the static services reside. It may not crash, for instance, when the first static service to register is the same as the dynamic service being loaded. You should be so lucky! ..

int ACE_Service_Gestalt::initialize	(	const ACE_TCHAR *	svc_name,
		const ACE_TCHAR *	parameters
	)

Initialize and activate a statically svc_name service.

If initialization fails ...

int ACE_Service_Gestalt::initialize_i	(	const ACE_Service_Type *	sr,
		const ACE_TCHAR *	parameters
	)		`[protected]`

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

int ACE_Service_Gestalt::insert ( ACE_Static_Svc_Descriptor * stsd )

Registers a service descriptor for a static service object.

Queues a static service object descriptor which, during open() will be given to process_directive() to create the Service Object. Normally, only called from static initializers, prior to calling open() but loading a service from a DLL can cause it too.

void ACE_Service_Gestalt::intrusive_add_ref ( ACE_Service_Gestalt * g ) [static]

void ACE_Service_Gestalt::intrusive_remove_ref ( ACE_Service_Gestalt * g ) [static]

int ACE_Service_Gestalt::is_opened ( void )

Has it been opened? Returns the difference between the times open and close have been called on this instance

int ACE_Service_Gestalt::load_static_svcs ( void ) [protected]

Add the default statically-linked services to the ACE_Service_Repository.

Add the default statically-linked services to the Service Repository.

int ACE_Service_Gestalt::open	(	const ACE_TCHAR	program_name[],
		const ACE_TCHAR *	logger_key = `0`,
		bool	ignore_static_svcs = `true`,
		bool	ignore_default_svc_conf_file = `false`,
		bool	ignore_debug_flag = `false`
	)		`[inline]`

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 true 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 true then the application is responsible for setting the ACE_Log_Msg::priority_mask appropriately.

int ACE_Service_Gestalt::open	(	int	argc,
		ACE_TCHAR *	argv[],
		const ACE_TCHAR *	logger_key = `0`,
		bool	ignore_static_svcs = `true`,
		bool	ignore_default_svc_conf_file = `false`,
		bool	ignore_debug_flag = `false`
	)		`[inline]`

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. If any configuration file is provided with this option then the default svc.conf will be ignored.
'-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. Can be specified multiple times.

Note: Options '-f' and '-S' complement each other. Directives from files and from '-S' option are processed together in the following order. First, the default file "./svc.conf" is evaluated if not ignored, then all files are processed in the order they are specified in '-f' argv parameter. Finally, all '-S' directive strings are executed in the order the directives appear in argv parameter.

If no files or directives are added via the '-f' and '-S' arguments, and the default file is not ignored, it will be evaluated whether it exists or not, possibly causing a failure return. If any other directives are added then the default file will be evaluated only if it exists.

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 false then the ./svc.conf configuration file will be ignored.
ignore_debug_flag	If false then the application is responsible for setting the `ACE_Log_Msg::priority_mask` appropriately.

Return values:

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

int ACE_Service_Gestalt::open_i	(	const ACE_TCHAR	program_name[],
		const ACE_TCHAR *	logger_key = `0`,
		bool	ignore_static_svcs = `true`,
		bool	ignore_default_svc_conf_file = `false`,
		bool	ignore_debug_flag = `false`
	)		`[protected]`

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_default_svc_conf_file is non-0 then the "svc.conf" file will not be added by default. 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_Gestalt::parse_args	(	int	argc,
		ACE_TCHAR *	argv[]
	)

Handle the command-line options intended for the ACE_Service_Gestalt. Note that argv[0] is assumed to be the program name.

The arguments that are valid in a call to this method are

'-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.

int ACE_Service_Gestalt::parse_args_i	(	int	argc,
		ACE_TCHAR *	argv[],
		bool &	ignore_default_svc_conf_file
	)		`[protected]`

int ACE_Service_Gestalt::process_commandline_directives ( void ) [protected]

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

int ACE_Service_Gestalt::process_directive ( const ACE_TCHAR directive[] )

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

int ACE_Service_Gestalt::process_directive	(	const ACE_Static_Svc_Descriptor &	ssd,
		bool	force_replace = `false`
	)

Process one static service definition.

Load a new static service.

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 repository.

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

int ACE_Service_Gestalt::process_directive_i	(	const ACE_Static_Svc_Descriptor &	ssd,
		bool	force_replace = `false`
	)		`[protected]`

Process a static directive without also inserting its descriptor the global table. This avoids multiple additions when processing directives in non-global gestalts.

int ACE_Service_Gestalt::process_directives ( bool defunct_option = false )

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

int ACE_Service_Gestalt::process_file ( const ACE_TCHAR file[] )

Process a file containing a list of service configuration directives.

int ACE_Service_Gestalt::remove ( const ACE_TCHAR svc_name[] )

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

int ACE_Service_Gestalt::resume ( const ACE_TCHAR svc_name[] )

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

int ACE_Service_Gestalt::suspend ( const ACE_TCHAR svc_name[] )

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...

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> method...

Friends And Related Function Documentation

friend class ACE_Dynamic_Service_Base [friend]

friend class ACE_Service_Config [friend]

friend class ACE_Service_Config_Guard [friend]

friend class ACE_Service_Object [friend]

Member Data Documentation

ACE_Service_Gestalt::ACE_ALLOC_HOOK_DECLARE

Declare the dynamic allocation hooks.

int ACE_Service_Gestalt::is_opened_ [protected]

Keep track of the number of times the instance has been initialized (opened). "If so, we can't allow <yyparse> to be called since it's not reentrant" is the original motivation, but that does not seem to be the case anymore. This variable is incremented by the <ACE_Service_Gestalt::open> method and decremented by the <ACE_Service_Gestalt::close> method.

const ACE_TCHAR* ACE_Service_Gestalt::logger_key_ [protected]

Indicates where to write the logging output. This is typically either a STREAM pipe or a socket

bool ACE_Service_Gestalt::no_static_svcs_ [protected]

Should we avoid loading the static services?

ACE_PROCESSED_STATIC_SVCS* ACE_Service_Gestalt::processed_static_svcs_ [protected]

Repository of statically linked services for which process directive was called, but the service is not already a member of the static_svcs_ list.

ACE_Atomic_Op<ACE_SYNCH_MUTEX, long> ACE_Service_Gestalt::refcnt_ [protected]

Support for intrusive reference counting.

ACE_Service_Repository* ACE_Service_Gestalt::repo_ [protected]

The service repository to hold the services.

ACE_STATIC_SVCS* ACE_Service_Gestalt::static_svcs_ [protected]

Repository of statically linked services.