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
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
-
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