openlcb_buffer_list.h File Reference

Random-access list of OpenLCB message pointers. More...

Go to the source code of this file.

Functions
void	OpenLcbBufferList_initialize (void)
	Initializes the buffer list to an empty state.
openlcb_msg_t *	OpenLcbBufferList_add (openlcb_msg_t *new_msg)
	Inserts a message pointer into the first available slot.
openlcb_msg_t *	OpenLcbBufferList_find (uint16_t source_alias, uint16_t dest_alias, uint16_t mti)
	Finds a message matching source alias, dest alias, and MTI.
openlcb_msg_t *	OpenLcbBufferList_release (openlcb_msg_t *msg)
	Removes a message from the list without freeing it.
openlcb_msg_t *	OpenLcbBufferList_index_of (uint16_t index)
	Returns the message pointer at the given index.
bool	OpenLcbBufferList_is_empty (void)
	Returns true if the list contains no messages.
void	OpenLcbBufferList_check_timeouts (uint8_t current_tick)
	Scans for stale in-progress buffers and frees them.

Detailed Description

Random-access list of OpenLCB message pointers.

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.

Provides a fixed-size array of openlcb_msg_t pointers that supports both indexed access and attribute-based search (source alias, destination alias, and MTI). Primarily used for multi-frame message assembly where frames must be matched to an in-progress message by sender and type. Must be initialized after OpenLcbBufferStore_initialize().

Author

Jim Kueneman

Date

28 Feb 2026

Function Documentation

OpenLcbBufferList_initialize()

void OpenLcbBufferList_initialize ( void )

extern

Initializes the buffer list to an empty state.

Clears all slots to NULL. Must be called once during startup after OpenLcbBufferStore_initialize().

Initializes the buffer list to an empty state.

Algorithm:

1. Clear all slots to NULL

OpenLcbBufferList_add()

openlcb_msg_t * OpenLcbBufferList_add ( openlcb_msg_t * new_msg )

extern

Inserts a message pointer into the first available slot.

Parameters

new_msg

Pointer to an openlcb_msg_t allocated from OpenLcbBufferStore.

Returns

The stored pointer on success, or NULL if the list is full.

Algorithm:

1. Search for first NULL slot
2. Store the pointer and return it, or return NULL if full

* @param new_msg Pointer to @ref openlcb_msg_t from the buffer store
* 

Returns

The stored pointer on success, or NULL if the list is full

OpenLcbBufferList_find()

openlcb_msg_t * OpenLcbBufferList_find ( uint16_t source_alias, uint16_t dest_alias, uint16_t mti )

extern

Finds a message matching source alias, dest alias, and MTI.

Parameters

source_alias	12-bit CAN alias of the originating node.
dest_alias	12-bit CAN alias of the destination node.
mti	Message Type Indicator to match.

Returns

Pointer to matching openlcb_msg_t, or NULL if not found.

Algorithm:

1. Search all non-NULL slots for a triple match
2. Return the first match, or NULL if none found

* @param source_alias CAN alias of sending node
* @param dest_alias CAN alias of receiving node
* @param mti Message Type Indicator code
* 

Returns

Pointer to matching openlcb_msg_t, or NULL if not found

OpenLcbBufferList_release()

openlcb_msg_t * OpenLcbBufferList_release ( openlcb_msg_t * msg )

extern

Removes a message from the list without freeing it.

Parameters

msg	Pointer to the openlcb_msg_t to remove (NULL is safe).

Returns

The removed pointer, or NULL if not found.

Algorithm:

1. If NULL, return NULL
2. Search for the pointer, clear the slot, return the pointer
3. Return NULL if not found

* @param msg Pointer to @ref openlcb_msg_t to remove (NULL is safe)
* 

Returns

The removed pointer, or NULL if not found

OpenLcbBufferList_index_of()

openlcb_msg_t * OpenLcbBufferList_index_of ( uint16_t index )

extern

Returns the message pointer at the given index.

Parameters

index

Zero-based slot index (0 to LEN_MESSAGE_BUFFER - 1).

Returns

Pointer to openlcb_msg_t, or NULL if empty or out of range.

Returns the message pointer at the given index.

OpenLcbBufferList_is_empty()

bool OpenLcbBufferList_is_empty ( void )

extern

Returns true if the list contains no messages.

OpenLcbBufferList_check_timeouts()

void OpenLcbBufferList_check_timeouts ( uint8_t current_tick )

extern

Scans for stale in-progress buffers and frees them.

Caller MUST hold the shared resource lock before calling. Frees any in-progress message whose elapsed time (computed from the global 100ms tick) has reached the timeout threshold.

Parameters

current_tick

Current value of the global 100ms tick counter, passed as a parameter from the main loop.