src/iguana/services/ConcurrentParam.h - GCC Code Coverage Report

Directory:	./
File:	src/iguana/services/ConcurrentParam.h
Date:	2025-11-25 17:57:04

	Coverage	Exec	Total
Lines:	35.2%	19	54
Functions:	23.1%	6	26
Branches:	37.5%	21	56

  
      Line
      Branch
      Exec
      Source
    
      #pragma once
    
      #include "GlobalParam.h"
    
      namespace iguana {
    
        /// concurrent hash key type
    
        using concurrent_key_t = std::size_t;
    
        // ==================================================================================
    
        // ConcurrentParam
    
        // ==================================================================================
    
        /// @brief abstract base class for concurrently mutable configuration parameters
    
        /// @see `iguana::ConcurrentParamFactory` for instantiation
    
        template <typename T>
    
        class ConcurrentParam
    
        {
    
          public:
    
            /// @param model the concurrency model this instance must be
    
            /// @see `ConcurrentParamFactory`, the preferred instantiation method
    
            ConcurrentParam(std::string const& model);
    
            virtual ~ConcurrentParam() = default;
    
            /// @brief access a stored value
    
            /// @param key the access key
    
            /// @returns the stored value
    
            virtual T const Load(concurrent_key_t const key) const = 0;
    
            /// @brief modify a value
    
            /// @param value the value
    
            /// @param key the access key
    
            virtual void Save(T const& value, concurrent_key_t const key) = 0;
    
            /// @param key the key
    
            /// @returns `true` if key `key` is used
    
            virtual bool HasKey(concurrent_key_t const key) const = 0;
    
            /// @brief whether or not hashing is needed to use this parameter
    
            /// @returns `true` if hashing is needed
    
        2/2✓ Branch 3 → 4 taken 5005 times.
✓ Branch 3 → 8 taken 5000 times.

      10005
            bool NeedsHashing() const { return m_needs_hashing; }
    
            /// @returns the size of the internal data storage container
    
            virtual std::size_t GetSize() const = 0;
    
            /// @returns `true` if no value has been saved
    
        2/2✓ Branch 8 → 9 taken 4995 times.
✓ Branch 8 → 11 taken 5 times.

      5000
            bool IsEmpty() const { return m_empty; }
    
          protected:
    
            /// whether this `ConcurrentParam` needs hashing for calling `::Load` or `::Save`
    
            bool m_needs_hashing;
    
            /// mutex for this `ConcurrentParam`
    
            std::mutex m_mutex;
    
            /// whether this `ConcurrentParam` has something saved
    
            bool m_empty{true};
    
        };
    
        // ==================================================================================
    
        // SingleThreadParam
    
        // ==================================================================================
    
        /// @brief a parameter that is _not_ thread safe;
    
        /// used when `iguana::GlobalConcurrencyModel` is "single"
    
        template <typename T>
    
        class SingleThreadParam : public ConcurrentParam<T>
    
        {
    
          public:
    
            SingleThreadParam();
    
        1/12iguana::SingleThreadParam<std::__cxx11::basic_string<char, std::char_traits<char>, std::allocator<char> > >::~SingleThreadParam():
✗ Branch 2 → 3 not taken.
✗ Branch 2 → 5 not taken.
iguana::SingleThreadParam<std::__cxx11::basic_string<char, std::char_traits<char>, std::allocator<char> > >::~SingleThreadParam():
✗ Branch 2 → 3 not taken.
✗ Branch 2 → 5 not taken.
iguana::SingleThreadParam<std::vector<int, std::allocator<int> > >::~SingleThreadParam():
✗ Branch 2 → 3 not taken.
✗ Branch 2 → 5 not taken.
iguana::SingleThreadParam<std::vector<int, std::allocator<int> > >::~SingleThreadParam():
✗ Branch 2 → 3 not taken.
✗ Branch 2 → 5 not taken.
iguana::SingleThreadParam<std::vector<double, std::allocator<double> > >::~SingleThreadParam():
✓ Branch 2 → 3 taken 9 times.
✗ Branch 2 → 5 not taken.
iguana::SingleThreadParam<std::vector<double, std::allocator<double> > >::~SingleThreadParam():
✗ Branch 2 → 3 not taken.
✗ Branch 2 → 5 not taken.

      23
            ~SingleThreadParam() override = default;
    
            T const Load(concurrent_key_t const key) const override;
    
            void Save(T const& value, concurrent_key_t const key) override;
    
            bool HasKey(concurrent_key_t const key) const override;
    
            std::size_t GetSize() const override;
    
          private:
    
            /// the stored value; it is not `std::atomic` since `std::string` is one of
    
            /// the specializations (for `T`), which is not trivially copyable
    
            T m_value;
    
        };
    
        // ==================================================================================
    
        // MemoizedParam
    
        // ==================================================================================
    
        /// @brief an `iguana::ConcurrentParam` that uses memoization for thread safety;
    
        /// used when `iguana::GlobalConcurrencyModel` is "memoize"
    
        template <typename T>
    
        class MemoizedParam : public ConcurrentParam<T>
    
        {
    
            /// hash table container for memoization
    
            using container_t = std::unordered_map<concurrent_key_t, T>;
    
          public:
    
            MemoizedParam();
    
      26
            ~MemoizedParam() override = default;
    
            T const Load(concurrent_key_t const key) const override;
    
            void Save(T const& value, concurrent_key_t const key) override;
    
            bool HasKey(concurrent_key_t const key) const override;
    
            std::size_t GetSize() const override;
    
          private:
    
            /// the hash table for stored (memoized) values
    
            container_t m_container;
    
        };
    
        // ==================================================================================
    
        // ConcurrentParamFactory
    
        // ==================================================================================
    
        /// @brief factory to create the appropriate `ConcurrentParam`-derived class instance for the current `GlobalConcurrencyModel`
    
        class ConcurrentParamFactory
    
        {
    
          public:
    
            ConcurrentParamFactory() = delete;
    
            /// @brief create a new `ConcurrentParam`-derived class instance
    
            /// @warning if `GlobalConcurrencyModel` is not set, the model `"memoize"` will be chosen,
    
            /// since it is thread safe and does not assume anything about the user's implementation
    
            /// @returns a pointer to the new instance
    
            template <typename T>
    
      40
            static std::unique_ptr<ConcurrentParam<T>> Create()
    
            {
    
        5/8std::unique_ptr<iguana::ConcurrentParam<std::vector<double, std::allocator<double> > >, std::default_delete<iguana::ConcurrentParam<std::vector<double, std::allocator<double> > > > > iguana::ConcurrentParamFactory::Create<std::vector<double, std::allocator<double> > >():
✓ Branch 3 → 4 taken 24 times.
✗ Branch 3 → 6 not taken.
✗ Branch 8 → 9 not taken.
✓ Branch 8 → 17 taken 24 times.
std::unique_ptr<iguana::ConcurrentParam<int>, std::default_delete<iguana::ConcurrentParam<int> > > iguana::ConcurrentParamFactory::Create<int>():
✓ Branch 3 → 4 taken 16 times.
✗ Branch 3 → 6 not taken.
✓ Branch 8 → 9 taken 6 times.
✓ Branch 8 → 17 taken 10 times.

      80
              if(GlobalConcurrencyModel() == "none")
    
        1/4std::unique_ptr<iguana::ConcurrentParam<std::vector<double, std::allocator<double> > >, std::default_delete<iguana::ConcurrentParam<std::vector<double, std::allocator<double> > > > > iguana::ConcurrentParamFactory::Create<std::vector<double, std::allocator<double> > >():
✗ Branch 10 → 11 not taken.
✗ Branch 10 → 58 not taken.
std::unique_ptr<iguana::ConcurrentParam<int>, std::default_delete<iguana::ConcurrentParam<int> > > iguana::ConcurrentParamFactory::Create<int>():
✓ Branch 10 → 11 taken 6 times.
✗ Branch 10 → 58 not taken.

      12
                GlobalConcurrencyModel = "memoize"; // the safest default, but not the fastest for single-threaded users
    
        6/8std::unique_ptr<iguana::ConcurrentParam<std::vector<double, std::allocator<double> > >, std::default_delete<iguana::ConcurrentParam<std::vector<double, std::allocator<double> > > > > iguana::ConcurrentParamFactory::Create<std::vector<double, std::allocator<double> > >():
✓ Branch 18 → 19 taken 24 times.
✗ Branch 18 → 21 not taken.
✓ Branch 23 → 24 taken 9 times.
✓ Branch 23 → 26 taken 15 times.
std::unique_ptr<iguana::ConcurrentParam<int>, std::default_delete<iguana::ConcurrentParam<int> > > iguana::ConcurrentParamFactory::Create<int>():
✓ Branch 18 → 19 taken 16 times.
✗ Branch 18 → 21 not taken.
✓ Branch 23 → 24 taken 5 times.
✓ Branch 23 → 26 taken 11 times.

      80
              if(GlobalConcurrencyModel() == "single")
    
      14
                return std::make_unique<SingleThreadParam<T>>();
    
        4/8std::unique_ptr<iguana::ConcurrentParam<std::vector<double, std::allocator<double> > >, std::default_delete<iguana::ConcurrentParam<std::vector<double, std::allocator<double> > > > > iguana::ConcurrentParamFactory::Create<std::vector<double, std::allocator<double> > >():
✓ Branch 27 → 28 taken 15 times.
✗ Branch 27 → 30 not taken.
✓ Branch 32 → 33 taken 15 times.
✗ Branch 32 → 35 not taken.
std::unique_ptr<iguana::ConcurrentParam<int>, std::default_delete<iguana::ConcurrentParam<int> > > iguana::ConcurrentParamFactory::Create<int>():
✓ Branch 27 → 28 taken 11 times.
✗ Branch 27 → 30 not taken.
✓ Branch 32 → 33 taken 11 times.
✗ Branch 32 → 35 not taken.

      52
              else if(GlobalConcurrencyModel() == "memoize")
    
      26
                return std::make_unique<MemoizedParam<T>>();
    
      ✗
              throw std::runtime_error("unknown GlobalConcurrencyModel '" + GlobalConcurrencyModel() + "'; valid options are 'single' or 'memoize'");
    
            }
    
        };
    
      }

Line	Branch	Exec	Source
1			#pragma once
2
3			#include "GlobalParam.h"
4
5			namespace iguana {
6
7			/// concurrent hash key type
8			using concurrent_key_t = std::size_t;
9
10			// ==================================================================================
11			// ConcurrentParam
12			// ==================================================================================
13
14			/// @brief abstract base class for concurrently mutable configuration parameters
15			/// @see `iguana::ConcurrentParamFactory` for instantiation
16			template <typename T>
17			class ConcurrentParam
18			{
19
20			public:
21
22			/// @param model the concurrency model this instance must be
23			/// @see `ConcurrentParamFactory`, the preferred instantiation method
24			ConcurrentParam(std::string const& model);
25			virtual ~ConcurrentParam() = default;
26
27			/// @brief access a stored value
28			/// @param key the access key
29			/// @returns the stored value
30			virtual T const Load(concurrent_key_t const key) const = 0;
31
32			/// @brief modify a value
33			/// @param value the value
34			/// @param key the access key
35			virtual void Save(T const& value, concurrent_key_t const key) = 0;
36
37			/// @param key the key
38			/// @returns `true` if key `key` is used
39			virtual bool HasKey(concurrent_key_t const key) const = 0;
40
41			/// @brief whether or not hashing is needed to use this parameter
42			/// @returns `true` if hashing is needed
43	2/2 ✓ Branch 3 → 4 taken 5005 times. ✓ Branch 3 → 8 taken 5000 times.	10005	bool NeedsHashing() const { return m_needs_hashing; }
44
45			/// @returns the size of the internal data storage container
46			virtual std::size_t GetSize() const = 0;
47
48			/// @returns `true` if no value has been saved
49	2/2 ✓ Branch 8 → 9 taken 4995 times. ✓ Branch 8 → 11 taken 5 times.	5000	bool IsEmpty() const { return m_empty; }
50
51			protected:
52
53			/// whether this `ConcurrentParam` needs hashing for calling `::Load` or `::Save`
54			bool m_needs_hashing;
55
56			/// mutex for this `ConcurrentParam`
57			std::mutex m_mutex;
58
59			/// whether this `ConcurrentParam` has something saved
60			bool m_empty{true};
61			};
62
63			// ==================================================================================
64			// SingleThreadParam
65			// ==================================================================================
66
67			/// @brief a parameter that is _not_ thread safe;
68			/// used when `iguana::GlobalConcurrencyModel` is "single"
69			template <typename T>
70			class SingleThreadParam : public ConcurrentParam<T>
71			{
72
73			public:
74			SingleThreadParam();
75	1/12 iguana::SingleThreadParam<std::__cxx11::basic_string<char, std::char_traits<char>, std::allocator<char> > >::~SingleThreadParam(): ✗ Branch 2 → 3 not taken. ✗ Branch 2 → 5 not taken. iguana::SingleThreadParam<std::__cxx11::basic_string<char, std::char_traits<char>, std::allocator<char> > >::~SingleThreadParam(): ✗ Branch 2 → 3 not taken. ✗ Branch 2 → 5 not taken. iguana::SingleThreadParam<std::vector<int, std::allocator<int> > >::~SingleThreadParam(): ✗ Branch 2 → 3 not taken. ✗ Branch 2 → 5 not taken. iguana::SingleThreadParam<std::vector<int, std::allocator<int> > >::~SingleThreadParam(): ✗ Branch 2 → 3 not taken. ✗ Branch 2 → 5 not taken. iguana::SingleThreadParam<std::vector<double, std::allocator<double> > >::~SingleThreadParam(): ✓ Branch 2 → 3 taken 9 times. ✗ Branch 2 → 5 not taken. iguana::SingleThreadParam<std::vector<double, std::allocator<double> > >::~SingleThreadParam(): ✗ Branch 2 → 3 not taken. ✗ Branch 2 → 5 not taken.	23	~SingleThreadParam() override = default;
76			T const Load(concurrent_key_t const key) const override;
77			void Save(T const& value, concurrent_key_t const key) override;
78			bool HasKey(concurrent_key_t const key) const override;
79			std::size_t GetSize() const override;
80
81			private:
82
83			/// the stored value; it is not `std::atomic` since `std::string` is one of
84			/// the specializations (for `T`), which is not trivially copyable
85			T m_value;
86			};
87
88			// ==================================================================================
89			// MemoizedParam
90			// ==================================================================================
91
92			/// @brief an `iguana::ConcurrentParam` that uses memoization for thread safety;
93			/// used when `iguana::GlobalConcurrencyModel` is "memoize"
94			template <typename T>
95			class MemoizedParam : public ConcurrentParam<T>
96			{
97
98			/// hash table container for memoization
99			using container_t = std::unordered_map<concurrent_key_t, T>;
100
101			public:
102			MemoizedParam();
103		26	~MemoizedParam() override = default;
104			T const Load(concurrent_key_t const key) const override;
105			void Save(T const& value, concurrent_key_t const key) override;
106			bool HasKey(concurrent_key_t const key) const override;
107			std::size_t GetSize() const override;
108
109			private:
110
111			/// the hash table for stored (memoized) values
112			container_t m_container;
113			};
114
115			// ==================================================================================
116			// ConcurrentParamFactory
117			// ==================================================================================
118
119			/// @brief factory to create the appropriate `ConcurrentParam`-derived class instance for the current `GlobalConcurrencyModel`
120			class ConcurrentParamFactory
121			{
122
123			public:
124			ConcurrentParamFactory() = delete;
125
126			/// @brief create a new `ConcurrentParam`-derived class instance
127			/// @warning if `GlobalConcurrencyModel` is not set, the model `"memoize"` will be chosen,
128			/// since it is thread safe and does not assume anything about the user's implementation
129			/// @returns a pointer to the new instance
130			template <typename T>
131		40	static std::unique_ptr<ConcurrentParam<T>> Create()
132			{
133
134	5/8 std::unique_ptr<iguana::ConcurrentParam<std::vector<double, std::allocator<double> > >, std::default_delete<iguana::ConcurrentParam<std::vector<double, std::allocator<double> > > > > iguana::ConcurrentParamFactory::Create<std::vector<double, std::allocator<double> > >(): ✓ Branch 3 → 4 taken 24 times. ✗ Branch 3 → 6 not taken. ✗ Branch 8 → 9 not taken. ✓ Branch 8 → 17 taken 24 times. std::unique_ptr<iguana::ConcurrentParam<int>, std::default_delete<iguana::ConcurrentParam<int> > > iguana::ConcurrentParamFactory::Create<int>(): ✓ Branch 3 → 4 taken 16 times. ✗ Branch 3 → 6 not taken. ✓ Branch 8 → 9 taken 6 times. ✓ Branch 8 → 17 taken 10 times.	80	if(GlobalConcurrencyModel() == "none")
135	1/4 std::unique_ptr<iguana::ConcurrentParam<std::vector<double, std::allocator<double> > >, std::default_delete<iguana::ConcurrentParam<std::vector<double, std::allocator<double> > > > > iguana::ConcurrentParamFactory::Create<std::vector<double, std::allocator<double> > >(): ✗ Branch 10 → 11 not taken. ✗ Branch 10 → 58 not taken. std::unique_ptr<iguana::ConcurrentParam<int>, std::default_delete<iguana::ConcurrentParam<int> > > iguana::ConcurrentParamFactory::Create<int>(): ✓ Branch 10 → 11 taken 6 times. ✗ Branch 10 → 58 not taken.	12	GlobalConcurrencyModel = "memoize"; // the safest default, but not the fastest for single-threaded users
136
137	6/8 std::unique_ptr<iguana::ConcurrentParam<std::vector<double, std::allocator<double> > >, std::default_delete<iguana::ConcurrentParam<std::vector<double, std::allocator<double> > > > > iguana::ConcurrentParamFactory::Create<std::vector<double, std::allocator<double> > >(): ✓ Branch 18 → 19 taken 24 times. ✗ Branch 18 → 21 not taken. ✓ Branch 23 → 24 taken 9 times. ✓ Branch 23 → 26 taken 15 times. std::unique_ptr<iguana::ConcurrentParam<int>, std::default_delete<iguana::ConcurrentParam<int> > > iguana::ConcurrentParamFactory::Create<int>(): ✓ Branch 18 → 19 taken 16 times. ✗ Branch 18 → 21 not taken. ✓ Branch 23 → 24 taken 5 times. ✓ Branch 23 → 26 taken 11 times.	80	if(GlobalConcurrencyModel() == "single")
138		14	return std::make_unique<SingleThreadParam<T>>();
139	4/8 std::unique_ptr<iguana::ConcurrentParam<std::vector<double, std::allocator<double> > >, std::default_delete<iguana::ConcurrentParam<std::vector<double, std::allocator<double> > > > > iguana::ConcurrentParamFactory::Create<std::vector<double, std::allocator<double> > >(): ✓ Branch 27 → 28 taken 15 times. ✗ Branch 27 → 30 not taken. ✓ Branch 32 → 33 taken 15 times. ✗ Branch 32 → 35 not taken. std::unique_ptr<iguana::ConcurrentParam<int>, std::default_delete<iguana::ConcurrentParam<int> > > iguana::ConcurrentParamFactory::Create<int>(): ✓ Branch 27 → 28 taken 11 times. ✗ Branch 27 → 30 not taken. ✓ Branch 32 → 33 taken 11 times. ✗ Branch 32 → 35 not taken.	52	else if(GlobalConcurrencyModel() == "memoize")
140		26	return std::make_unique<MemoizedParam<T>>();
141
142		✗	throw std::runtime_error("unknown GlobalConcurrencyModel '" + GlobalConcurrencyModel() + "'; valid options are 'single' or 'memoize'");
143			}
144			};
145
146			}
147