在嵌入式系統中，任務之間常常需要通過一種結構化方式傳遞消息或數據，例如傳感器采集值上傳、串口數據解析、指令調度、事件響應等。在這些場景下，“隊列（Queue）”是一種非常經典且高效的數據組織形式。

通用隊列模塊以結構體數組為核心，結合固定內存與循環索引，實現了一個輕量、穩定、適配性強的隊列管理器。該模塊適合用于裸機或 RTOS 系統，是構建通信緩沖、消息隊列、任務分發機制的基礎組件。

核心結構與概念隊列管理器 queue_t

隊列通過 queue_t 結構體進行管理，內部維護以下成員：

• base：隊列內存起始地址；

• size：隊列最大容量（元素個數）；

• element_size：每個元素的字節數；

• front、rear：隊頭與隊尾索引，用于控制循環進出。

隊列結構采用 循環數組，即環形緩沖的方式，避免頻繁移動內存，入隊出隊僅需更新索引。

功能概覽

一、模塊功能概述

本隊列模塊支持以下基礎能力：

• 隊列的初始化與創建；

• 判斷隊列空滿狀態；

• 元素入隊與出隊；

• 隊列長度查詢；

• 隊列內容預讀取（不出隊）；

• 隊列清空；

• 隊尾元素刪除。

該隊列采用循環數組結構，不依賴動態內存分配，適合資源受限的嵌入式環境使用。支持自定義元素類型，通過配置元素大小與容器地址實現通用性管理。

二、使用方式簡述

使用者在使用該模塊時需自行提供以下參數：

• 數據緩沖區指針；

• 緩沖區容量（元素個數）；

• 單個元素的大小（字節）；

• 隊列管理結構體實例。

通過調用創建函數對隊列進行初始化后，即可使用相關接口進行操作，如入隊出隊等。

三、接口功能說明1. 創建隊列

通過 queue_create 函數傳入結構體、容器地址、容器容量、元素大小，即可完成隊列初始化。

2. 狀態判斷

提供 queue_is_empty 和 queue_is_full 接口判斷當前隊列狀態，便于進行邊界處理。

3. 元素操作

• 使用 queue_put 向隊列尾部寫入一個元素；

• 使用 queue_get 從隊列頭部讀取一個元素并出隊；

• 使用 queue_peek 可在不出隊的情況下獲取隊頭元素地址；

• 使用 queue_del 可直接丟棄隊頭元素（刪除而不讀取）；

• 使用 queue_clr 可清空整個隊列內容；

• 使用 queue_size 可獲取當前隊列中元素數量。

1. 串口接收命令緩存

串口中斷接收到數據幀后，將幀內容通過 queue_put 入隊，主循環中調用 queue_get 提取完整指令進行解析，避免數據丟失或阻塞。

typedef struct {
    uint8_t data[8];
} uart_cmd_t;uart_cmd_t cmd_buf[16];queue_t cmd_queue;

queue_create(&cmd_queue, cmd_buf, 16, sizeof(uart_cmd_t));

2. 多任務消息傳遞（RTOS環境）

任務 A 收集數據并通過 queue_put 入隊，任務 B 輪詢或通過事件驅動使用 queue_get 獲取消息，完成跨任務通信。

3. 簡易任務調度器

使用 queue_t 管理一個“函數指針 + 參數”結構體列表，即可構建輕量的調度任務表，實現軟中斷調度或定時任務執行。

通用隊列管理模塊，是構建嵌入式通信、緩存和調度功能的堅實基礎。通過靈活封裝與高效實現，該模塊能夠幫助開發者快速構建穩定的數據流通路。在系統架構設計中，清晰的數據組織方式往往是高質量代碼的關鍵，隊列，正是連接數據與邏輯的橋梁。

開源代碼：

#include "queue.h"#include <stddef.h>#include <string.h>/* @brief      創建一個隊列
 * @param[in]  q    - 隊列管理器
 * @param[in]  base - 隊列容器基地址
 * @param[in]  size - 隊列容器可容納元素個數
 * @param[in]  element_size - 隊列元素大小(sizeof(type))
 * @return     true - 創建成功, false - 創建失敗
 */bool queue_create(queue_t *q, void *base, int size, int element_size)
{    if (q == NULL || base == NULL || size== 0 || element_size == 0)        return false;
    q->base         = base;
    q->size         = size;
    q->element_size = element_size;
    q->front        = q->rear = 0;    return true;
}/* @brief      判斷隊列是否為空
 * @return    true - 隊列為空, false - 隊列非空
 */bool queue_is_empty(queue_t *q)
{    return q->front == q->rear;
}/* @brief      判斷隊列是否滿
 * @return     true - 隊列非滿, false - 隊列未滿
 */bool queue_is_full(queue_t *q)
{    return (q->rear + 1) % q->size == q->front;
}/* @brief      入隊(添加元素至隊尾)
 * @param[in]  element  - 隊列元素
 * @return     true - 成功入隊, false - 隊列滿
 */bool queue_put(queue_t *q,  void *element)
{    if (queue_is_full(q))        return false;
    memcpy((unsigned char *)q->base + q->rear * q->element_size, element, 
           q->element_size);
    q->rear = (q->rear + 1) % q->size;    return true;
}/* @brief      出隊(移除隊首元素)
 * @param[in]  element  - 指向隊首元素的地址
 * @return     true - 成功出隊, false - 隊列為空
 */bool queue_get(queue_t *q,  void *element)
{    if (queue_is_empty(q))        return false;   
    memcpy(element, (unsigned char *)q->base + q->front * q->element_size,
          q->element_size);
    q->front = (q->front + 1) % q->size;    return true;
}/* @brief      獲取隊首元素地址(預讀取)
 * @param[in]  element  - 指向隊首元素的地址
 * @return     true - 獲取成功, false - 獲取失敗隊列為空
 */bool queue_peek(queue_t *q, void **element)
{    if (queue_is_empty(q))        return false;   
    *element = (void *)((unsigned char *)q->base + q->front * 
              q->element_size);    return true;
}/* @brief      刪除隊尾元素
 * @return     true - 成功移除, false -  隊列為空, 
 */bool queue_del(queue_t *q)
{    if (queue_is_empty(q))        return false;   
    q->front = (q->front + 1) % q->size;    return true;
}/* @brief      獲取隊列元素個數
 * @return    隊列元素個數
 */int queue_size(queue_t *q)
{    return (q->rear + q->size - q->front ) % q->size;
}/* @brief      清空隊列
 * @return    none
 */void queue_clr(queue_t *q)
{
    q->front = q->rear = 0;
}