Class thl::State#

class State : public thl::StateGroup #

Inheritance diagram for thl::State:

Collaboration diagram for thl::State:

Root state container providing hierarchical parameter management with real-time safe access.

State extends StateGroup to provide the root-level parameter storage using RCU (Read-Copy-Update) for lock-free reads. Parameters are stored in a flat map with dot-separated path keys for efficient lookup while maintaining a hierarchical group structure.

Parameters must be explicitly created via create_in_root() before they can be updated with set_in_root(). Each ParameterRecord embeds a const ParameterDefinition that is immutable after creation.

Functions marked with TANH_NONBLOCKING_FUNCTION are designed to be real-time safe when:

The thread has been registered via ensure_thread_registered()
For numeric types (double, float, int, bool): fully real-time safe
For string types: may allocate if string exceeds SSO buffer size

Real-Time Safety

See also

RCU for the underlying lock-free read mechanism

Public Functions

State(size_t max_string_size = 512, size_t max_levels = 10)#

Constructs a new State object.

Initializes RCU for the current thread and pre-allocates string buffers for real-time safe path operations.

Warning

NOT real-time safe - allocates memory

Parameters:

max_string_size – Maximum size for pre-allocated string buffers (default: 512)
max_levels – Maximum depth levels for path resolution (default: 10)

virtual void ensure_thread_registered() override#

void create_in_root(std::string_view key, ParameterDefinition def)#

Creates a parameter with a ParameterDefinition.

The definition is moved into the ParameterRecord and becomes immutable. The initial value is set from m_def.m_default_value. If no ID is set on the definition, one is auto-assigned.

Warning

NOT real-time safe - allocates memory

Parameters:

key – The parameter key
def – The parameter definition (moved into the record)

Throws:

ParameterAlreadyExistsException – if the key already exists
DuplicateParameterIdException – if an explicit ID collides

template<typename T> void create_in_root(std::string_view key, const T &initial_value)#

Creates a parameter with an initial value and default definition.

Builds a default ParameterDefinition with type inferred from T. An ID is auto-assigned.

Warning

NOT real-time safe - allocates memory

Template Parameters:

T – Value type (double, float, int, bool, or std::string)

Parameters:

key – The parameter key
initial_value – The initial value

Throws:

ParameterAlreadyExistsException – if the key already exists

void create_in_root(std::string_view key, const char *value)#

Creates a string parameter from a C-string.

Warning

NOT real-time safe - allocates memory

Parameters:

key – The parameter key
value – The initial value, stored as std::string

Throws:

ParameterAlreadyExistsException – if the key already exists

template<typename T> void set_in_root(std::string_view key, const T &value, ParameterListener *source = nullptr)#

Sets a parameter value directly in the root parameter map.

Updates existing parameters atomically for numeric types. Always notifies listeners. Use ParameterHandle::store() for silent writes.

Warning

NOT real-time safe for string types

Template Parameters:

T – Parameter type (double, float, int, bool, or std::string)

Parameters:

key – The parameter key (must already exist)
value – The value to set
source – Source listener for strategy-based notification filtering

Throws:

StateKeyNotFoundException – if the key doesn’t exist

void set_in_root(std::string_view key, const char *value, ParameterListener *source = nullptr)#

Sets a string parameter from a C-string.

Updates existing parameters atomically for numeric types. Always notifies listeners. Use ParameterHandle::store() for silent writes.

Warning

NOT real-time safe for string types

Template Parameters:

T – Parameter type (double, float, int, bool, or std::string)

Parameters:

key – The parameter key (must already exist)
value – The value to set
source – Source listener for strategy-based notification filtering

Throws:

StateKeyNotFoundException – if the key doesn’t exist

template<typename T> T get_from_root(std::string_view key, bool allow_blocking = false) const#

Gets a parameter value directly from the root parameter map.

Note

REAL-TIME SAFE for numeric types (double, float, int, bool)

Template Parameters:

T – Return type (double, float, int, bool, or std::string)

Parameters:

key – The parameter key
allow_blocking – If true, disables real-time sanitizer checks

Throws:

StateKeyNotFoundException – if the key doesn’t exist

Returns:

The parameter value converted to type T

Parameter get_parameter_from_root(std::string_view key) const#

Gets a Parameter object for the specified key.

Warning

NOT real-time safe - creates a Parameter object

Parameters:: key – The parameter key
Throws:: StateKeyNotFoundException – if the key doesn’t exist
Returns:: Parameter object providing access to the parameter

ParameterType get_type_from_root(std::string_view key) const#

Gets the type of a parameter.

Note

REAL-TIME SAFE - uses RCU for lock-free access

Parameters:: key – The parameter key
Throws:: StateKeyNotFoundException – if the key doesn’t exist
Returns:: ParameterType enum indicating the parameter’s type

template<typename T> ParameterHandle<T> get_handle_from_root(std::string_view key) const#

Gets a lightweight handle for real-time safe per-sample parameter access.

Warning

NOT real-time safe — call during setup, then use the handle on the real-time thread.

Template Parameters:

T – Numeric type: double, float, int, or bool

Parameters:

key – The parameter key (must already exist)

Throws:

StateKeyNotFoundException – if the key doesn’t exist
std::invalid_argument – if T doesn’t match the parameter’s native type

Returns:

ParameterHandle<T> pointing to the parameter’s atomic cache entry

bool is_modulatable(std::string_view key) const#

Checks if a parameter has the modulatable flag set.

Note

REAL-TIME SAFE - uses RCU for lock-free access

Parameters:: key – The parameter key
Returns:: true if the parameter exists and has kModulatable flag

template<typename T> ParameterHandle<T> get_handle_by_id(uint32_t id) const#

Gets a typed handle by parameter ID.

Warning

NOT real-time safe — call during setup

Template Parameters:

T – Numeric type matching the parameter’s native type

Parameters:

id – The parameter ID (auto-assigned or from ParameterDefinition::m_id)

Throws:

StateKeyNotFoundException – if no parameter has this ID
std::invalid_argument – if T doesn’t match the parameter’s type

Returns:

ParameterHandle<T> for the matching parameter

Parameter get_parameter_by_id(uint32_t id) const#

Gets a Parameter object by parameter ID.

Warning

NOT real-time safe

Parameters:: id – The parameter ID (auto-assigned or from ParameterDefinition::m_id)
Throws:: StateKeyNotFoundException – if no parameter has this ID
Returns:: Parameter object for the matching parameter

template<typename T> T get_by_id(uint32_t id, bool allow_blocking = false) const#

Gets a parameter value by ID.

Note

REAL-TIME SAFE for numeric types (double, float, int, bool)

Template Parameters:

T – Return type (double, float, int, bool, or std::string)

Parameters:

id – The parameter ID (auto-assigned or from ParameterDefinition::m_id)
allow_blocking – If true, disables real-time sanitizer checks

Throws:

StateKeyNotFoundException – if no parameter has this ID

Returns:

The parameter value converted to type T

template<typename T> void set_by_id(uint32_t id, const T &value, ParameterListener *source = nullptr)#

Sets a parameter value by ID.

Warning

NOT real-time safe for string types

Template Parameters:

T – Parameter type (double, float, int, bool, or std::string)

Parameters:

id – The parameter ID (auto-assigned or from ParameterDefinition::m_id)
value – The value to set
source – Source listener for strategy-based notification filtering

Throws:

StateKeyNotFoundException – if no parameter has this ID

void set_gesture_from_root(std::string_view key, bool gesture)#

Sets the gesture state for a parameter.

While a parameter is in-gesture, listeners that have m_receives_during_gesture=false will be skipped during notifications. Also dispatches on_gesture_start()/on_gesture_end() callbacks.

Parameters:

key – The parameter key
gesture – true to begin gesture, false to end

void from_json(const nlohmann::json &json_data, ParameterListener *source = nullptr)#

Updates multiple parameters from a JSON object.

Recursively processes the JSON structure and updates corresponding parameters. Parameters must already exist in the state.

Warning

NOT real-time safe - performs JSON parsing and memory allocation

Parameters:

json_data – JSON object containing parameter updates
source – Source listener for strategy-based notification filtering

Throws:

StateKeyNotFoundException – if a parameter key doesn’t exist

nlohmann::json to_json(bool include_definitions = true) const#

Generates a JSON dump of the entire state.

Warning

NOT real-time safe - performs JSON serialization

Parameters:: include_definitions – Whether to include parameter definitions
Returns:: JSON array of parameter objects

nlohmann::json group_to_json(std::string_view group_prefix, bool include_definitions = true) const#

Generates a JSON dump of parameters matching a group prefix.

Warning

NOT real-time safe - performs JSON serialization

Parameters:

group_prefix – Prefix to filter by (e.g., “parameter.engine0”)
include_definitions – Whether to include parameter definitions

Returns:

JSON array of matching parameter objects

virtual void clear() override#: Clears all parameters and subgroups from this group.

Warning

NOT real-time safe - modifies RCU-protected data structures

virtual bool is_empty() const override#

Checks if this group contains any parameters or subgroups.

Note

REAL-TIME SAFE - uses RCU for lock-free access

Returns:: true if the group is empty, false otherwise

Friends

friend class modulation::ModulationMatrix