openlcb_login_statemachine.h File Reference

Non-blocking login state machine for node initialization. More...

Go to the source code of this file.

Data Structures
struct	interface_openlcb_login_state_machine_t
	Callback interface for the login state machine. All pointers are REQUIRED unless noted. Internal function pointers are exposed for unit testing. More...

Functions
void	OpenLcbLoginStateMachine_initialize (const interface_openlcb_login_state_machine_t *interface_openlcb_login_state_machine)
	Stores the callback interface. Call once at startup after OpenLcbLoginMessageHandler_initialize().
void	OpenLcbLoginMainStatemachine_run (void)
	Runs one non-blocking step of login processing. Call from main loop.
void	OpenLcbLoginStateMachine_process (openlcb_login_statemachine_info_t *openlcb_statemachine_info)
	Dispatches to the handler matching node->run_state. Exposed for unit testing.
bool	OpenLcbLoginStatemachine_handle_outgoing_openlcb_message (void)
	Tries to send the pending message; returns true if one was pending. Exposed for unit testing.
bool	OpenLcbLoginStatemachine_handle_try_reenumerate (void)
	Re-enters the state processor if the enumerate flag is set. Exposed for unit testing.
bool	OpenLcbLoginStatemachine_handle_try_enumerate_first_node (void)
	Starts enumeration from the first node if none is active. Exposed for unit testing.
bool	OpenLcbLoginStatemachine_handle_try_enumerate_next_node (void)
	Advances to the next node needing login. Exposed for unit testing.
openlcb_login_statemachine_info_t *	OpenLcbLoginStatemachine_get_statemachine_info (void)
	Returns pointer to internal static state machine info. For unit testing only — do not modify.

Detailed Description

Non-blocking login state machine for node initialization.

Copyright

Copyright (c) 2024, Jim Kueneman All rights reserved.

Redistribution and use in source and binary forms, with or without modification, are permitted provided that the following conditions are met:

• Redistributions of source code must retain the above copyright notice, this list of conditions and the following disclaimer.
• Redistributions in binary form must reproduce the above copyright notice, this list of conditions and the following disclaimer in the documentation and/or other materials provided with the distribution.

THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS" AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT HOLDER OR CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.

Walks each node through Initialization Complete, Producer Identified, Consumer Identified, and on_login_complete before entering RUNSTATE_RUN. Uses a polling architecture called repeatedly from the main loop; each call performs one atomic operation and returns immediately.

Author

Jim Kueneman

Date

4 Mar 2026

Function Documentation

OpenLcbLoginStateMachine_initialize()

void OpenLcbLoginStateMachine_initialize ( const interface_openlcb_login_state_machine_t * interface_openlcb_login_state_machine )

extern

Stores the callback interface. Call once at startup after OpenLcbLoginMessageHandler_initialize().

Parameters

interface_openlcb_login_state_machine

Must remain valid for application lifetime.

Stores the callback interface. Call once at startup after OpenLcbLoginMessageHandler_initialize().

Algorithm:

1. Store interface pointer
2. Link outgoing message buffer pointers in state machine info
3. Set payload type to BASIC, clear message and payload
4. Mark buffer as allocated, set current node to NULL

* @param interface_openlcb_login_state_machine Pointer to interface structure
* 

OpenLcbLoginMainStatemachine_run()

void OpenLcbLoginMainStatemachine_run ( void )

extern

Runs one non-blocking step of login processing. Call from main loop.

Tries to send a pending message, re-enumerate if flagged, or advance to the next node needing login. Nodes already in RUNSTATE_RUN are skipped.

Algorithm:

1. Try to send pending outgoing message (highest priority)
2. Re-enumerate if multi-message sequence in progress
3. Get first node if none active
4. Advance to next node Each step returns immediately after one operation.

OpenLcbLoginStateMachine_process()

void OpenLcbLoginStateMachine_process ( openlcb_login_statemachine_info_t * openlcb_statemachine_info )

extern

Dispatches to the handler matching node->run_state. Exposed for unit testing.

Parameters

openlcb_statemachine_info

Pointer to openlcb_login_statemachine_info_t context.

Dispatches to the handler matching node->run_state. Exposed for unit testing.

Algorithm:

1. Switch on run_state
2. RUNSTATE_LOAD_INITIALIZATION_COMPLETE → load_initialization_complete()
3. RUNSTATE_LOAD_PRODUCER_EVENTS → load_producer_events()
4. RUNSTATE_LOAD_CONSUMER_EVENTS → load_consumer_events()
5. RUNSTATE_LOGIN_COMPLETE → on_login_complete() if set, then RUNSTATE_RUN
6. All other states → return without action

* @param openlcb_statemachine_info Pointer to state machine info with node and message buffer
* 

OpenLcbLoginStatemachine_handle_outgoing_openlcb_message()

bool OpenLcbLoginStatemachine_handle_outgoing_openlcb_message ( void )

extern

Tries to send the pending message; returns true if one was pending. Exposed for unit testing.

Tries to send the pending message; returns true if one was pending. Exposed for unit testing.

Algorithm:

1. If valid flag not set, return false
2. Call send_openlcb_msg(); clear valid on success
3. Return true (caller should keep retrying until sent)

Returns

true if a message was pending, false if idle

OpenLcbLoginStatemachine_handle_try_reenumerate()

bool OpenLcbLoginStatemachine_handle_try_reenumerate ( void )

extern

Re-enters the state processor if the enumerate flag is set. Exposed for unit testing.

Re-enters the state processor if the enumerate flag is set. Exposed for unit testing.

Algorithm:

1. If enumerate flag not set, return false
2. Call process_login_statemachine() to generate next message
3. Return true (keep going until handler clears the flag)

Returns

true if re-enumeration occurred, false if complete

OpenLcbLoginStatemachine_handle_try_enumerate_first_node()

bool OpenLcbLoginStatemachine_handle_try_enumerate_first_node ( void )

extern

Starts enumeration from the first node if none is active. Exposed for unit testing.

Starts enumeration from the first node if none is active. Exposed for unit testing.

Algorithm:

1. If current node already set, return false
2. Get first node; return true if NULL (no nodes)
3. If run_state < RUNSTATE_RUN, call process_login_statemachine()
4. Return true

Returns

true if first node attempt was made, false if current node already exists

OpenLcbLoginStatemachine_handle_try_enumerate_next_node()

bool OpenLcbLoginStatemachine_handle_try_enumerate_next_node ( void )

extern

Advances to the next node needing login. Exposed for unit testing.

Advances to the next node needing login. Exposed for unit testing.

Algorithm:

1. If no current node, return false
2. Get next node; return true if NULL (end of list)
3. If run_state < RUNSTATE_RUN, call process_login_statemachine()
4. Return true

Returns

true if next node attempt was made, false if no current node exists

OpenLcbLoginStatemachine_get_statemachine_info()

openlcb_login_statemachine_info_t * OpenLcbLoginStatemachine_get_statemachine_info ( void )

extern

Returns pointer to internal static state machine info. For unit testing only — do not modify.

Returns pointer to internal static state machine info. For unit testing only — do not modify.