ALib C++ Library
Library Version: 2510 R0
Documentation generated by doxygen
Loading...
Searching...
No Matches
localresourcepool.inl
Go to the documentation of this file.
1//==================================================================================================
2/// \file
3/// This header-file is part of module \alib_resources of the \aliblong.
4///
5/// \emoji :copyright: 2013-2025 A-Worx GmbH, Germany.
6/// Published under \ref mainpage_license "Boost Software License".
7//==================================================================================================
9
10//==================================================================================================
11/// This class provides a very simple implementation of abstract interface class
12/// \alib{resources;ResourcePool}, which does \b not externalize resources.
13///
14/// A shared instance of this class is attached to each \alibmod, if the
15/// \ref alib_mod_bs "bootstrapping of ALib" is not customized.
16///
17/// With the use of type \alib{containers;HashTable} for its internal data management, this
18/// class uses \ref alib_mods_contmono "monotonically growing memory" taken from the global
19/// allocator.
20///
21/// Only pointers to the given resources (as well as their associated category and name strings)
22/// are stored, hence all string argument's of this class's methods have to be static data.
23///
24/// For debug or optimization purposes, method #BootstrapGetInternalHashMap is given that allows
25/// fine-tune the performance parameters or to inspect the data. For the latter, in
26/// debug-compilations, consider also methods #DbgGetList and #DbgGetCategories.
27///
28/// \see
29/// Please consult the \ref alib_mod_resources "Programmer's Manual" of module \alib_resources_nl for
30/// details on the concept of resources.
31/// Some details on this specific type are given in chapter
32/// \ref alib_resources_interface_default.
33///
34//==================================================================================================
36{
37 protected:
38 /// A hash map used to store static resources.
40
41 #if ALIB_DEBUG_RESOURCES
42 /// If set before bootstrapping (e.g., to <c>&std::cout</c>), then each found resource string
43 /// is written here. This is very useful to find errors in bulk resource strings, for example
44 /// a simple missing comma.
45 ///
46 /// \par Availability
47 /// Available only if the compiler-symbol \ref ALIB_DEBUG_RESOURCES is set.
48 ///
49 /// \see Manual section \ref alib_resources_details_debug.
50 public: static std::ostream* DbgResourceLoadObserver;
51 #endif
52
53 // #############################################################################################
54 // Constructor/Destructor
55 // #############################################################################################
56 public:
57 /// Constructor.
59 : data( monomem::GLOBAL_ALLOCATOR )
60 {}
61
62 /// Destructor.
64 virtual
66 {}
67
68 /// Returns the internal table that maps a pair of category and name strings to the resource
69 /// string.
70 ///
71 /// Access to this map may be useful for two purposes:
72 /// 1. Debug inspection.
73 /// 2. Modification of the parameters of the hash table. (For example, the use of methods
74 /// \alib{containers::HashTable;Reserve},
75 /// \alib{containers::HashTable;BaseLoadFactor} or
76 /// \alib{containers::HashTable;MaxLoadFactor}).
77 ///
78 /// Modifications on the returned object are allowed only while no threads have been started
79 /// by the software process (respectively no threads that use \alib ), which usually is true
80 /// during bootstrapping a process. Therefore , the prefix in this method's name.
81 ///
82 /// @return The internal hash map.
87
88
89 // #############################################################################################
90 // ResourcePool Interface
91 // #############################################################################################
92
93 //==============================================================================================
94 /// Implements abstract method \alib{resources;ResourcePool::BootstrapAddOrReplace}.
95 /// \note
96 /// If the compiler-symbol \ref ALIB_DEBUG_RESOURCES is set on compilation and static field
97 /// \alib{resources;LocalResourcePool::DbgResourceLoadObserver} is set before bootstrapping,
98 /// this method will write information about whether the given data is added or replaced
99 /// to the debug output stream.
100 ///
101 /// @param category Category string of the resource to add.
102 /// @param name Name string of the resource.
103 /// @param data The resource data.
104 /// @return \c true if the resource did exist and was replaced, \c false if it was an insertion.
105 //==============================================================================================
107 virtual
108 bool BootstrapAddOrReplace( const NString& category,
109 const NString& name,
110 const String& data ) override;
111
112 //==============================================================================================
113 /// Implements abstract method \alib{resources;ResourcePool::BootstrapBulk}.
114 ///
115 /// @param category The category of the resources given.
116 /// @param ... A list of pairs of <b>const nchar*</b> and <b>const character*</b>
117 /// keys and data, including a terminating \c nullptr value.
118 //==============================================================================================
120 virtual
121 void BootstrapBulk( const nchar* category, ... ) override;
122
123
124#if DOXYGEN
125 //==============================================================================================
126 /// Implements abstract method \alib{resources;ResourcePool::Get}.
127 ///
128 /// @param category Category string of the resource.
129 /// @param name Name string of the resource
130 /// @param dbgAssert This parameter is available (and to be passed) only in debug mode.
131 /// If \c true, an \ref alib_mod_assert "error is raised" if the resource
132 /// was not found.
133 /// @return The resource string, respectively a \e nulled string on failure.
134 //==============================================================================================
136 virtual
137 const String& Get( const NString& category, const NString& name, bool dbgAssert ) override;
138#else
140 virtual
141 const String& Get( const NString& category, const NString& name
142 ALIB_DBG(, bool dbgAssert) ) override;
143#endif
144
145 #if ALIB_DEBUG_RESOURCES
146 //==========================================================================================
147 /// Returns a vector of tuples for each resourced element. Each tuple contains:
148 /// 0. The category name
149 /// 1. The resource name
150 /// 2. The resource value
151 /// 3. The number of requests for the resource performed by using software.
152 ///
153 /// While being useful to generally inspect the resources, a high number of requests
154 /// might indicate a performance penalty. Mitigation can usually be performed in a very
155 /// simple fashion by "caching" a resource string in a local or global/static string
156 /// variable.
157 ///
158 /// \par Availability
159 /// Available only if the compiler-symbol \ref ALIB_DEBUG_RESOURCES is set.
160 ///
161 /// \attention
162 /// This function is implemented only with the default pool instance of type
163 /// \alib{resources;LocalResourcePool} is used.
164 /// Otherwise, an \alib warning is raised and an empty vector is returned.
165 ///
166 /// \see
167 /// Methods #DbgGetCategories and #DbgDump.
168 ///
169 /// @return The externalized resource string.
170 //==========================================================================================
172 virtual
173 std::vector<std::tuple<NString, NString, String, integer>>
174 DbgGetList() override;
175
176
177 //==========================================================================================
178 /// Implements abstract method \alib{resources;ResourcePool::DbgGetCategories}.
179 ///
180 /// \par Availability
181 /// Available only if the compiler-symbol \ref ALIB_DEBUG_RESOURCES is set.
182 ///
183 /// @return The externalized resource string.
184 //==========================================================================================
186 virtual
187 std::vector<std::pair<NString, integer>>
188 DbgGetCategories() override;
189 #endif
190}; // class LocalResourcePool
191
192} // namespace [alib::resources]
virtual ALIB_DLL const String & Get(const NString &category, const NString &name, bool dbgAssert) override
virtual ALIB_DLL std::vector< std::tuple< NString, NString, String, integer > > DbgGetList() override
virtual ALIB_DLL void BootstrapBulk(const nchar *category,...) override
detail::StaticResourceMap & BootstrapGetInternalHashMap()
detail::StaticResourceMap data
A hash map used to store static resources.
virtual ALIB_DLL bool BootstrapAddOrReplace(const NString &category, const NString &name, const String &data) override
virtual ALIB_DLL ~LocalResourcePool() override
Destructor.
static std::ostream * DbgResourceLoadObserver
virtual ALIB_DLL std::vector< std::pair< NString, integer > > DbgGetCategories() override
#define ALIB_DLL
Definition alib.inl:496
#define ALIB_EXPORT
Definition alib.inl:488
#define ALIB_DBG(...)
Definition alib.inl:836
HashMap< MonoAllocator, Key, std::pair< String, integer >, Key::Hash, Key::EqualTo, lang::Caching::Enabled, Recycling::None > StaticResourceMap
strings::TString< nchar > NString
Type alias in namespace alib.
Definition string.inl:2390
characters::nchar nchar
Type alias in namespace alib.
strings::TString< character > String
Type alias in namespace alib.
Definition string.inl:2381