openlcb_buffer_fifo.c File Reference

FIFO queue for OpenLCB message pointers. More...

Data Structures
struct	openlcb_msg_fifo_t
	Circular buffer of message pointers with head/tail indices. More...

Macros
#define	LEN_MESSAGE_FIFO_BUFFER   (LEN_MESSAGE_BUFFER + 1)
	FIFO buffer size (one extra slot for full detection without additional state)

Functions
void	OpenLcbBufferFifo_initialize (void)
	Initializes the FIFO.
openlcb_msg_t *	OpenLcbBufferFifo_push (openlcb_msg_t *new_msg)
	Adds a message pointer to the tail of the FIFO.
openlcb_msg_t *	OpenLcbBufferFifo_pop (void)
	Removes and returns the oldest message from the FIFO.
bool	OpenLcbBufferFifo_is_empty (void)
	Returns true if the FIFO contains no messages.
void	OpenLcbBufferFifo_check_and_invalidate_messages_by_source_alias (uint16_t alias)
	Marks all queued incoming messages from a released alias as invalid.
openlcb_msg_t *	OpenLcbBufferFifo_push_to_head (openlcb_msg_t *new_msg)
	Inserts a message pointer at the head of the FIFO.
uint16_t	OpenLcbBufferFifo_get_allocated_count (void)
	Returns the number of messages currently held in the FIFO.

Detailed Description

FIFO queue for 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.

Circular buffer with one wasted slot for full/empty detection. Head = next insertion, tail = next removal. Empty when head == tail.

Author

Jim Kueneman

Date

8 Mar 2026

Macro Definition Documentation

LEN_MESSAGE_FIFO_BUFFER

#define LEN_MESSAGE_FIFO_BUFFER   (LEN_MESSAGE_BUFFER + 1)

FIFO buffer size (one extra slot for full detection without additional state)

Function Documentation

OpenLcbBufferFifo_initialize()

void OpenLcbBufferFifo_initialize

(

void

)

Initializes the FIFO.

Initializes the FIFO to an empty state.

Algorithm:

1. Clear all slots to NULL
2. Reset head and tail to 0

OpenLcbBufferFifo_push()

openlcb_msg_t * OpenLcbBufferFifo_push

(

openlcb_msg_t *

new_msg

)

Adds a message pointer to the tail of the FIFO.

Algorithm:

1. Compute next head position with wraparound
2. If next == tail the FIFO is full, return NULL
3. Store pointer at head, advance head, return the pointer

* @param new_msg Pointer to @ref openlcb_msg_t allocated from OpenLcbBufferStore
* 

Returns

The queued pointer on success, or NULL if the FIFO is full

OpenLcbBufferFifo_pop()

openlcb_msg_t * OpenLcbBufferFifo_pop

(

void

)

Removes and returns the oldest message from the FIFO.

Algorithm:

1. If head == tail the FIFO is empty, return NULL
2. Retrieve pointer at tail, advance tail with wraparound
3. Return the pointer

Returns

Pointer to the oldest openlcb_msg_t, or NULL if the FIFO is empty

OpenLcbBufferFifo_is_empty()

bool OpenLcbBufferFifo_is_empty

(

void

)

Returns true if the FIFO contains no messages.

OpenLcbBufferFifo_check_and_invalidate_messages_by_source_alias()

void OpenLcbBufferFifo_check_and_invalidate_messages_by_source_alias

(

uint16_t

alias

)

Marks all queued incoming messages from a released alias as invalid.

Walks the FIFO from tail to head and sets state.invalid on any message whose source_alias matches the released alias. These are completed incoming messages from a node that has gone away — processing them could generate replies to a stale alias that may now belong to a different node. The pop-phase guard or TX guard will discard them.

Does not remove messages from the FIFO — the circular buffer head/tail pointers stay untouched.

* @param alias  12-bit CAN alias that was released.  If 0, returns immediately.
* 

OpenLcbBufferFifo_push_to_head()

openlcb_msg_t * OpenLcbBufferFifo_push_to_head

(

openlcb_msg_t *

new_msg

)

Inserts a message pointer at the head of the FIFO.

Algorithm:

1. Compute previous tail position with wraparound
2. If prev == head the FIFO is full, return NULL
3. Move tail back, store pointer at new tail, return the pointer

* @param new_msg Pointer to @ref openlcb_msg_t allocated from OpenLcbBufferStore
* 

Returns

The queued pointer on success, or NULL if the FIFO is full

OpenLcbBufferFifo_get_allocated_count()

uint16_t OpenLcbBufferFifo_get_allocated_count

(

void

)

Returns the number of messages currently held in the FIFO.