#include <module.hpp>

Inheritance diagram for Module:

Collaboration diagram for Module:

Class Description

This class is used by ALib to

manage library bootstrap and termination,
provide resources and to
provide Configuration data (e.g. configuration files, command line parameters, etc.).

Typically, every "full" ALib Module disposes about a type derived from this class. The singleton instances of these types are collected in namespace aworx::lib and are named in capital letters, for example aworx::lib::ALOX, aworx::lib::EXPRESSIONS, etc.

Types found in an ALib Module, will use methods GetResourcePool and GetConfig of that singleton to access resources and to read and write configuration data. With that, it has to be kept in mind that these objects most probably are shared with other modules. As a consequence, clear and understandable resource and variable categories and names are to be used, to avoid conflicting entries.

The ALib Programmer's Manual provides several chapters that explain how 3. Bootstrapping ALib is performed with the help of this class.
Furthermore, source code sample is given with the tutorial of ALib module CLI.

Often, types that comprise a "module singleton" (as the derived types shown in the inheritance diagram above) incorporate some further functionality specific to the field of application that a module covers.

Reference Documentation

Definition at line 74 of file module.hpp.

Public Types
enum	BootstrapPhases { PrepareResources = 1, PrepareConfig = 2, Final = 3 }

enum	ShutdownPhases { Announce = 1, Destruct = 2 }

Public Fields
std::vector< std::pair< const nchar *, uint64_t > >	CompilationFlagMeanings

const uint64_t	CompilationFlags

NCString	ResourceCategory

const int	Revision

const int	Version

Public Methods
	Module (const Module &)=delete

	Module (int version, int revision, const NCString &resourceCategory, uint64_t compilationFlags=0)

	Module (Module &&)=delete

virtual	~Module ()

ALIB_API bool	Bootstrap (BootstrapPhases targetPhase=BootstrapPhases::Final, int argc=0, const char argvN=nullptr, const wchar_t argvW=nullptr)

template<typename TChar >
bool	Bootstrap (int argc, TChar **argv, BootstrapPhases targetPhase=BootstrapPhases::Final)

void	BootstrapResource (const NString &name, const String &data)

void	BootstrapSetConfig (config::Configuration *pConfig)

void	BootstrapSetResourcePool (resources::ResourcePool *pool)

config::Configuration &	GetConfig ()

const String &	GetResource (const NString &name)

ResourcePool &	GetResourcePool ()

bool	IsBootstrapped ()

void	operator= (const Module &)=delete

void	operator= (Module &&)=delete

ALIB_API void	Shutdown (ShutdownPhases targetPhase=ShutdownPhases::Destruct)

const String &	TryResource (const NString &name)

ALIB_API bool	VerifyCompilationFlags (uint64_t compilationFlags)

Protected Static Fields
static bool	microModulesInitialized = false

Protected Fields
int	bootstrapState = 0

config::Configuration *	config = nullptr

bool	isConfigOwner = false

bool	isResourceOwner = false

resources::ResourcePool *	resourcePool = nullptr

Protected Methods
virtual void	bootstrap (BootstrapPhases phase, int argc, const char argv, const wchar_t wargv)=0

virtual void	shutdown (ShutdownPhases phase)=0

Member Enumeration Documentation

◆ BootstrapPhases

enum BootstrapPhases

strong

Initialization levels usable with Bootstrap methods.

Enumerator
PrepareResources	Creates field resourcePool and loads its module specific default values.
PrepareConfig	Initializes up to the creation of a field config.
Final	The final initialization phase.

Definition at line 78 of file module.hpp.

◆ ShutdownPhases

enum ShutdownPhases

strong

Termination levels usable with Shutdown methods.

Enumerator
Announce	Signals termination. Keeps resources, config, etc. intact. Usable to write configuration data, stop background threads, etc.
Destruct	The main phase of termination that destructs everything.

Definition at line 88 of file module.hpp.

Constructor & Destructor Documentation

◆ Module() [1/3]

Module	(	int	version,
		int	revision,
		const NCString &	resourceCategory,
		uint64_t	compilationFlags = `0`
	)

inline

Constructor. Just stores the given values in corresponding fields.

Parameters

version	Value for field Version.
revision	Value for field Revision.
resourceCategory	Value for field ResourceCategory.
compilationFlags	Value for field CompilationFlags. See method VerifyCompilationFlags. Defaults to `0`.

Definition at line 204 of file module.hpp.

◆ Module() [2/3]

Module ( const Module & )

delete

Deleted copy constructor.

◆ Module() [3/3]

Module ( Module && )

delete

Deleted move constructor.

◆ ~Module()

virtual ~Module ( )

inlinevirtual

Virtual destructor to satisfy virtual methods.

Definition at line 230 of file module.hpp.

Here is the call graph for this function:

Member Function Documentation

◆ bootstrap()

virtual void bootstrap	(	BootstrapPhases	phase,
		int	argc,
		const char **	argv,
		const wchar_t **	wargv
	)

protectedpure virtual

Abstract method which is invoked during bootstrapping by method Bootstrap for each phase, with all modules found in list ALibDistribution::Modules of singleton aworx::ALIB.

Note that the availability of parameters argc, argv and wargv depend on the using code of the library, namely if there, the arguments are passed to Module::Bootstrap.

Parameters

phase	The initialization phase to perform.
argc	The number of command line arguments. Defaults to `0`.
argv	List of command line arguments if given as single byte character strings.
wargv	List of command line arguments if given as multi-byte character strings.

Implemented in Expressions, ALibDistribution, ALox, Text, Config, System, Results, and Cli.

◆ Bootstrap() [1/2]

bool Bootstrap	(	BootstrapPhases	targetPhase = `BootstrapPhases::Final`,
		int	argc = `0`,
		const char **	argvN = `nullptr`,
		const wchar_t **	argvW = `nullptr`
	)

Initializes this module up to the given targetPhase. If the module was initialized for the given level already, nothing is done and false is returned.

Checks if module list ALibDistribution::Modules of singleton aworx::ALIB was filled already (by the using software for the purpose to add custom modules). If not, ALibDistribution::BootstrapFillDefaultModuleList is invoked to place the ALib modules as contained in the ALib Distribution.

If method BootstrapSetResourcePool is not invoked prior to invoking this method, an object of type LocalResourcePool is created and shared with each lower-level module, until a module is found that has a resource pool set.

If method BootstrapSetConfig is not invoked prior to invoking this method, with parameter targetPhase set equal or higher than BootstrapPhases::PrepareConfig, then an object of type Configuration is created and shared with each lower-level module, until a module is found that has a configuration instance set.

This approach of creating and distributing the resource pool and the configuration, together with the possibility to invoke this method on a module that resides anywhere in list ALibDistribution::Modules, allows to customize bootstrapping and module setup in various ways.

Parameters argc, argvN and argvW may be used to provide command line arguments. They will be passed to abstract method bootstrap of all dependent libraries. Special singleton aworx::ALIB of type ALibDistribution will store the parameters for convenience in publicly accessible fields. Note that only either of parameters argvN and argvW is to be provided (the other should be nulled), depending on system/compilation preferences and on the character size that the compilation toolset provides with method main().

See also: For details on when and how to invoke this method, see the detailed explanations in chapter 3. Bootstrapping ALib of the ALib Programmer's Manual.

Parameters

targetPhase	The initialization level to perform. Defaults to `BootstrapPhases::Final`.
argc	Parameter usually taken from standard C `main()` method (the number of arguments in argv). Defaults to `0`.
argvN	The command line parameters given as a zero-terminated list to zero-terminated narrow strings. Defaults to `nullptr`.
argvW	The command line parameters given as a zero-terminated list to zero-terminated wide strings. Defaults to `nullptr`.

Returns: true if the module was not initialized before, false otherwise.

Definition at line 64 of file module.cpp.

Here is the call graph for this function:

◆ Bootstrap() [2/2]

bool Bootstrap	(	int	argc,
		TChar **	argv,
		BootstrapPhases	targetPhase = `BootstrapPhases::Final`
	)

Inline convenience shortcut to method Bootstrap(BootstrapPhases,int,const char**,const wchar_t**) accepting either narrow or wide character command line arguments using one templated method parameter.

Template Parameters

TChar The character type of parameter argv.

Parameters

argc	The number of arguments.
argv	The command line arguments as nchar or wchar, constant or not.
targetPhase	The initialization level to perform. Defaults to BootstrapPhases::Final.

Returns: true if the module was not initialized before, false otherwise.

◆ BootstrapResource()

void BootstrapResource	(	const NString &	name,
		const String &	data
	)

inline

Shortcut method that invokes ResourcePool::Bootstrap on field resourcePool providing field ResourceCategory as parameter.

Parameters

name	The resource name.
data	The resource data string.

Definition at line 447 of file module.hpp.

Here is the call graph for this function:

◆ BootstrapSetConfig()

void BootstrapSetConfig ( config::Configuration * pConfig )

inline

Sets the configuration object of this module.

Attention: This method must be invoked before method Bootstrap is invoked with parameter targetPhase set equal or higher than BootstrapPhases::PrepareConfig, because in this phase, internally a configuration is created if none is set.; Method Bootstrap will distribute the given instance to each lower level module that has not received a different object.

See also

Chapter

Bootstrapping And Shutting Down ALib

of the Programmer's Manual of ALib.

Parameters

pConfig The external configuration object to use.

Definition at line 390 of file module.hpp.

◆ BootstrapSetResourcePool()

void BootstrapSetResourcePool ( resources::ResourcePool * pool )

inline

Sets the resource pool of this module.

Attention: This method must be invoked before method Bootstrap, because in the first phase BootstrapPhases::PrepareConfig, internally a pool of type LocalResourcePool is created if none is set.; Method Bootstrap will distribute the given instance to each lower level module that has not received a different object.

See also

Chapter

Bootstrapping And Shutting Down ALib

of the Programmer's Manual of ALib.

Parameters

pool	The external resource pool to use.

Definition at line 424 of file module.hpp.

◆ GetConfig()

config::Configuration& GetConfig ( )

inline

Returns a reference to the configuration object.

Returns: The configuration object set with bootstrapping.

Definition at line 401 of file module.hpp.

◆ GetResource()

const String& GetResource ( const NString & name )

inline

Shortcut method that invokes ResourcePool::Get on field resourcePool providing field ResourceCategory as parameter.

With debug builds, this method asserts that a resource was found. If this is not wanted, use TryResource.

Parameters

name	The resource name.

Returns: The resource string, respectively a nulled string on failure.

Definition at line 462 of file module.hpp.

Here is the call graph for this function:

◆ GetResourcePool()

ResourcePool& GetResourcePool ( )

inline

Returns a reference to the resource pool.

Returns: The resource pool set with bootstrapping.

Definition at line 435 of file module.hpp.

◆ IsBootstrapped()

bool IsBootstrapped ( )

inline

Tests if the module was completely initialized.

Returns: true if the initialization state is either BootstrapPhases::Final or ShutdownPhases::Announce, false otherwise.

Definition at line 361 of file module.hpp.

Here is the call graph for this function:

◆ operator=() [1/2]

void operator= ( const Module & )

delete

Deleted copy assignment.

◆ operator=() [2/2]

void operator= ( Module && )

delete

Deleted move assignment.

◆ shutdown()

virtual void shutdown ( ShutdownPhases phase )

protectedpure virtual

Abstract method invoked by Shutdown.

Parameters

phase The termination level to perform.

Implemented in Expressions, ALibDistribution, ALox, Text, Config, System, Results, and Cli.

◆ Shutdown()

void Shutdown ( ShutdownPhases targetPhase = ShutdownPhases::Destruct )

De-initializes modules found in list ALibDistribution::Modules of singleton aworx::ALIB# in reverse order.

With built-in ALib Modules, no urgent actions are performed apart from memory de-allocation, which is anyhow done by modern operating systems with the termination of a process. However, still this method should be invoked in the case of future changes. Also, if using memory analysis tools (such as Valgrind) it is important to remove any internal allocations before a program terminates.

Custom modules might use the first of the two termination levels (ShutdownPhases::Announce) to close background threads or write configuration data.

Only in the second level (ShutdownPhases::Destruct) actions are to be taken that disables and destructs a software.

Parameters

targetPhase The termination level to perform. Defaults to ShutdownPhases::Destruct.

Definition at line 249 of file module.cpp.

Here is the call graph for this function:

◆ TryResource()

const String& TryResource ( const NString & name )

inline

Shortcut method that invokes ResourcePool::Get on field resourcePool providing field ResourceCategory as parameter.

Note: Usually, it is recommended to use GetResource, which asserts with debug builds if a resource was not found.

Parameters

name	The resource name.

Returns: The resource string, respectively a nulled string on failure.

Definition at line 477 of file module.hpp.

Here is the call graph for this function:

◆ VerifyCompilationFlags()

bool VerifyCompilationFlags ( uint64_t compilationFlags )

Compares a given set of compilation flags with the internal set. This is an optional feature of modules which expose compiler definitions that lead to incompatible module versions when mixed.

If used, the following steps have to be performed:

By the module that offers the feature:
- Expose a preprocessor macro that collects the bits at compile-time. As a sample see macro ALIB_COMPILATION_FLAGS.
- The constructor of the derived module needs to be defined in a compilation unit of the module (aka not inline) and needs to pass the macro as the value for optional parameter compilationFlags to this class's constructor.
- The constructor of the derived module needs to fill field CompilationFlagMeanings.
The user of the module now invokes this method in bootstrap, hence preferably at the beginning of method bootstrap with BootstrapPhases::PrepareResources.

In case they are different in a way that the module gets incompatible (e.g. different class sizes, which results in errors which are confusing the debugger), the flags are written to std::cout for comparison and false is returned.

Parameters

compilationFlags The flags as defined in invoking compilation unit. Defaults to ALIB_COMPILATION_FLAGS.

Returns: true if compatible, false else.

Definition at line 354 of file module.cpp.

Member Data Documentation

◆ bootstrapState

int bootstrapState = 0

protected

State of initialization, used to avoid double initialization.

Definition at line 102 of file module.hpp.

◆ CompilationFlagMeanings

std::vector<std::pair <const nchar*, uint64_t> > CompilationFlagMeanings

This is for the creation of output on information about the bits found in field CompilationFlags. Declared public to allow exposure, e.g. in verbose logging.

See also: Method VerifyCompilationFlags for more information.

Definition at line 188 of file module.hpp.

◆ CompilationFlags

const uint64_t CompilationFlags

These flags are used internally to detect incompatibilities when linking ALib to binaries that use different compilation flags. Declared public to allow exposure, e.g. in verbose logging.

See also: Method VerifyCompilationFlags for more information.

Definition at line 180 of file module.hpp.

◆ config

config::Configuration* config = nullptr

protected

Pointer to the configuration instance used to load variable configuration data. An instance is created and assigned with the invocation of one of the Bootstrap methods. This instance is then passed to all dependent libraries (recursively) and this way shared. Dependent libraries that are to an own dedicated instance, have to be initialized explicitly prior to initializing this module.

Access to the field is provided with method GetConfig.

Note: This field is available only with ALib module Configuration included.

Definition at line 138 of file module.hpp.

◆ isConfigOwner

bool isConfigOwner = false

protected

If a configuration instance has been created when this module was initialized, this flag evaluates to true and the instance stored in config will be deleted with destruction of this object.

Definition at line 145 of file module.hpp.

◆ isResourceOwner

bool isResourceOwner = false

protected

If a default instance of type LocalResourcePool has been created when this module was initialized, this flag evaluates to true and the instance stored in resourcePool will be deleted with destruction of this object.

Definition at line 121 of file module.hpp.

◆ microModulesInitialized

bool microModulesInitialized = false

staticprotected

State of initialization of the "micro modules".

Definition at line 105 of file module.hpp.

◆ ResourceCategory

NCString ResourceCategory

The name of the configuration category of configuration variables used by this module.
ALib itself uses "ALIB". ALib modules use the naming scheme ALIB_{MODULE_NAMESPACE}.

Definition at line 172 of file module.hpp.

◆ resourcePool

resources::ResourcePool* resourcePool = nullptr

protected

Pointer to the resource pool. An instance is created and assigned with the invocation of one of the Bootstrap methods. This instance is then passed to all dependent libraries (recursively) and this way shared. Dependent libraries that are to an own dedicated instance, have to be initialized explicitly prior to initializing this module.

Definition at line 114 of file module.hpp.

◆ Revision

const int Revision

The revision number of this release. Usually a module is initially released as revision 0. Pure bug-fix releases that do not change the interface of ALib are holding the same Version but an increased number in this field.

Definition at line 165 of file module.hpp.

◆ Version

const int Version

The module version. Standard ALib versioning scheme is YYMM (as integer number) of the module release date. Besides this version number, field Revision indicates if this is a revised version of a former release.

Definition at line 158 of file module.hpp.

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

Class Description

Reference Documentation

Public Types

Public Fields

Public Methods

Protected Static Fields

Protected Fields

Protected Methods

Member Enumeration Documentation

◆ BootstrapPhases

◆ ShutdownPhases

Constructor & Destructor Documentation

◆ Module() [1/3]

◆ Module() [2/3]

◆ Module() [3/3]

◆ ~Module()

Member Function Documentation

◆ bootstrap()

◆ Bootstrap() [1/2]

◆ Bootstrap() [2/2]

◆ BootstrapResource()

◆ BootstrapSetConfig()

◆ BootstrapSetResourcePool()

◆ GetConfig()

◆ GetResource()

◆ GetResourcePool()

◆ IsBootstrapped()

◆ operator=() [1/2]

◆ operator=() [2/2]

◆ shutdown()

◆ Shutdown()

◆ TryResource()

◆ VerifyCompilationFlags()

Member Data Documentation

◆ bootstrapState

◆ CompilationFlagMeanings

◆ CompilationFlags

◆ config

◆ isConfigOwner

◆ isResourceOwner

◆ microModulesInitialized

◆ ResourceCategory

◆ resourcePool

◆ Revision

◆ Version