GCC Code Coverage Report

Directory: ./
File: src/iguana/algorithms/Algorithm.h
Date: 2025-03-24 18:50:00
Exec Total Coverage
Lines: 13 14 92.9%
Functions: 7 8 87.5%
Branches: 6 12 50.0%
Line Branch Exec Source
1 #pragma once
2
3 #include <mutex>
4 #include <optional>
5 #include <set>
6
7 #include <hipo4/bank.h>
8
9 #include "AlgorithmBoilerplate.h"
10 #include "iguana/bankdefs/BankDefs.h"
11 #include "iguana/services/YAMLReader.h"
12 #include <iguana/services/GlobalParam.h>
13
14 namespace iguana {
15
16 /// Option value variant type
17 /* NOTE: if you modify this, you also must modify:
18 * - [ ] `PrintOptionValue`
19 * - [ ] Template specializations in this class
20 * - [ ] Template specializations in `YAMLReader` or `ConfigFileReader`, and `ConcurrentParam`
21 * - [ ] Add new tests, if you added new types
22 */
23 using option_t = std::variant<
24 int,
25 double,
26 std::string,
27 std::vector<int>,
28 std::vector<double>,
29 std::vector<std::string>>;
30
31 /// @brief Base class for all algorithms to inherit from
32 ///
33 /// This is the base class for all algorithms. It provides common members, such as
34 /// a logger instance and options data structure. Algorithm implementations must:
35 /// - inherit from this base class
36 /// - override the methods `Algorithm::Start`, `Algorithm::Run` and `Algorithm::Stop`
37 ///
38 /// See existing algorithms for examples.
39 class Algorithm : public Object
40 {
41
42 public:
43
44 /// @param name the unique name for a derived class instance
45 79 Algorithm(std::string_view name)
46 79 : Object(name)
47 79 , m_rows_only(false)
48
1/2
✓ Branch 0 (3→4) taken 79 times.
✗ Branch 1 (3→11) not taken.
 79 , m_default_config_file("")
49
1/2
✓ Branch 0 (4→5) taken 79 times.
✗ Branch 1 (4→9) not taken.
 79 , o_user_config_file("")
50
2/4
✓ Branch 0 (3→4) taken 79 times.
✗ Branch 1 (3→11) not taken.
✓ Branch 2 (5→6) taken 79 times.
✗ Branch 3 (5→7) not taken.
 158 , o_user_config_dir("")
51 79 {}
52 158 virtual ~Algorithm() {}
53
54 /// @brief Initialize this algorithm before any events are processed, with the intent to process _banks_
55 ///
56 /// use this method if you intend to use `Algorithm::Run`.
57 /// @param banks the list of banks this algorithm will use, so that `Algorithm::Run` can cache the indices
58 /// of the banks that it needs
59 virtual void Start(hipo::banklist& banks) = 0;
60
61 /// @brief Initialize this algorithm before any events are processed, with the intent to process _bank rows_ rather than full banks;
62 ///
63 /// use this method if you intend to use "action functions" instead of `Algorithm::Run`.
64 void Start();
65
66 /// @brief Run this algorithm for an event.
67 /// @param banks the list of banks to process
68 virtual void Run(hipo::banklist& banks) const = 0;
69
70 /// @brief Finalize this algorithm after all events are processed.
71 virtual void Stop() = 0;
72
73 /// Set an option specified by the user. If the option name is `"log"`, the log level of the `Logger`
74 /// owned by this algorithm will be changed to the specified value.
75 /// @param key the name of the option
76 /// @param val the value to set
77 /// @returns the value that has been set (if needed, _e.g._, when `val` is an rvalue)
78 template <typename OPTION_TYPE>
79 58 OPTION_TYPE SetOption(std::string const& key, const OPTION_TYPE val)
80 {
81 // FIXME: this template is not specialized, to be friendlier to python `cppyy` bindings
82
2/2
✓ Branch 0 (2→3) taken 32 times.
✓ Branch 1 (2→7) taken 26 times.
 58 if(key == "log") {
83 if constexpr(std::disjunction<
84 std::is_same<OPTION_TYPE, std::string>,
85 std::is_same<OPTION_TYPE, char const*>,
86 std::is_same<OPTION_TYPE, Logger::Level>>::value)
87 32 m_log->SetLevel(val);
88 else
89 ✗ m_log->Error("Option '{}' must be a string or a Logger::Level", key);
90 }
91 54 m_option_cache[key] = val;
92 58 return val;
93 }
94
95 /// Get the value of a scalar option
96 /// @param key the unique key name of this option, for caching; if empty, the option will not be cached
97 /// @param node_path the `YAML::Node` identifier path to search for this option in the config files; if empty, it will just use `key`
98 /// @returns the scalar option
99 template <typename OPTION_TYPE>
100 OPTION_TYPE GetOptionScalar(std::string const& key, YAMLReader::node_path_t node_path = {}) const;
101
102 /// Get the value of a vector option
103 /// @param key the unique key name of this option, for caching; if empty, the option will not be cached
104 /// @param node_path the `YAML::Node` identifier path to search for this option in the config files; if empty, it will just use `key`
105 /// @returns the vector option
106 template <typename OPTION_TYPE>
107 std::vector<OPTION_TYPE> GetOptionVector(std::string const& key, YAMLReader::node_path_t node_path = {}) const;
108
109 /// Get the value of a vector option, and convert it to `std::set`
110 /// @param key the unique key name of this option
111 /// @param node_path the `YAML::Node` identifier path to search for this option in the config files; if empty, it will just use `key`
112 /// @returns the vector option converted to `std::set`
113 template <typename OPTION_TYPE>
114 std::set<OPTION_TYPE> GetOptionSet(std::string const& key, YAMLReader::node_path_t node_path = {}) const;
115
116 /// Set the name of this algorithm
117 /// @param name the new name
118 void SetName(std::string_view name);
119
120 /// Get a reference to this algorithm's configuration (`YAMLReader`)
121 /// @returns the configuration
122 std::unique_ptr<YAMLReader> const& GetConfig() const;
123
124 /// Set a custom `YAMLReader` to use for this algorithm
125 /// @param yaml_config the custom `YAMLReader` instance
126 void SetConfig(std::unique_ptr<YAMLReader>&& yaml_config);
127
128 /// Set a custom configuration file for this algorithm
129 /// @see `Algorithm::SetConfigDirectory`
130 /// @param name the configuration file name
131 void SetConfigFile(std::string const& name);
132
133 /// Set a custom configuration file directory for this algorithm
134 /// @see `Algorithm::SetConfigFile`
135 /// @param name the directory name
136 void SetConfigDirectory(std::string const& name);
137
138 protected: // methods
139
140 /// Parse YAML configuration files. Sets `m_yaml_config`.
141 void ParseYAMLConfig();
142
143 /// Get the reference to a bank from a `hipo::banklist`; optionally checks if the bank name matches the expectation
144 /// @param banks the `hipo::banklist` from which to get the specified bank
145 /// @param idx the index of `banks` of the specified bank
146 /// @param expected_bank_name if specified, checks that the specified bank has this name
147 /// @return a reference to the bank
148 hipo::bank& GetBank(hipo::banklist& banks, hipo::banklist::size_type const idx, std::string const& expected_bank_name = "") const noexcept(false);
149
150 /// Get the index of a bank in a `hipo::banklist`; throws an exception if the bank is not found
151 /// @param banks the list of banks this algorithm will use
152 /// @param bank_name the name of the bank
153 /// returns the `hipo::banklist` index of the bank
154 hipo::banklist::size_type GetBankIndex(hipo::banklist& banks, std::string const& bank_name) const noexcept(false);
155
156 /// Create a new bank and push it to the bank list. The bank must be defined in `src/iguana/bankdefs/iguana.json`.
157 /// @param [out] banks the `hipo::banklist` onto which the new bank will be pushed
158 /// @param [out] bank_idx will be set to the `hipo::banklist` index of the new bank
159 /// @param [in] bank_name the new bank name
160 /// @returns the bank's schema
161 hipo::schema CreateBank(
162 hipo::banklist& banks,
163 hipo::banklist::size_type& bank_idx,
164 std::string const& bank_name) const noexcept(false);
165
166 /// Dump all banks in a `hipo::banklist`
167 /// @param banks the banks to show
168 /// @param message if specified, print a header message
169 /// @param level the log level
170 void ShowBanks(hipo::banklist& banks, std::string_view message = "", Logger::Level const level = Logger::trace) const;
171
172 /// Dump a single bank
173 /// @param bank the bank to show
174 /// @param message if specified, print a header message
175 /// @param level the log level
176 void ShowBank(hipo::bank& bank, std::string_view message = "", Logger::Level const level = Logger::trace) const;
177
178 /// Get an option from the option cache
179 /// @param key the key name associated with this option
180 /// @returns the option value, if found (using `std::optional`)
181 template <typename OPTION_TYPE>
182 std::optional<OPTION_TYPE> GetCachedOption(std::string const& key) const;
183
184 private: // methods
185
186 /// Prepend `node_path` with the full algorithm name. If `node_path` is empty, set it to `{key}`.
187 /// @param key the key name for this option
188 /// @param node_path the `YAMLReader::node_path_t` to prepend
189 void CompleteOptionNodePath(std::string const& key, YAMLReader::node_path_t& node_path) const;
190
191 // PrintOptionValue: overloaded for different value types
192 void PrintOptionValue(std::string const& key, int const& val, Logger::Level const level = Logger::debug, std::string_view prefix = "OPTION") const;
193 void PrintOptionValue(std::string const& key, double const& val, Logger::Level const level = Logger::debug, std::string_view prefix = "OPTION") const;
194 void PrintOptionValue(std::string const& key, std::string const& val, Logger::Level const level = Logger::debug, std::string_view prefix = "OPTION") const;
195 void PrintOptionValue(std::string const& key, std::vector<int> const& val, Logger::Level const level = Logger::debug, std::string_view prefix = "OPTION") const;
196 void PrintOptionValue(std::string const& key, std::vector<double> const& val, Logger::Level const level = Logger::debug, std::string_view prefix = "OPTION") const;
197 void PrintOptionValue(std::string const& key, std::vector<std::string> const& val, Logger::Level const level = Logger::debug, std::string_view prefix = "OPTION") const;
198
199 protected: // members
200
201 /// Class name of this algorithm
202 std::string m_class_name;
203
204 /// If true, algorithm can only operate on bank _rows_; `Algorithm::GetBank`, and therefore `Algorithm::Run`, cannot be called
205 bool m_rows_only;
206
207 /// Default configuration file name
208 std::string m_default_config_file;
209
210 /// User's configuration file name, which may override the default configuration file, `m_default_config_file`.
211 /// Set it with `Algorithm::SetConfigFile`
212 std::string o_user_config_file;
213
214 /// User's configuration file directory.
215 /// Set it with `Algorithm::SetConfigDirectory`
216 std::string o_user_config_dir;
217
218 /// A mutex for this algorithm
219 mutable std::mutex m_mutex;
220
221 private: // members
222
223 /// YAML reader
224 std::unique_ptr<YAMLReader> m_yaml_config;
225
226 /// Data structure to hold configuration options set by `Algorithm::SetOption`
227 std::unordered_map<std::string, option_t> m_option_cache;
228
229 };
230
231 //////////////////////////////////////////////////////////////////////////////
232
233 /// Algorithm pointer type
234 using algo_t = std::unique_ptr<Algorithm>;
235
236 /// @brief Factory to create an algorithm.
237 class AlgorithmFactory
238 {
239
240 public:
241
242 /// Algorithm creator function type
243 using algo_creator_t = std::function<algo_t()>;
244
245 AlgorithmFactory() = delete;
246
247 /// Register an algorithm with a unique name. Algorithms register themselves by calling this function.
248 /// @param name the name of the algorithm (not equivalent to `Object::m_name`)
249 /// @param creator the creator function
250 /// @param new_banks if this algorithm creates *new* banks, list them here
251 /// @returns true if the algorithm has not yet been registered
252 static bool Register(std::string const& name, algo_creator_t creator, std::vector<std::string> const new_banks = {}) noexcept;
253
254 /// Create an algorithm. Throws an exception if the algorithm cannot be created
255 /// @param name the name of the algorithm, which was used as an argument in the `AlgorithmFactory::Register` call
256 /// @returns the algorithm instance
257 static algo_t Create(std::string const& name) noexcept(false);
258
259 /// Check if a bank is created by an algorithm
260 /// @param bank_name the name of the bank
261 /// @returns the list of algorithms which create it, if any
262 static std::optional<std::vector<std::string>> QueryNewBank(std::string const& bank_name) noexcept;
263
264 private:
265
266 /// Association between the algorithm names and their creators
267 static std::unordered_map<std::string, algo_creator_t> s_creators;
268
269 /// Association between a created bank and its creator algorithms
270 static std::unordered_map<std::string, std::vector<std::string>> s_created_banks;
271 };
272 }
273