ALib C++ Library
Library Version: 2510 R0
Documentation generated by doxygen
Loading...
Searching...
No Matches
ALib Module Camp - Programmer's Manual

1. Introduction

This module is the fundament for the subset of ALib Modules that we call ALib Camps.

Please Read Now:
To avoid redundancy, we would ask you to read the short chapter 2.6 ALib Camps of the Programmer's Manual of ALib, which gives an explanation to this statement.

The three key aspects mentioned in the link above — 1) managing externalized resources, 2) accessing external configuration, and 3) defining a bootstrap process — are relevant to most software, even to small command-line tools. However, these areas are not well-supported by the C++ language and also the introduction of C++20 Modules left these challenges unresolved.

This module addresses these issues by introducing the virtual interface Camp, which is designed to handle these three concerns. Other ALib Modules already integrate this interface, and custom code units can also derive one or more types from it as needed.

In traditional application design, there is typically a centralized application class managing these responsibilities. From a broader perspective, ALib Camps offer an alternative by allowing the delegation of these tasks to the specific code entities responsible for them. Put simply, conventional software design often relies on each code unit being aware of a central application class that provides the necessary interfaces. This can lead to circular dependencies between the application class and the code units. One of the primary goals of this module is to eliminate such design limitations.

2. Class Camp

To implement the proposed functionality, class Camp relies on the aggregation of functionality stemming from other ALib Modules.
Let us look at them one by one:

2.1 Resource Management

For resource management, the class provides a pointer to an instance of the virtual class ResourcePool defined in the module ALib Resources. Derived types can use inherited methods

to access externalized string resources conveniently.

2.2 Configuration Data

For external configuration data, the class provides a pointer to an instance of class Configuration, defined in the module ALib Variables. Derived types can retrieve this instance with method Camp::GetConfig and with that get access to ALib run-time variables.

In this context, one core feature of ALib Variables is that their values can transparently emerge from

  • command-line parameters,
  • environment variables,
  • configuration files, or
  • any other external configuration system.

This gives access to such data at the place where it is needed.

Note that run-time variables can also be be defined by other code entities to share information between modules.

2.3 Bootstrapping and Shutdown

Implementing a well-defined bootstrap and shutdown process is the responsibility of the overarching module ALib Bootstrap. The namespace functions alib::Bootstrap and alib::Shutdown change their signature, depending on the inclusion of this module ALib Camp in the ALib Build. Without the inclusion of any ALib Camp, a heavily simplified bootstrap and shutdown process is in place, which calls corresponding bootstrap- and shutdown-functions of certain non-camp modules (among only a few other things).

The altered versions of the functions allow to either share or not share resources and configuration data between the different ALib Camps. This is why the internal field members Camp::resourcePool and Camp::config are implemented as pointer types.

Furthermore, the altered functions divide the processes into different phases. For each phase, they invoke the abstract virtual methods Bootstrap, and Shutdown which have to be implemented by derived classes.

Finally, the bootstrap functions also make sure that the built-in ALib Camps are initialized in the right order, namely from lower-level camps to higher ones. The same applies for the shutdown process, but in reverse order.

All information about

  • how default bootstrapping works,
  • how an application can alter this default to adjust the distribution of different configuration and resource management instances, and
  • how a using code may inject own ALib Camps into these processes,

is documented with the Programmer's Manual of module ALib Bootstrap.

When developing custom camps, the Programmer's Manuals of the modules ALib Resources and ALib Variables should be consulted as well. A good jump-start to copy from could be the straightforward reference implementation found in the ALib Files camp.

3. The Basecamp

In the introduction to this manual, it was explained that the ALib Camp module introduces the Camp class. Each module designed to be an ALib Camp must provide a singleton instance derived from this class.

Below is a summary of the currently available camps in ALib:

Module Camp Class Singleton Instance
ALib ALox alib::lox::ALoxCamp alib::ALOX
ALib Camp alib::camp::Basecamp alib::BASECAMP
ALib CLI alib::cli::CliCamp alib::CLI
ALib Expressions alib::expressions::ExpressionsCamp alib::EXPRESSIONS
ALib Files alib::files::FilesCamp alib::FILES

As shown in the table, this very module creates its own singleton instance with alib::BASECAMP. Consequently, it qualifies as an ALib Camp itself.

A natural question might arise: why would a module like this, which mainly provides the interface class Camp, require any extensive setup, resources, or configuration?

The answer lies in the way this module subtly enhances functionality. When included in the ALib Build, it replaces some lower-level resources, primarily related to ALib Enum Records. Without this module, these records are usually hardcoded or just unavailable. By incorporating this module, the build process dynamically constructs these records during the module's bootstrap phase. This approach takes advantage of the externalized resources managed by the Basecamp class, doing away with the hard-coded implementation via preprocessor directives.
This improvement applies not just to enum records but also to a variety of format strings and exception-related messages (notably in the ALib Format and ALib System modules).

Additionally, during bootstrap, the Basecamp class reads and processes external ALib Configuration Variables.

For those curious about the full range of tasks this module performs, the source code of the Basecamp implementation serves as a useful reference.

For developers looking to create custom camp-modules, it is recommended to begin with the much simpler and more straightforward reference implementation found in the ALib Files camp.

4. Extensions For ALib Variables

The inclusion of this module with the header ALib.Camp.H, injects various overloads of the function CampVariable into the namespace alib::variables of the module ALib Variables.
These functions are inline shortcuts used for creating variables associated with the Configuration instance found in a Camp.