openlcb_buffer_list.c File Reference

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

Macros
#define	BUFFER_LIST_INPROCESS_TIMEOUT_TICKS   30
	Multi-frame assembly timeout in 100ms ticks (3 seconds).

Functions
void	OpenLcbBufferList_initialize (void)
	Initializes the buffer list.
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, or NULL if empty or out of range.
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.

Fixed-size array with linear search. NULL slots are free. Supports indexed access and attribute-based search (alias + MTI).

Author

Jim Kueneman

Date

4 Mar 2026

Macro Definition Documentation

BUFFER_LIST_INPROCESS_TIMEOUT_TICKS

#define BUFFER_LIST_INPROCESS_TIMEOUT_TICKS   30

Multi-frame assembly timeout in 100ms ticks (3 seconds).

Function Documentation

OpenLcbBufferList_initialize()

void OpenLcbBufferList_initialize

(

void

)

Initializes the buffer list.

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

)

Inserts a message pointer into the first available slot.

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 )

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

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

)

Removes a message from the list without freeing it.

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

)

Returns the message pointer at the given index, or NULL if empty or out of range.

Returns the message pointer at the given index.

OpenLcbBufferList_is_empty()

bool OpenLcbBufferList_is_empty

(

void

)

Returns true if the list contains no messages.

OpenLcbBufferList_check_timeouts()

void OpenLcbBufferList_check_timeouts

(

uint8_t

current_tick

)

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.