Clears all FSM type definitions from the global registry.

Returns

• ok - Registry cleared successfully

Warning

This function removes ALL registered FSM types. Use with caution.

Example

cure_fsm_runtime:clear_fsm_registry().

Clears any existing timeout for the FSM.

Arguments

• FSMPid - The PID of the FSM process

Returns

• ok - Timeout cleared successfully (asynchronous)

Example

cure_fsm_runtime:clear_timeout(FSMPid).

Compiles an FSM definition from AST format to optimized runtime format.

This function transforms a parsed FSM definition into an efficient runtime representation with pre-compiled guards, actions, and optimized transition lookups.

Arguments

• FSMDef - FSM definition record from the parser containing:
  • name - FSM type name
  • states - List of state names
  • initial - Initial state name
  • state_defs - List of state definition records

Returns

• #fsm_definition{} - Compiled FSM definition ready for runtime execution

Compilation Process

1. Transition Compilation: Creates flat lookup maps from nested AST
2. Guard Compilation: Compiles guard expressions to instruction sequences
3. Action Compilation: Compiles action expressions to stack-based instructions
4. Timeout Compilation: Extracts and organizes timeout definitions

Example

CompiledDef = cure_fsm_runtime:compile_fsm_definition(ParsedFSM),
cure_fsm_runtime:register_fsm_type(my_fsm, CompiledDef).

Retrieves comprehensive FSM information for debugging and introspection.

Arguments

• FSMPid - The PID of the FSM process

Returns

• {ok, Info} - Map containing FSM information:
  • fsm_type - The FSM type name
  • current_state - Current state name
  • data - Current state data
  • event_history - List of recent events (newest first)
• {error, Reason} - Error retrieving information

Example

{ok, #{fsm_type := Type, current_state := State}} = 
    cure_fsm_runtime:get_fsm_info(FSMPid).

Retrieves performance statistics for an FSM instance.

Arguments

• FSMPid - The PID of the FSM process

Returns

• {ok, Stats} - Performance statistics record containing:
  • events_processed - Total number of events processed
  • avg_event_time - Average event processing time (microseconds)
  • max_event_time - Maximum event processing time (microseconds)
  • memory_usage - Current memory usage (bytes)
  • last_updated - Timestamp of last update
• {error, Reason} - Error retrieving statistics

Example

{ok, Stats} = cure_fsm_runtime:get_performance_stats(FSMPid),
AvgTime = Stats#fsm_perf_stats.avg_event_time.

Returns a list of all registered FSM type names.

Returns

• List of FSM type names (atoms)

Example

Types = cure_fsm_runtime:get_registered_fsm_types(),
%% Types might be [counter, traffic_light, state_machine]

Retrieves the current state of an FSM instance.

Arguments

• FSMPid - The PID of the FSM process

Returns

• {ok, State} - The current state name (atom)
• {error, Reason} - Error retrieving state

Example

{ok, CurrentState} = cure_fsm_runtime:get_state(FSMPid).

Looks up an FSM definition by type name in the global registry.

Arguments

• FSMType - The FSM type name to look up (atom)

Returns

• {ok, Definition} - FSM definition found
• {error, not_found} - FSM type not registered

Example

case cure_fsm_runtime:lookup_fsm_definition(counter) of
    {ok, Definition} -> cure_utils:debug("Found FSM definition~n");
    {error, not_found} -> cure_utils:debug("FSM type not registered~n")
end.

Registers a new FSM type definition in the global registry.

Arguments

• FSMType - The FSM type name (atom)
• Definition - Compiled FSM definition record

Returns

• ok - FSM type registered successfully

Example

Definition = #fsm_definition{name = counter, ...},
ok = cure_fsm_runtime:register_fsm_type(counter, Definition).

Sends multiple events to an FSM in a single operation for improved performance.

Arguments

• FSMPid - The PID of the FSM process
• Events - List of events to send. Each event can be:
  • An atom (event without data)
  • A tuple {Event, Data} (event with data)

Returns

• ok - Batch sent successfully (asynchronous)

Performance

Batch processing can provide 5-10x performance improvement over individual event sends when processing large numbers of events.

Example

Events = [start, {increment, 5}, stop],
cure_fsm_runtime:send_batch_events(FSMPid, Events).

Sends an event to an FSM instance without event data.

This is a convenience function that calls send_event/3 with undefined event data.

Arguments

• FSMPid - The PID of the target FSM process
• Event - The event to send (atom)

Returns

• ok - Event sent successfully (asynchronous)

Example

cure_fsm_runtime:send_event(FSMPid, start).

Sends an event with associated data to an FSM instance.

Arguments

• FSMPid - The PID of the target FSM process
• Event - The event to send (atom)
• Data - Event data to accompany the event

Returns

• ok - Event sent successfully (asynchronous)

Example

cure_fsm_runtime:send_event(FSMPid, button_pressed, #{button => ok}).

Sets a timeout for the FSM that will trigger the specified event after the given time.

Arguments

• FSMPid - The PID of the FSM process
• Timeout - Timeout in milliseconds
• Event - Event to trigger when timeout occurs

Returns

• ok - Timeout set successfully (asynchronous)

Example

cure_fsm_runtime:set_timeout(FSMPid, 5000, timeout_expired).

Starts a new FSM instance with the specified type and initial data.

This is a convenience function that calls start_fsm/3 with an empty options list.

Arguments

• FSMType - The registered FSM type name (atom)
• InitialData - Initial state data for the FSM instance

Returns

• {ok, Pid} - Success with the FSM process PID
• {error, {fsm_type_not_found, FSMType}} - FSM type not registered
• {error, Reason} - Other gen_server startup errors

Example

{ok, FSM} = cure_fsm_runtime:start_fsm(counter, #{count => 0}).

Starts a new FSM instance with the specified type, initial data, and options.

Arguments

• FSMType - The registered FSM type name (atom)
• InitialData - Initial state data for the FSM instance
• Options - List of startup options (currently unused)

Returns

• {ok, Pid} - Success with the FSM process PID
• {error, {fsm_type_not_found, FSMType}} - FSM type not registered
• {error, Reason} - Other gen_server startup errors

Example

{ok, FSM} = cure_fsm_runtime:start_fsm(traffic_light, #{}, []).

Stops an FSM instance gracefully.

Arguments

• FSMPid - The PID of the FSM process to stop

Returns

• ok - FSM stopped successfully
• {error, Reason} - Error stopping the FSM

Example

ok = cure_fsm_runtime:stop_fsm(FSMPid).

Removes an FSM type definition from the global registry.

Arguments

• FSMType - The FSM type name to unregister (atom)

Returns

• true - FSM type unregistered successfully (or did not exist)

Example

cure_fsm_runtime:unregister_fsm_type(old_counter).