ALib C++ Library
Library Version: 2510 R0
Documentation generated by doxygen
Loading...
Searching...
No Matches
camp.inl
Go to the documentation of this file.
1//==================================================================================================
2/// \file
3/// This header-file is part of module \alib_camp of the \aliblong.
4///
5/// \emoji :copyright: 2013-2025 A-Worx GmbH, Germany.
6/// Published under \ref mainpage_license "Boost Software License".
7//==================================================================================================
8ALIB_EXPORT namespace alib {
9
10//==================================================================================================
11/// Initialization levels usable with
12/// \ref alib_mod_bs_camps "Bootstrapping ALib Camps".
13//==================================================================================================
15{
16 /// Field \alib{camp;Camp::resourcePool} is created when this phase is called for a camp.
17 /// Camps are requested to feed in their resources now. When this is done, all entities that
18 /// rely exclusively on resources are to be initialized. For example, all resourced enumerations
19 /// of a camp should be parsed in this phase.
21
22 /// Field \alib{camp;Camp::config} is created when this phase is called for a camp.
23 /// Camps are requested to
24 /// \alib{variables;Configuration::RegisterType;register application-specific variable types} in
25 /// this phase. Furthermore modifications on the configuration object itself might be performed,
26 /// for example \alib{variables;ConfigurationPlugin;custom plugins} might be added to a
27 /// configuration or configurable options of default plug-ins can be set.<br>
28 /// Finally, this is the right phase to
29 /// \alib{variables;Configuration::PreloadVariables;declare variables} which have a resourced
30 /// variable declaration, or likewise perform 'hard-coded' variable declarations including
31 /// their default values.
33
34 /// The final initialization phase. Here, camps are initializing their custom setup.
35 Final = 3,
36};
37
38//==================================================================================================
39/// Termination levels usable with \ref alib_mod_bs_camps "Bootstrapping ALib Camps".
40//==================================================================================================
42{
43 Announce = 1, ///< Signals termination. Keeps resources, config, etc.
44 ///< intact. Usable to write configuration data, stop
45 ///< background threads, etc.
46 Destruct = 2, ///< The main phase of termination that destructs everything.
47};
48
49namespace camp {
50
51//==================================================================================================
52/// This class is used by \alib to
53///
54/// - manage library bootstrap and termination,
55/// - provide \ref alib_mod_resources "resources" and to
56/// - provide Configuration data (e.g., configuration files, command line parameters, etc.).
57///
58/// Typically, every "bigger" and "higher level" \alibmod disposes of a type derived from this
59/// class. The singleton instances of these types are collected in namespace \ref alib and are named
60/// in capital letters, for example \ref alib::ALOX, \ref alib::EXPRESSIONS, etc.
61///
62/// Types found in an \alibmod_nl, will use methods \alib{camp::Camp;GetResourcePool} and
63/// \alib{camp::Camp;GetConfig} of that singleton to access resources and to read and write
64/// configuration data.
65/// With that, it has to be kept in mind that these objects most probably are shared with other
66/// camps. As a consequence, clear and understandable resource and variable categories and names
67/// are to be used, to avoid conflicting entries.
68///
69/// The \ref alib_mod_bs "Programmer's Manual" of module \alib_bootstrap_nl explains how
70/// bootstrapping and shutting down \alib is performed with the help of this class.<br>
71/// Furthermore, source code sample is given with the
72/// \ref alib_cli_tut "tutorial of ALib Module CLI".
73///
74/// Often, types that comprise a "camp singleton" (as the derived types shown in the inheritance
75/// diagram above) incorporate some further functionality specific to the field of application that
76/// a "module" respectively "camp" covers.
77///
78/// # Reference Documentation #
79//==================================================================================================
80class Camp
81{
82 public:
83 /// Type definition used for sharing resource-pool instances. With default-bootstrapping,
84 /// an instance of type \alib{resources;LocalResourcePool} is used here, which is
85 /// created with allocator instance \alib{monomem;GLOBAL_ALLOCATOR}.
87
88 protected:
89 /// State of initialization, used to avoid double initialization as well as initialization
90 /// "gaps".
92
93 /// Shared pointer to the resource pool.
94 /// @see Function #BootstrapSetResourcePool.
96
97 /// Pointer to the configuration instance used to load variable configuration data.
98 /// An instance is created and assigned with the invocation of one of the #Bootstrap methods.
99 /// This instance is then passed to all dependent libraries (recursively) and this way
100 /// shared. Dependent libraries that are to an own dedicated instance, have to be
101 /// initialized explicitly before initializing this \alibcamp.
102 ///
103 /// Access to the field is provided with method #GetConfig.
105
106 // ##############################################################################################
107 // Public fields
108 // ##############################################################################################
109 public:
110 /// The name of the resource category of externalized string resources defined and used by
111 /// this \alibcamp.<br>
112 /// Special camp \alib{BASECAMP} uses "ALIB". Other \alibcamps_nl use a short unique name.
114
115 // #############################################################################################
116 // Constructor/Destructor
117 // #############################################################################################
118 /// Constructor.
119 /// @param resourceCategory Value for field #ResourceCategory.
120 Camp( const NCString& resourceCategory )
121 : ResourceCategory(resourceCategory)
122 {}
123
124 /// Deleted copy constructor.
125 Camp( const Camp& ) = delete;
126
127 /// Deleted move constructor.
128 Camp( Camp&& ) = delete;
129
130 /// Deleted copy assignment.
131 void operator=( const Camp& ) = delete;
132
133 /// Deleted move assignment.
134 void operator=( Camp&& ) = delete;
135
136
137 /// Virtual destructor to satisfy C++ abstract type rules.
138 virtual ~Camp()
139 {
141 || bootstrapState == 0, "CAMPS",
142 "Destructing a non-terminated camp. Camp Resource category is: \"{}\"", ResourceCategory )
143 }
144
145 // ###############################################################################################
146 // Bootstrap/Shutdown()
147 // ###############################################################################################
148 public:
149
150 /// Abstract method which is invoked during bootstrapping by function<br>
151 /// \doxlinkproblem{namespacealib.html;a78bb34888e5142adb87e265e23ee3c2e;alib::Bootstrap(BootstrapPhases targetPhase, camp::Camp* targetCamp, int,int,TCompilationFlags)}
152 /// for each \p{phase}, and each camp found in list \alib{CAMPS}.
153 /// Implementations of this function receive the phase to perform with #GetBootstrapState.
154 ///
155 /// This method is not to be called from outside, but is internally invoked by function
156 /// \ref alib::Bootstrap.
157 ///
158 /// For details on bootstrapping\alibcamps, see the detailed explanations in the
159 /// \ref alib_mod_bs "Programmer's Manual" of module \alib_bootstrap_nl.
160 virtual void Bootstrap() = 0;
161
162 /// Abstract method which is invoked during bootstrapping by function<br>
163 /// \doxlinkproblem{namespacealib.html;a4374717714582ef1a859b773367ec5d9;alib::Shutdown(ShutdownPhases targetPhase, camp::Camp* targetCamp)}
164 /// for each \p{phase}, and each camp found in list \alib{CAMPS}.
165 ///
166 /// This method is not to be called from outside, but is internally invoked by function
167 /// \ref alib::Bootstrap.
168 ///
169 /// For details on bootstrapping \alibcamps, see the detailed explanations in the
170 /// \ref alib_mod_bs "Programmer's Manual" of module \alib_bootstrap_nl.
171 /// @param phase The termination level to perform.
172 virtual void Shutdown( ShutdownPhases phase ) = 0;
173
174 /// Returns the bootstrap state of this camp.
175 /// @return The internal state flag.
177
178 /// Sets the (next) bootstrap phase to perform.
179 /// @param phase The upcomming phase.
181
182 /// Tests if this \alibcamp was completely initialized.
183 /// @return
184 /// \c true if the initialization state is either \alib{BootstrapPhases::Final}
185 /// or \alib{ShutdownPhases::Announce}, \c false otherwise.
191
192 // #############################################################################################
193 // Other public interface methods
194 // #############################################################################################
195 /// Sets the configuration instance of this camp.
196 ///
197 /// \attention
198 /// Note the documentation of sibling method #BootstrapSetResourcePool.
199 /// Here, the very same rules apply in respect to the distribution of configuration instances
200 /// between different camps and in respect to the customization of bootstrapping.
201 ///
202 /// @see Chapter \ref alib_mod_bs_customize of the Programmer's Manual of module
203 /// \alib_bootstrap.
204 /// @param pConfig The configuration to use.
206 {
207 ALIB_ASSERT_WARNING( (config == nullptr) != (pConfig == nullptr), "CAMPS",
208 "Double setting or removing a camp's configuration instance.\n"
209 "Note: A custom configuration must be set before camp initialization." )
210 config= pConfig;
211 }
212
213 /// Returns a reference (!) to the configuration object.
214 /// @return The configuration object set with bootstrapping.
216
217 /// Sets the resource pool of this camp.
218 /// By default, this function is called with \p{pResourcePool} holding an instance of type
219 /// \alib{resources;LocalResourcePool} when \alib is bootstrapped.
220 ///
221 /// In case a custom resource pool type (and/or instance) should be used with this camp,
222 /// a custom shared pointer has to be created and the custom pool has to be inserted
223 /// (potentially using method \alib{containers;SharedPtr::InsertDerived}).
224 /// Then this method has to be called on the camp prior to the invocation of
225 /// #alib::Bootstrap.
226 ///
227 /// Note that the Function \b %alib::Bootstrap will distribute the given instance to each
228 /// lower-level camp that has not received a different object. If this should be avoided
229 /// (to separate the resources of this camp from lower level camps), a
230 /// \ref alib_mod_bs_customize "further customized bootstrap strategy" has to be implemented.
231 /// @param pResourcePool The resource pool to use.
232 void BootstrapSetResourcePool( const SPResourcePool& pResourcePool )
233 {
234 ALIB_ASSERT_WARNING( (resourcePool == nullptr) != (pResourcePool == nullptr), "CAMPS",
235 "Double setting or removing a camp's resource pool instance.\n"
236 "Note: A custom resource pool must be set before camp initialization." )
237
238 resourcePool = pResourcePool;
239 }
240
241 /// Returns a reference (!) to the \b SharedPtr holding the resource pool.
242 /// @return The resource pool set with bootstrapping.
244
245 /// Shortcut method that invokes \alib{resources;ResourcePool::Bootstrap} on field
246 /// #resourcePool providing field #ResourceCategory as parameter.
247 /// @param name The resource name.
248 /// @param data The resource data string.
249 inline
250 void BootstrapResource( const NString& name, const String& data ) {
251 resourcePool->Bootstrap( ResourceCategory, name, data );
252 }
253
254 /// Shortcut method that invokes \alib{resources;ResourcePool::Get} on field
255 /// #resourcePool providing field #ResourceCategory as parameter.
256 ///
257 /// With debug-builds, this method asserts that a resource was found. If this is not
258 /// wanted, use #TryResource.
259 ///
260 /// \note This method is defined only after inclusion of header-file
261 /// \implude{Camp}.
262 /// @param name The resource name.
263 /// @return The resource string, respectively a \e nulled string on failure.
264 inline
265 const String& GetResource( const NString& name ) {
266 return resourcePool->Get( ResourceCategory, name ALIB_DBG(, true) );
267 }
268
269 /// Shortcut method that invokes \alib{resources;ResourcePool::Get} on field
270 /// #resourcePool providing field #ResourceCategory as parameter.
271 ///
272 /// \note
273 /// Usually, it is recommended to use #GetResource, which asserts with debug-builds
274 /// if a resource was not found.
275 ///
276 /// \note This method is defined only after inclusion of header-file
277 /// \implude{Camp}.
278 /// @param name The resource name.
279 /// @return The resource string, respectively a \e nulled string on failure.
280 inline
281 const String& TryResource( const NString& name ) {
282 return resourcePool->Get( ResourceCategory, name ALIB_DBG(, false) );
283 }
284
285
286};// class Camp
287}} // namespace [alib::camp]
288
289
290//==================================================================================================
291//=== enumrecords::Bootstrap() functions with Camps
292//==================================================================================================
294
295/// This method can be used if a set of enum records is resourced using an \alib
296/// \alib{camp;Camp}'s resource instance.
297///
298/// Invokes #Bootstrap(ResourcePool&, const NString&, const NString&, character, character)
299/// accepting a \alib{camp;Camp} and using its \alib{resources;ResourcePool} and
300/// field \alib{camp;Camp::ResourceCategory}.
301///
302/// \note
303/// This is the preferred overload taken with \alib to load built-in enum records.
304/// The only exception is the use of overload #Bootstrap(character, character)
305/// for enum record types that require a specialization of
306/// \alib{resources;ResourcedTraits} to perform "recursive" acquisition of other
307/// resources defined by fields of the records.
308///
309/// \par Availability
310/// This namespace function is available only if the module \alib_camp is included in
311/// the \alibbuild.
312///
313/// \see Chapters \ref alib_enums_records_resourced_tresourced and
314/// \ref alib_enums_records_resourced_from_modules for more information.
315///
316/// @tparam TEnum The enumeration type to load resourced records for.
317/// @param camp The module to use the resource pool and category name from.
318/// @param name The resource name of the externalized name. In the case that a
319/// resource with that name does not exist, it is tried to load
320/// a resource with index number \c 0 appended to this name, aiming to
321/// parse a single record. On success, the index is incremented until
322/// no consecutive resource is found.
323/// @param innerDelim The delimiter used for separating the fields of a record.
324/// Defaults to <c>','</c>.
325/// @param outerDelim The character delimiting enum records.
326/// Defaults to <c>','</c>.
327template<typename TEnum>
330 const NString& name,
331 character innerDelim= ',' ,
332 character outerDelim= ',' )
333{ Bootstrap<TEnum>( *camp.GetResourcePool(), camp.ResourceCategory, name, innerDelim, outerDelim ); }
334
335} // namespace [alib::enumrecords::bootstrap]
336
337//==================================================================================================
338//=== Configuration variable construction with Camps
339//==================================================================================================
342/// Creates an undeclared configuration variable attached to an \alibcamp.
343/// \note While all other overloads of this shortcut-function lock the configuration instance of
344/// the given \p{camp}, with this method it this is not needed and thus not done.
345///
346/// @param camp An singleton which supplies the \b Configuration instance.
347/// @return A variable using the \alib{variables;Configuration} of the given \p{camp}.
348inline
350 return variables::Variable(camp.GetConfig()->Root());
351}
352
353/// Constructs and declares a variable, without using or allocating a declaration struct.
354/// \note This shortcut-function locks the configuration instance of the given \p{camp} for
355/// declaring the variable. Thus, it must not be locked before the call.
356/// @param camp An \alibcamp An \alibcamp singleton which supplies the
357/// \alib{variables;Configuration} instance.
358/// @param name The name of the variable.
359/// @param typeName The type of the variable.
360/// @param defaultValue An optional default value. Defaults to \e nulled string.
361/// @return The variable created.
362inline
364 const String& name, const String& typeName,
365 const String& defaultValue= NULL_STRING ) {
366 ALIB_LOCK_WITH(camp.GetConfig())
367 auto var= CampVariable(camp);
368 var.Declare( name, typeName, defaultValue );
369 return var;
370}
371
372/// Constructs and declares a variable.
373/// \note This shortcut-function locks the configuration instance of the given \p{camp} for
374/// declaring the variable. Thus, it must not be locked before the call.
375/// @param camp An \alibcamp singleton which supplies the \alib{variables;Configuration} instance.
376/// @param decl The declaration to use.
377/// @return The variable created.
378inline
380 ALIB_LOCK_WITH(camp.GetConfig())
381 auto var= CampVariable(camp);
382 var.Declare( decl );
383 return var;
384}
385
386/// Constructs and declares a variable.
387/// \note This shortcut-function locks the configuration instance of the given \p{camp} for
388/// declaring the variable. Thus, it must not be locked before the call.
389/// @tparam TEnum The type of parameter \p{Enum}
390/// @param camp An \alibcamp singleton which supplies the \alib{variables;Configuration} instance.
391/// @param Enum Element of an enum type that represents resourced configuration variables.
392/// @return The variable created.
393template<typename TEnum>
395{
396 ALIB_LOCK_WITH(camp.GetConfig())
397 auto var= CampVariable(camp);
398 var.Declare( Declaration::Get( Enum ) );
399 return var;
400}
401
402/// Constructs and declares a variable.
403/// \note This shortcut-function locks the configuration instance of the given \p{camp} for
404/// declaring the variable. Thus, it must not be locked before the call.
405/// \attention This function might allocate a new record in the mono allocator of \p{cfg}.
406/// To avoid memory drain, consult the documentation of method
407/// \alib{variables;Configuration::StoreDeclaration}.,
408/// @tparam TEnum The type of parameter \p{Enum}
409/// @param camp An \alibcamp singleton which supplies the \alib{variables;Configuration}
410/// instance.
411/// @param Enum Element of an enum type that represents resourced configuration variables.
412/// @param replacements Replacement values.
413/// @return The variable created.
414template<typename TEnum>
415requires std::is_enum_v<TEnum>
417{
418 ALIB_LOCK_WITH(camp.GetConfig())
419 auto var= CampVariable(camp);
420 var.Declare( camp.GetConfig()->StoreDeclaration( Declaration::Get( Enum ), replacements ) );
421 return var;
422}
423} // namespace [alib::camp]
424#include "ALib.Lang.CIMethods.H"
425
426
NCString ResourceCategory
Definition camp.inl:113
BootstrapPhases GetBootstrapState()
Definition camp.inl:176
SharedConfiguration config
Definition camp.inl:104
void BootstrapResource(const NString &name, const String &data)
Definition camp.inl:250
void operator=(const Camp &)=delete
Deleted copy assignment.
Camp(const Camp &)=delete
Deleted copy constructor.
void BootstrapSetPhase(BootstrapPhases phase)
Definition camp.inl:180
SharedConfiguration & GetConfig()
Definition camp.inl:215
virtual ~Camp()
Virtual destructor to satisfy C++ abstract type rules.
Definition camp.inl:138
void operator=(Camp &&)=delete
Deleted move assignment.
virtual void Shutdown(ShutdownPhases phase)=0
Camp(Camp &&)=delete
Deleted move constructor.
virtual void Bootstrap()=0
int bootstrapState
Definition camp.inl:91
const String & TryResource(const NString &name)
Definition camp.inl:281
SharedPtr< resources::ResourcePool, MonoAllocator > SPResourcePool
Definition camp.inl:86
void BootstrapSetConfig(const SharedConfiguration &pConfig)
Definition camp.inl:205
void BootstrapSetResourcePool(const SPResourcePool &pResourcePool)
Definition camp.inl:232
bool IsBootstrapped()
Definition camp.inl:186
Camp(const NCString &resourceCategory)
Definition camp.inl:120
SPResourcePool resourcePool
Definition camp.inl:95
SPResourcePool & GetResourcePool()
Definition camp.inl:243
const String & GetResource(const NString &name)
Definition camp.inl:265
static const Declaration * Get(TEnum element)
#define ALIB_ASSERT_WARNING(cond, domain,...)
Definition alib.inl:1050
#define ALIB_EXPORT
Definition alib.inl:488
#define ALIB_DBG(...)
Definition alib.inl:836
#define ALIB_LOCK_WITH(lock)
Definition alib.inl:1322
void Bootstrap(camp::Camp &camp, const NString &name, character innerDelim=',', character outerDelim=',')
Definition camp.inl:329
variables::Variable CampVariable(camp::Camp &camp)
Definition camp.inl:349
constexpr String NULL_STRING
A nulled string of the default character type.
Definition string.inl:2463
BootstrapPhases
Definition camp.inl:15
@ Final
The final initialization phase. Here, camps are initializing their custom setup.
Definition camp.inl:35
ShutdownPhases
Termination levels usable with Bootstrapping ALib Camps.
Definition camp.inl:42
@ Destruct
The main phase of termination that destructs everything.
Definition camp.inl:46
strings::TString< nchar > NString
Type alias in namespace alib.
Definition string.inl:2390
variables::TSharedConfiguration< SharedLock > SharedConfiguration
Type alias in namespace alib.
strings::TCString< nchar > NCString
Type alias in namespace alib.
Definition cstring.inl:512
boxing::Enum Enum
Type alias in namespace alib.
Definition enum.inl:211
boxing::Box Box
Type alias in namespace alib.
Definition box.inl:1216
strings::TString< character > String
Type alias in namespace alib.
Definition string.inl:2381
characters::character character
Type alias in namespace alib.
containers::SharedPtr< T, TAllocator > SharedPtr
Type alias in namespace alib.