openlcb_buffer_fifo.h File Reference

FIFO queue for OpenLCB message pointers. More...

Go to the source code of this file.

Functions
void	OpenLcbBufferFifo_initialize (void)
	Initializes the FIFO to an empty state.
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.
uint16_t	OpenLcbBufferFifo_get_allocated_count (void)
	Returns the number of messages currently held in the FIFO.
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.

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.

Provides a fixed-capacity First-In-First-Out queue that holds pointers to openlcb_msg_t buffers allocated from openlcb_buffer_store.h. Messages are delivered in the order they were pushed. Must be initialized after OpenLcbBufferStore_initialize() and before any push or pop operations.

Author

Jim Kueneman

Date

8 Mar 2026

Function Documentation

OpenLcbBufferFifo_initialize()

void OpenLcbBufferFifo_initialize ( void )

extern

Initializes the FIFO to an empty state.

Clears all slots and resets head/tail. Must be called once during startup after OpenLcbBufferStore_initialize().

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 )

extern

Adds a message pointer to the tail of the FIFO.

Parameters

new_msg

Pointer to an openlcb_msg_t allocated from OpenLcbBufferStore.

Returns

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

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 )

extern

Removes and returns the oldest message from the FIFO.

Returns

Pointer to the oldest openlcb_msg_t, or NULL if empty.

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 )

extern

Returns true if the FIFO contains no messages.

OpenLcbBufferFifo_get_allocated_count()

uint16_t OpenLcbBufferFifo_get_allocated_count ( void )

extern

Returns the number of messages currently held in the FIFO.

OpenLcbBufferFifo_check_and_invalidate_messages_by_source_alias()

void OpenLcbBufferFifo_check_and_invalidate_messages_by_source_alias ( uint16_t alias )

extern

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 incoming messages from a node that has gone away — processing them could generate replies to a stale alias. The pop-phase guard or TX guard will discard them. Used when an AMR (Alias Map Reset) frame arrives and the alias must be retired within 100 ms.

Parameters

alias

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

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 )

extern

Inserts a message pointer at the head of the FIFO.

The inserted message becomes the next one returned by OpenLcbBufferFifo_pop(). Used by sibling dispatch to ensure loopback copies are processed immediately, minimizing the time the loopback buffer is allocated.

Parameters

new_msg

Pointer to an openlcb_msg_t allocated from OpenLcbBufferStore.

Returns

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

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