Class thl::StateGroup

class StateGroup

Inheritance diagram for thl::StateGroup:

Hierarchical container for organizing parameters into logical groups.

StateGroup provides a tree structure for organizing parameters with dot-separated path support (e.g., “synth.oscillator.frequency”). Groups can contain parameters and nested subgroups.

Subclassed by thl::State

Public Functions

StateGroup(State *root_state, StateGroup *parent = nullptr, std::string_view name = "")

virtual ~StateGroup()

StateGroup *create_group(std::string_view name)

Creates a new child group.

Creates a subgroup with the specified name. If the group already exists, returns the existing group.

Warning

NOT real-time safe - may allocate memory for new groups

Parameters:

name – The name of the group to create

Returns:

Pointer to the created or existing group

StateGroup *get_group(std::string_view name) const

Gets a child group by name.

Note

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

Parameters:

name – The name of the group to retrieve

Returns:

Pointer to the group, or nullptr if not found

bool has_group(std::string_view name) const

Checks if a child group exists.

Note

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

Parameters:

name – The name of the group to check

Returns:

true if the group exists, false otherwise

void create(std::string_view path, ParameterDefinition def)

Creates a parameter with a ParameterDefinition.

Creates intermediate groups as needed. Throws if the parameter already exists.

Warning

NOT real-time safe - allocates memory

Parameters:

• path – The parameter path (e.g., “oscillator.frequency”)

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

Throws:

std::invalid_argument – if the parameter already exists

template<typename T>
void create(std::string_view path, const T &value)

Creates a parameter with an initial value and default definition.

Creates intermediate groups as needed. Throws if the parameter already exists.

Warning

NOT real-time safe - allocates memory

Template Parameters:

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

Parameters:

• path – The parameter path

• value – The initial value

Throws:

std::invalid_argument – if the parameter already exists

void create(std::string_view path, const char *value)

Creates a string parameter from a C-string.

Warning

NOT real-time safe - allocates memory

Parameters:

• path – The parameter path

• value – The initial value, stored as std::string

Throws:

std::invalid_argument – if the parameter already exists

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

Sets a parameter value at the specified path.

Updates an existing parameter. Throws if the parameter doesn’t exist. Always notifies listeners. Use ParameterHandle::store() for silent writes.

Warning

NOT real-time safe - may allocate for string parameters

Template Parameters:

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

Parameters:

• path – The parameter path

• value – The value to set

• source – Source listener for strategy-based notification filtering

Throws:

• StateKeyNotFoundException – if parameter doesn’t exist

• StateGroupNotFoundException – if intermediate group doesn’t exist

void set(std::string_view path, const char *value, ParameterListener *source = nullptr)

Sets a string parameter from a C-string.

Updates an existing parameter. Throws if the parameter doesn’t exist. Always notifies listeners. Use ParameterHandle::store() for silent writes.

Warning

NOT real-time safe - may allocate for string parameters

Template Parameters:

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

Parameters:

• path – The parameter path

• value – The value to set

• source – Source listener for strategy-based notification filtering

Throws:

• StateKeyNotFoundException – if parameter doesn’t exist

• StateGroupNotFoundException – if intermediate group doesn’t exist

template<typename T>
T get(std::string_view path, bool allow_blocking = false) const

Gets a parameter value from the specified path.

Note

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

Template Parameters:

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

Parameters:

• path – The parameter path

• allow_blocking – If true, disables real-time sanitizer checks

Throws:

• StateKeyNotFoundException – if the parameter doesn’t exist

• StateGroupNotFoundException – if an intermediate group doesn’t exist

Returns:

The parameter value converted to type T

Parameter get_parameter(std::string_view path) const

Gets a Parameter object for the specified path.

Warning

NOT real-time safe (BLOCKING) - creates a Parameter object

Parameters:

path – The parameter path (e.g., “oscillator.frequency”)

Throws:

• StateKeyNotFoundException – if the parameter doesn’t exist

• StateGroupNotFoundException – if an intermediate group doesn’t exist

Returns:

Parameter object providing access to the parameter

std::map<std::string, Parameter> get_parameters() const

Gets all parameters in this group and its subgroups.

Warning

NOT real-time safe - allocates memory for the returned map

Returns:

Map of parameter paths to Parameter objects

ParameterType get_parameter_type(std::string_view path) const

Gets the type of a parameter at the specified path.

Note

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

Parameters:

path – The parameter path

Throws:

StateKeyNotFoundException – if the parameter doesn’t exist

Returns:

ParameterType enum indicating the parameter’s type

template<typename T>
ParameterHandle<T> get_handle(std::string_view path) 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:

path – The parameter path (must already exist)

Throws:

• StateKeyNotFoundException – if the parameter doesn’t exist

• StateGroupNotFoundException – if an intermediate group 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

void set_gesture(std::string_view path, bool gesture)

Sets the gesture state for a parameter.

Parameters:

• path – The parameter path

• gesture – true to begin gesture, false to end

void add_listener(ParameterListener *listener)

Adds a listener for parameter changes in this group.

Warning

NOT real-time safe - modifies listener list

Parameters:

listener – Pointer to the listener (must remain valid while registered)

void remove_listener(ParameterListener *listener)

Removes a previously added listener.

Warning

NOT real-time safe - modifies listener list

Parameters:

listener – Pointer to the listener to remove

void notify_parameter_change(std::string_view path)

Manually triggers notifications for a parameter.

Warning

NOT real-time safe - invokes listener callbacks

Parameters:

path – The parameter path to notify about

virtual void clear()

Clears all parameters and subgroups from this group.

Warning

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

void clear_groups()

Clears all subgroups from this group.

Warning

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

virtual bool is_empty() const

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

inline StateGroup *get_parent() const

inline State *get_root_state() const

std::string_view get_full_path() const

Gets the full dot-separated path from the root to this group.

Note

REAL-TIME SAFE - uses pre-allocated string buffers

Returns:

String view of the full path