ALib C++ Library
Library Version: 2312 R0
Documentation generated by doxygen
lib/fs_modules/distribution.hpp
Go to the documentation of this file.
1 /** ************************************************************************************************
2  * \file
3  * This header file is part of file set \alibfs_modules of the \aliblong.
4  *
5  * \emoji :copyright: 2013-2023 A-Worx GmbH, Germany.
6  * Published under \ref mainpage_license "Boost Software License".
7  **************************************************************************************************/
8 #ifndef HPP_ALIB_FS_MODULES_DISTRIBUTION
9 #define HPP_ALIB_FS_MODULES_DISTRIBUTION 1
10 
11 #if !defined(HPP_ALIB_FS_MODULES_MODULE)
12 # include "alib/lib/fs_modules/module.hpp"
13 #endif
14 
15 #if ALIB_CONFIGURATION && !defined(HPP_ALIB_CONFIG_VARIABLEDECL)
16 # include "alib/config/variabledecl.hpp"
17 #endif
18 
19 #if !defined(HPP_ALIB_MONOMEM_LIST)
20 # include "alib/monomem/list.hpp"
21 #endif
22 
23 
24 ALIB_ASSERT_FILESET(MODULES)
25 
26 // #################################################################################################
27 // Compilation flags
28 // Create a bitset from the ALib compilation features.
29 // For this, we ensure that the individual headers tested are included
30 // #################################################################################################
31 
32 #if ALIB_SINGLETONS && !defined(HPP_ALIB_SINGLETONS_SINGLETON) && !defined(ALIB_DOX)
33 # include "alib/singletons/singleton.hpp"
34 #endif
35 
36 #if ALIB_BOXING && !defined(HPP_ALIB_BOXING_BOXING) && !defined(ALIB_DOX)
37 # include "alib/boxing/boxing.hpp"
38 #endif
39 
40 
41 #if !defined(ALIB_DOX)
42 
43 # define ALIB_VFYBIT_DEBUG (1LLU << 0)
44 
45 # define ALIB_VFYBIT_MODULE_MONOMEM (1LLU << 1)
46 # define ALIB_VFYBIT_MODULE_SINGLETONS (1LLU << 2)
47 # define ALIB_VFYBIT_MODULE_CHARACTERS (1LLU << 3)
48 # define ALIB_VFYBIT_MODULE_ENUMS (1LLU << 4)
49 # define ALIB_VFYBIT_MODULE_TIME (1LLU << 5)
50 # define ALIB_VFYBIT_MODULE_BOXING (1LLU << 6)
51 # define ALIB_VFYBIT_MODULE_STRINGS (1LLU << 7)
52 # define ALIB_VFYBIT_MODULE_BITBUFFER (1LLU << 8)
53 # define ALIB_VFYBIT_MODULE_RESOURCES (1LLU << 9)
54 # define ALIB_VFYBIT_MODULE_THREADS (1LLU << 10)
55 # define ALIB_VFYBIT_MODULE_TEXT (1LLU << 11)
56 # define ALIB_VFYBIT_MODULE_RESULTS (1LLU << 12)
57 # define ALIB_VFYBIT_MODULE_SYSTEM (1LLU << 13)
58 # define ALIB_VFYBIT_MODULE_CONFIGURATION (1LLU << 14)
59 # define ALIB_VFYBIT_MODULE_ALOX (1LLU << 15)
60 # define ALIB_VFYBIT_MODULE_EXPRESSIONS (1LLU << 16)
61 # define ALIB_VFYBIT_MODULE_CLI (1LLU << 17)
62 
63 # define ALIB_VFYBIT_FEAT_SINGLETON_MAPPED (1LLU << 40)
64 
65 # define ALIB_VFYBIT_CHARACTERS_WIDE (1LLU << 41)
66 # define ALIB_VFYBIT_CHARACTERS_WCHAR_IS_4 (1LLU << 42)
67 
68 # define ALIB_VFYBIT_FEAT_BOXING_BIJECTIVE_INTEGRALS (1LLU << 43)
69 # define ALIB_VFYBIT_FEAT_BOXING_BIJECTIVE_CHARACTERS (1LLU << 44)
70 # define ALIB_VFYBIT_FEAT_BOXING_BIJECTIVE_FLOATS (1LLU << 45)
71 
72 # define ALIB_VFYBIT_DEBUG_STRINGS (1LLU << 46)
73 # define ALIB_VFYBIT_DEBUG_BOXING (1LLU << 47)
74 # define ALIB_VFYBIT_DEBUG_MONOMEM_MONOMEM (1LLU << 48)
75 # define ALIB_VFYBIT_DEBUG_RESOURCES (1LLU << 49)
76 
77 # define ALOX_VFYBIT_DBG_LOG (1LLU << 50)
78 # define ALOX_VFYBIT_DBG_LOG_CI (1LLU << 51)
79 # define ALOX_VFYBIT_REL_LOG (1LLU << 52)
80 # define ALOX_VFYBIT_REL_LOG_CI (1LLU << 53)
81 
82 
83 
84 
85 #if ALIB_ALOX
86 # if !defined(HPP_ALOX_PREDEF) && !defined(HPP_ALIB_ALOX)
87 # include "alib/alox/alox.hpp"
88 # endif
89 # define ALIB_COMPILATION_FLAGS_ALOX \
90  ( ALOX_VFYBIT_DBG_LOG * ALOX_DBG_LOG \
91  + ALOX_VFYBIT_DBG_LOG_CI * ALOX_DBG_LOG_CI \
92  + ALOX_VFYBIT_REL_LOG * ALOX_REL_LOG \
93  + ALOX_VFYBIT_REL_LOG_CI * ALOX_REL_LOG_CI \
94  )
95 #else
96 # define ALIB_COMPILATION_FLAGS_ALOX 0
97 #endif
98 
99 
100 
101 # define ALIB_COMPILATION_FLAGS \
102 ( ALIB_VFYBIT_DEBUG * ALIB_DEBUG \
103  \
104  + ALIB_VFYBIT_MODULE_MONOMEM * ALIB_MONOMEM \
105  + ALIB_VFYBIT_MODULE_SINGLETONS * ALIB_SINGLETONS \
106  + ALIB_VFYBIT_MODULE_CHARACTERS * ALIB_CHARACTERS \
107  + ALIB_VFYBIT_MODULE_ENUMS * ALIB_ENUMS \
108  + ALIB_VFYBIT_MODULE_TIME * ALIB_TIME \
109  + ALIB_VFYBIT_MODULE_BOXING * ALIB_BOXING \
110  + ALIB_VFYBIT_MODULE_STRINGS * ALIB_STRINGS \
111  + ALIB_VFYBIT_MODULE_BITBUFFER * ALIB_BITBUFFER \
112  + ALIB_VFYBIT_MODULE_RESOURCES * ALIB_RESOURCES \
113  + ALIB_VFYBIT_MODULE_THREADS * ALIB_THREADS \
114  + ALIB_VFYBIT_MODULE_TEXT * ALIB_TEXT \
115  + ALIB_VFYBIT_MODULE_RESULTS * ALIB_RESULTS \
116  + ALIB_VFYBIT_MODULE_SYSTEM * ALIB_SYSTEM \
117  + ALIB_VFYBIT_MODULE_CONFIGURATION * ALIB_CONFIGURATION \
118  + ALIB_VFYBIT_MODULE_ALOX * ALIB_ALOX \
119  + ALIB_VFYBIT_MODULE_EXPRESSIONS * ALIB_EXPRESSIONS \
120  + ALIB_VFYBIT_MODULE_CLI * ALIB_CLI \
121  \
122  + ALIB_VFYBIT_FEAT_SINGLETON_MAPPED * ALIB_FEAT_SINGLETON_MAPPED \
123  \
124  + ALIB_VFYBIT_CHARACTERS_WIDE * ALIB_CHARACTERS_WIDE \
125  + ALIB_VFYBIT_CHARACTERS_WCHAR_IS_4 * (ALIB_CHARACTERS_SIZEOF_WCHAR == 4 ? 1 : 0) \
126  \
127  + ALIB_VFYBIT_FEAT_BOXING_BIJECTIVE_INTEGRALS * ALIB_FEAT_BOXING_BIJECTIVE_INTEGRALS \
128  + ALIB_VFYBIT_FEAT_BOXING_BIJECTIVE_CHARACTERS * ALIB_FEAT_BOXING_BIJECTIVE_CHARACTERS \
129  + ALIB_VFYBIT_FEAT_BOXING_BIJECTIVE_FLOATS * ALIB_FEAT_BOXING_BIJECTIVE_FLOATS \
130  \
131  + ALIB_VFYBIT_DEBUG_STRINGS * ALIB_DEBUG_STRINGS \
132  + ALIB_VFYBIT_DEBUG_BOXING * ALIB_DEBUG_BOXING \
133  + ALIB_VFYBIT_DEBUG_MONOMEM_MONOMEM * ALIB_DEBUG_MONOMEM \
134  + ALIB_VFYBIT_DEBUG_RESOURCES * ALIB_DEBUG_RESOURCES \
135  \
136  + ALIB_COMPILATION_FLAGS_ALOX \
137 )
138 #endif //ALIB_DOX
139 
140 namespace aworx { namespace lib {
141 
142 // #################################################################################################
143 // Variables
144 // #################################################################################################
145 #if ALIB_CONFIGURATION
146  /**
147  * Configuration variables of \alib.
148  * \note
149  * As required by module \alib_config, this enumerations is equipped with
150  * \ref alib_enums_records "ALib Enum Records" of type \alib{config,VariableDecl}
151  * and resourced with this module.<br>
152  * Hence, all variable categories, names, default values and such can be modified
153  * by modifying the resource data of the singleton of class \aworx{lib,ALibDistribution}.
154  */
155  enum class Variables
156  {
157  LOCALE = 1 , ///< \alib Resourced variable.
158  WAIT_FOR_KEY_PRESS = 2 , ///< \alib Resourced variable.
159  HAS_CONSOLE_WINDOW = 3 , ///< \alib Resourced variable.
160  };
161 #endif // ALIB_CONFIGURATION
162 
163 
164 /** ************************************************************************************************
165  * This is a special module singleton that provides some "knowledge" about the modules contained
166  * in a distribution. It offers method #BootstrapFillDefaultModuleList which is used
167  * by method \alib{Module::Bootstrap} in the case that the module list was not externally customized
168  * and filled already.
169  *
170  * Usually, this module is the one that method \b Module::Bootstrap is invoked on.
171  * All details on this topic are given in chapter
172  * \ref alib_manual_bootstrapping "3. Bootstrapping ALib" of the \ref alib_manual.
173  *
174  * Besides that, the class provides a few utility members that have not found a different home
175  * with the current version of the library.
176  *
177  * This is a strict singleton class. The only instance is found with namespace variable
178  * \ref aworx::ALIB.
179  **************************************************************************************************/
180 class ALibDistribution : public Module
181 {
182  // #############################################################################################
183  // Public fields
184  // #############################################################################################
185  public:
186  /**
187  * Lists all modules in the order of bootstrapping. Shutdown is performed in reverse order.
188  * This list is used by method \alib{Module::Bootstrap}, regardless on which module it was
189  * invoked. If the list is empty at the time of invocation, method Module::Bootstrap
190  * will use this class's method #BootstrapFillDefaultModuleList to fill it with the default
191  * \alib modules in the right order.
192  *
193  * To customize the list (append own modules), method #BootstrapFillDefaultModuleList may
194  * be invoked prior to \b Module::Bootstrap and afterwards the list might be extended.
195  *
196  * \see Chapter \ref alib_manual_bootstrapping_class_alibdistribution and the following
197  * ones to learn about how to customize bootstrapping in various ways.
198  */
199  List<Module*> Modules;
200 
201  /**
202  * If \c true, within #Shutdown, it is waited for a key press in the console
203  * window.<br>
204  * By default, this flag is enabled when debugging a console application under Visual
205  * Studio.<br>
206  * This default behavior can be overruled by setting configuration variable
207  * \https{ALIB_WAIT_FOR_KEY_PRESS,alexworx.github.io/ALox-Logging-Library/group__GrpALoxConfigVars.html}.
208  * <br>In addition, this public flag may be modified at run-time (after method #Bootstrap was
209  * invoked).
210  */
211  bool WaitForKeyPressOnTermination =false;
212 
213  /**
214  * This flag indicates if the current process has console output window attached.
215  * While this is not detectable in Unix like systems (or just with huge efforts), in
216  * windows it is. The determination is performed in #bootstrap and done as follows
217  * - If configuration variable \b ALIB_HAS_CONSOLE_WINDOW
218  * is set, its value is returned.
219  * - Otherwise, on Unix like OS\c true is returned.
220  * - On Windows OS it is determined if a console window is attached to the process
221  * using system call \e GetConsoleWindow() and compare its result to \e NULL.
222  *
223  * In addition, this public flag may be modified at run-time (after method #Bootstrap was
224  * invoked).
225  *
226  * \note
227  * The evaluation of configuration variable \b ALIB_HAS_CONSOLE_WINDOW is done
228  * only if module \alib_config is included in the \alibdist.
229  */
230  bool HasConsoleWindow;
231 
232  /**
233  * This string is set during bootstrapping in the case that a locale information was
234  * found (via standard environment variables or \alib variable \aworx{lib,Variables,LOCALE})
235  * and successfully set.<br>
236  * Otherwise this string is \e nulled.
237  */
238  String LocaleFound;
239 
240  /**
241  * The command line arguments stored for convenience.
242  * Only available, if (recursive) module initialization was performed with
243  * \alib{Module::Bootstrap(int, nchar**,BootstrapPhases)} or
244  * \alib{Module::Bootstrap(int, wchar**,BootstrapPhases)}.
245  */
246  int ArgC = 0;
247 
248  /**
249  * The command line arguments stored for convenience.
250  * Only available, if (recursive) module initialization was performed with
251  * \alib{Module::Bootstrap(int, char**,BootstrapPhases)}.
252  */
253  const char** ArgVN = nullptr;
254 
255  /**
256  * The command line arguments stored for convenience.
257  * Only available, if (recursive) module initialization was performed with
258  * \alib{Module::Bootstrap(int, wchar_t**,BootstrapPhases)}.
259  */
260  const wchar_t** ArgVW = nullptr;
261 
262  // #############################################################################################
263  // Construction/Destruction
264  // #############################################################################################
265  /** ****************************************************************************************
266  * Constructor.<br>
267  * While this is public, it must not be invoked as this is a strict singleton type.
268  * (See notes in \ref alib_manual_bootstrapping_class_module_singletons).
269  ******************************************************************************************/
270  ALibDistribution();
271 
272  // #############################################################################################
273  // Environment definition/detection
274  // #############################################################################################
275  public:
276 
277  #if ALIB_SYSTEM
278  /** ************************************************************************************
279  * If \c true, the current process is under the hood of a debugger.
280  *
281  * \note
282  * This method is available only if module \alib_system is included in the
283  * \alibdist.
284  *
285  * @return \c true if the application is run in a debugger.
286  **************************************************************************************/
287  ALIB_API
288  bool IsDebuggerPresent();
289 
290  #endif
291 
292  // #############################################################################################
293  // Compilation Flags
294  // #############################################################################################
295  public:
296 
297  /** ****************************************************************************************
298  * Checks the versions of \alib and whether the current compilation unit shares compatible
299  * compiler symbols with the \alib binaries. The latter is done by invoking
300  * inherited method \alib{Module::VerifyCompilationFlags}.
301  *
302  * This method should be invoked in the bootstrap code of your processes and libraries
303  * to check for compilation and linkage mismatch.
304  *
305  * Parameter \p{alibVersion} defaults to macro \ref ALIB_VERSION and
306  * parameter \p{compilationFlags} to macro \ref ALIB_COMPILATION_FLAGS.
307  * Both parameters should not be given when invoked.
308  * This value is internally matched against what they were when \alib was compiled.
309  *
310  * \see
311  * For more information, see chapter
312  * \ref alib_manual_bootstrapping_assertcomp "3.9 Assuring Compilation Compatibility"
313  * of the \ref alib_manual.
314  *
315  *
316  * @param alibVersion The \alib version required.
317  * Defaults to \ref ALIB_VERSION and should not be passed.
318  * @param compilationFlags The flags as defined in invoking compilation unit.
319  * Defaults to \ref ALIB_COMPILATION_FLAGS and should not be passed.
320  ******************************************************************************************/
321  ALIB_API
322  void CheckDistribution( int alibVersion = ALIB_VERSION,
323  uint64_t compilationFlags = ALIB_COMPILATION_FLAGS );
324 
325  // #############################################################################################
326  // Methods for being a module ourselves
327  // #############################################################################################
328  public:
329  /** ****************************************************************************************
330  * Fills list #Modules, taking the permutation of modules contained in the \alibdist into
331  * account.
332  ******************************************************************************************/
333  ALIB_API
334  void BootstrapFillDefaultModuleList();
335 
336 
337  protected:
338  /** ****************************************************************************************
339  * Implementation of \alib{Module::bootstrap}.
340  *
341  * In phase \alib{Module,BootstrapPhases::Final} performs:
342  * - In glibc versions of \alib (GNU/unix) probably invoke glibc method
343  * <em>setlocale()</em>, depending on the setting of the environment variables
344  * <em>LANG</em> and <em>LANGUAGE</em>
345  * and depending on \alib configuration variable
346  * \https{ALIB_LOCALE,alexworx.github.io/ALox-Logging-Library/group__GrpALoxConfigVars.html}.
347  *
348  * In addition, invokes
349  * \alib{strings,TNumberFormat::SetFromLocale,NumberFormat::SetFromLocale} on static singleton
350  * \alib{strings,TNumberFormat::Global,NumberFormat::Global}.
351  *
352  * - Config variable
353  * \https{WAIT_FOR_KEY_PRESS,alexworx.github.io/ALox-Logging-Library/group__GrpALoxConfigVars.html}
354  * is read and field #WaitForKeyPressOnTermination set accordingly
355  *
356  *
357  * @param phase The initialization phase to perform.
358  * @param argc The number of command line arguments. Defaults to \c 0.
359  * @param argv List of command line arguments if given as single byte character strings.
360  * @param wargv List of command line arguments if given as multi-byte character strings.
361  ******************************************************************************************/
362  virtual void bootstrap( BootstrapPhases phase,
363  int argc, const char** argv, const wchar_t** wargv ) override;
364 
365  /** ****************************************************************************************
366  * Terminates this module.
367  * @param phase The shutdown phase to perform.
368  ******************************************************************************************/
369  virtual void shutdown( ShutdownPhases phase ) override;
370 
371 
372 };// class ALibDistribution
373 
374 } // namespace aworx[::lib]
375 
376 /** The singleton of module-class \alib{ALibDistribution}. */
377 extern ALIB_API lib::ALibDistribution ALIB;
378 
379 } // namespace [aworx]
380 
381 #if ALIB_CONFIGURATION
382  ALIB_ENUMS_ASSIGN_RECORD( aworx::lib::Variables, aworx::lib::config::VariableDecl )
383  ALIB_RESOURCED_IN_MODULE( aworx::lib::Variables, aworx::ALIB, "Var" )
384 #endif
385 
386 
387 #endif // HPP_ALIB_FS_MODULES_DISTRIBUTION
ALIB_RESOURCED_IN_MODULE
#define ALIB_RESOURCED_IN_MODULE(T, Module, ResName)
Definition: resources.hpp:648
aworx::lib::monomem::List
Definition: monomem/fwds.hpp:57
aworx::lib::ALibDistribution::ArgC
int ArgC
Definition: lib/fs_modules/distribution.hpp:246
aworx::lib::ALibDistribution::CheckDistribution
ALIB_API void CheckDistribution(int alibVersion=ALIB_VERSION, uint64_t compilationFlags=ALIB_COMPILATION_FLAGS)
Definition: distribution.cpp:612
aworx::lib::Module::ShutdownPhases
ShutdownPhases
Definition: module.hpp:88
aworx::lib::ALibDistribution
Definition: lib/fs_modules/distribution.hpp:180
aworx::lib::ALibDistribution::BootstrapFillDefaultModuleList
ALIB_API void BootstrapFillDefaultModuleList()
Definition: distribution.cpp:191
ALIB_ASSERT_FILESET
#define ALIB_ASSERT_FILESET(filesetname)
Definition: modules.hpp:242
aworx::lib::Module::BootstrapPhases
BootstrapPhases
Definition: module.hpp:78
aworx::lib::ALibDistribution::LocaleFound
String LocaleFound
Definition: lib/fs_modules/distribution.hpp:238
aworx::lib::strings::TString< character >
aworx::lib::ALibDistribution::IsDebuggerPresent
ALIB_API bool IsDebuggerPresent()
Definition: distribution.cpp:576
alox.hpp
list.hpp
aworx::lib::ALibDistribution::ArgVN
const char ** ArgVN
Definition: lib/fs_modules/distribution.hpp:253
aworx::lib::ALibDistribution::bootstrap
virtual void bootstrap(BootstrapPhases phase, int argc, const char **argv, const wchar_t **wargv) override
Definition: distribution.cpp:215
variabledecl.hpp
aworx::lib::ALibDistribution::ALibDistribution
ALibDistribution()
Definition: distribution.cpp:133
aworx::lib::ALibDistribution::ArgVW
const wchar_t ** ArgVW
Definition: lib/fs_modules/distribution.hpp:260
ALIB_COMPILATION_FLAGS
#define ALIB_COMPILATION_FLAGS
aworx
Definition: alox/alox.hpp:40
aworx::lib::ALibDistribution::HasConsoleWindow
bool HasConsoleWindow
Definition: lib/fs_modules/distribution.hpp:230
aworx::ALIB
lib::ALibDistribution ALIB
Definition: distribution.cpp:125
aworx::lib::Variables::LOCALE
ALib Resourced variable.
module.hpp
ALIB_ENUMS_ASSIGN_RECORD
#define ALIB_ENUMS_ASSIGN_RECORD(TEnum, TRecord)
Definition: records.hpp:769
aworx::lib::Variables
Variables
Definition: lib/fs_modules/distribution.hpp:155
ALIB_API
#define ALIB_API
Definition: compilers.hpp:150
aworx::lib::Variables::WAIT_FOR_KEY_PRESS
ALib Resourced variable.
boxing.hpp
ALIB_VERSION
#define ALIB_VERSION
Definition: modules.hpp:20
aworx::lib::Variables::HAS_CONSOLE_WINDOW
ALib Resourced variable.
singleton.hpp
aworx::lib::ALibDistribution::shutdown
virtual void shutdown(ShutdownPhases phase) override
Definition: distribution.cpp:532
aworx::lib::Module
Definition: module.hpp:74
aworx::lib::ALibDistribution::Modules
List< Module * > Modules
Definition: lib/fs_modules/distribution.hpp:199
aworx::lib::ALibDistribution::WaitForKeyPressOnTermination
bool WaitForKeyPressOnTermination
Definition: lib/fs_modules/distribution.hpp:211
aworx::lib::config::VariableDecl
Definition: variabledecl.hpp:109