Data Structures API

This section provides detailed API documentation for all data structures implemented in the STM32 DevOps Template.

Common Types

All data structures use common return types and constants defined in common_types.h:

enum status_t

Status enumeration for data structure operations.

This enumeration provides a standardized way to indicate the success or failure of data structure operations across all implementations in the project.

Usage Examples:

  • Function return values to indicate operation status

  • Error checking in calling code

  • Status reporting in embedded system diagnostics

Note

All data structure functions use this enum for consistent error handling

Warning

Always check return values when calling data structure functions

Values:

enumerator SUCCESS

Operation completed successfully.

enumerator FAILURE

Operation failed (e.g., queue full, empty, or null pointer)

Warning

doxygendefine: Cannot find define “SUCCESS” in doxygen xml output for project “STM32DevOpsTemplate” from directory: ./doxygen/xml

Warning

doxygendefine: Cannot find define “FAILURE” in doxygen xml output for project “STM32DevOpsTemplate” from directory: ./doxygen/xml

Queue API

Regular FIFO Queue Implementation

struct queue_t

Queue data structure.

This structure maintains the queue state including the data array, front and rear pointers, and element count. The implementation uses circular indexing for efficient memory utilization.

Structure Layout:

  • data[]: Array to store queue elements

  • front: Index of the first element to be dequeued

  • rear: Index where the next element will be enqueued

  • count: Current number of elements in the queue

Note

All members should be considered private and accessed only through API functions

Warning

Direct modification of structure members may lead to undefined behavior

Warning

doxygenfunction: Cannot find function “queue_init” in doxygen xml output for project “STM32DevOpsTemplate” from directory: ./doxygen/xml

Warning

doxygenfunction: Cannot find function “queue_enqueue” in doxygen xml output for project “STM32DevOpsTemplate” from directory: ./doxygen/xml

Warning

doxygenfunction: Cannot find function “queue_dequeue” in doxygen xml output for project “STM32DevOpsTemplate” from directory: ./doxygen/xml

Warning

doxygenfunction: Cannot find function “queue_peek” in doxygen xml output for project “STM32DevOpsTemplate” from directory: ./doxygen/xml

Warning

doxygenfunction: Cannot find function “queue_is_empty” in doxygen xml output for project “STM32DevOpsTemplate” from directory: ./doxygen/xml

Warning

doxygenfunction: Cannot find function “queue_is_full” in doxygen xml output for project “STM32DevOpsTemplate” from directory: ./doxygen/xml

Warning

doxygenfunction: Cannot find function “queue_size” in doxygen xml output for project “STM32DevOpsTemplate” from directory: ./doxygen/xml

Circular Queue API

Ring Buffer Implementation

struct circular_queue_t

Circular queue data structure.

This structure maintains the circular queue state including the data array, front and rear pointers, and a full indicator. The circular nature is achieved through modulo arithmetic on the pointers.

Structure Layout:

  • data[]: Array to store queue elements

  • front: Index of the first element to be dequeued

  • rear: Index where the next element will be enqueued

  • is_full: Flag to distinguish between full and empty states

Full vs Empty Detection:

Since front == rear can mean both empty and full, the is_full flag is used to distinguish between these states.

Note

All members should be considered private and accessed only through API functions

Warning

Direct modification of structure members may lead to undefined behavior

Public Members

void *data[CIRCULAR_QUEUE_MAX_SIZE]

Array of void pointers to store any data type.

int front

Index of the front element (next to dequeue)

int rear

Index of the rear position (next enqueue location)

int is_full

Flag indicating if the queue is full (1) or not (0)

Warning

doxygenfunction: Cannot find function “circular_queue_init” in doxygen xml output for project “STM32DevOpsTemplate” from directory: ./doxygen/xml

Warning

doxygenfunction: Cannot find function “circular_queue_enqueue” in doxygen xml output for project “STM32DevOpsTemplate” from directory: ./doxygen/xml

Warning

doxygenfunction: Cannot find function “circular_queue_dequeue” in doxygen xml output for project “STM32DevOpsTemplate” from directory: ./doxygen/xml

Warning

doxygenfunction: Cannot find function “circular_queue_peek” in doxygen xml output for project “STM32DevOpsTemplate” from directory: ./doxygen/xml

Warning

doxygenfunction: Cannot find function “circular_queue_is_empty” in doxygen xml output for project “STM32DevOpsTemplate” from directory: ./doxygen/xml

Warning

doxygenfunction: Cannot find function “circular_queue_is_full” in doxygen xml output for project “STM32DevOpsTemplate” from directory: ./doxygen/xml

Warning

doxygenfunction: Cannot find function “circular_queue_size” in doxygen xml output for project “STM32DevOpsTemplate” from directory: ./doxygen/xml

Priority Queue API

Binary Max-Heap Implementation

struct priority_queue_element_t

Priority queue element structure.

Each element in the priority queue contains both data and its associated priority value. This allows the heap to maintain proper ordering.

Priority Semantics:

Higher numerical values indicate higher priority. For example:

  • Priority 10 will be processed before priority 5

  • Priority 1 will be processed last among priorities 1, 5, 10

Note

Both data and priority are stored together for efficiency

Warning

Priority values should be chosen carefully to avoid overflow

Public Members

void *data

Pointer to the actual data element.

int priority

Priority value (higher numbers = higher priority)

struct priority_queue_t

Priority queue data structure.

This structure maintains the priority queue state including the heap array and current size. The heap property is maintained through specialized insertion and deletion algorithms.

Structure Layout:

  • elements[]: Array implementing the binary heap

  • size: Current number of elements in the heap

Heap Property:

For any element at index i: elements[i].priority >= elements[2*i+1].priority (left child) elements[i].priority >= elements[2*i+2].priority (right child)

Note

All members should be considered private and accessed only through API functions

Warning

Direct modification of structure members will break heap property

Public Members

priority_queue_element_t elements[PRIORITY_QUEUE_MAX_SIZE]

Heap array of elements.

int size

Current number of elements.

Warning

doxygenfunction: Cannot find function “priority_queue_init” in doxygen xml output for project “STM32DevOpsTemplate” from directory: ./doxygen/xml

Warning

doxygenfunction: Cannot find function “priority_queue_enqueue” in doxygen xml output for project “STM32DevOpsTemplate” from directory: ./doxygen/xml

Warning

doxygenfunction: Cannot find function “priority_queue_dequeue” in doxygen xml output for project “STM32DevOpsTemplate” from directory: ./doxygen/xml

Warning

doxygenfunction: Cannot find function “priority_queue_peek” in doxygen xml output for project “STM32DevOpsTemplate” from directory: ./doxygen/xml

Warning

doxygenfunction: Cannot find function “priority_queue_is_empty” in doxygen xml output for project “STM32DevOpsTemplate” from directory: ./doxygen/xml

Warning

doxygenfunction: Cannot find function “priority_queue_is_full” in doxygen xml output for project “STM32DevOpsTemplate” from directory: ./doxygen/xml

Warning

doxygenfunction: Cannot find function “priority_queue_size” in doxygen xml output for project “STM32DevOpsTemplate” from directory: ./doxygen/xml

Linked List API

Traditional Linked List Implementation

Warning

doxygenstruct: Cannot find class “node_t” in doxygen xml output for project “STM32DevOpsTemplate” from directory: ./doxygen/xml

Warning

doxygenfunction: Cannot find function “ll_init” in doxygen xml output for project “STM32DevOpsTemplate” from directory: ./doxygen/xml

Warning

doxygenfunction: Cannot find function “ll_insert_at_head” in doxygen xml output for project “STM32DevOpsTemplate” from directory: ./doxygen/xml

Warning

doxygenfunction: Cannot find function “ll_insert_at_tail” in doxygen xml output for project “STM32DevOpsTemplate” from directory: ./doxygen/xml

Warning

doxygenfunction: Cannot find function “ll_delete_at_head” in doxygen xml output for project “STM32DevOpsTemplate” from directory: ./doxygen/xml

Warning

doxygenfunction: Cannot find function “ll_delete_at_tail” in doxygen xml output for project “STM32DevOpsTemplate” from directory: ./doxygen/xml