重构

Foundation/c_ArrayQueue.h

@@ -5,29 +5,46 @@
 #include <c_Types.h>
 #endif /*INCLUDED_C_TYPES_H*/
 
+#ifndef INCLUDED_C_ALLOCATOR_H
+#include <c_Allocator.h>
+#endif /*INCLUDED_C_ALLOCATOR_H*/
 
 
 /* ------------------------------------------------------------------------------------------------------------------ */
 /*  */
 
 typedef struct {
-    void* array;
-    int obj_size;
-    c_size_t capacity;
-    c_size_t size;
-}c_ArrayQueue_t;
+    void* array;              // 连续的动态环形缓冲区
+    c_size_t item_size;       // 单个元素的字节大小
+    c_size_t capacity;        // 环形缓冲区当前最大可承纳的元素容量
+    c_size_t size;            // 当前队列中已有的元素个数
+    c_size_t head;            // 指向队头元素的索引
+    c_size_t tail;            // 指向队尾下一个待插入坑位的索引
+    c_Allocator_t allocator;  // 绑定的内存管理器（支持自定义/伙伴系统）
+} c_ArrayQueue_t;
 
+/* ------------------------------------------------------------------------------------------------------------------ */
+/*  */
 
-c_err_t c_ArrayQueue_Init(c_ArrayQueue_t* self, int obj_size, c_size_t capacity);
-
+c_err_t c_ArrayQueue_Init(c_ArrayQueue_t* self, c_size_t item_size, c_size_t capacity, c_Allocator_t* allocator);
 void c_ArrayQueue_Destroy(c_ArrayQueue_t* self);
 
-c_err_t c_ArrayQueue_Push(c_ArrayQueue_t* self, void* obj);
+// 核心队列操作 API
+c_err_t c_ArrayQueue_Enqueue(c_ArrayQueue_t* self, const void* item);
+c_err_t c_ArrayQueue_Dequeue(c_ArrayQueue_t* self, void* out_item);
+void*   c_ArrayQueue_Peek(const c_ArrayQueue_t* self);
+c_err_t c_ArrayQueue_Resize(c_ArrayQueue_t* self, c_size_t new_capacity);
 
-c_err_t c_ArrayQueue_Pop(c_ArrayQueue_t* self, void* obj);
+// 内联高频辅助接口
+C_STATIC_FORCE_INLINE
+c_size_t c_ArrayQueue_Size(const c_ArrayQueue_t* self) {
+    if (!self) return 0;
+    return self->size;
+}
 
-void* c_ArrayQueue_Peek(c_ArrayQueue_t* self);
-
-c_err_t c_ArrayQueue_Remove(c_ArrayQueue_t* self, c_size_t index);
+C_STATIC_FORCE_INLINE
+bool c_ArrayQueue_IsEmpty(const c_ArrayQueue_t* self) {
+    return c_ArrayQueue_Size(self) == 0;
+}
 
 #endif /*INCLUDED_C_ARRAYQUEUE_H*/