重构

Foundation/c_LinkQueue.h

@@ -5,66 +5,63 @@
 #include <c_Types.h>
 #endif /*INCLUDED_C_TYPES_H*/
 
+#ifndef INCLUDED_C_ALLOCATOR_H
+#include <c_Allocator.h>
+#endif /*INCLUDED_C_ALLOCATOR_H*/
+
+/* ------------------------------------------------------------------------------------------------------------------ */
+/*  */
+
+#define QUEUE_NODE_DATA(node) ((void*)((char*)(node) + sizeof(c_LinkQueueNode_t)))
+
 /* ------------------------------------------------------------------------------------------------------------------ */
 /*  */
 
 typedef struct c_LinkQueueNode_t {
-    void* data;
-    struct c_LinkQueueNode_t * next;
-}c_LinkQueueNode_t;
+    struct c_LinkQueueNode_t* next; // 后驱节点指针
+    // 后面会紧跟一整块大小为 item_size 的物理连续内存直接存放真实数据值
+} c_LinkQueueNode_t;
 
+// 终极闭环泛型链式队列控制头（无哨兵极致架构）
 typedef struct {
-    c_LinkQueueNode_t* head;
-    c_LinkQueueNode_t* tail;
-    int obj_size;
-    c_size_t size;
-}c_LinkQueue_t;
-
-typedef struct {
-    c_LinkQueue_t* queue;
-    c_LinkQueueNode_t** node;
-}c_LinkQueueIter_t;
+    c_LinkQueueNode_t* head;  // 指向真实的队头节点（出队端）
+    c_LinkQueueNode_t* tail;  // 指向真实的队尾节点（入队端）
+    c_size_t item_size;       // 单个元素的字节大小
+    c_size_t size;            // 当前队列中持有的有效元素个数（O(1) 计数）
+    c_Allocator_t allocator;  // 内部绑定的自主内存管理器
+} c_LinkQueue_t;
 
 /* ------------------------------------------------------------------------------------------------------------------ */
 /*  */
 
-c_err_t c_LinkQueue_Init(c_LinkQueue_t* self, int obj_size);
-
-void c_LinkQueue_Destroy(c_LinkQueue_t* self);
-
-c_err_t c_LinkQueue_Push(c_LinkQueue_t* self, void* obj);
-
-c_err_t c_LinkQueue_Pop(c_LinkQueue_t* self, void* obj);
-
-c_err_t c_LinkQueue_Peek(c_LinkQueue_t* self, void* obj);
-
 C_STATIC_FORCE_INLINE
-void c_LinkQueueIter_Init(c_LinkQueueIter_t* self, c_LinkQueue_t* queue) {
-    if (!self || !queue) return;
-    self->queue = queue;
-    self->node = &queue->head;
+void* c_LinkQueueNode_Get(const c_LinkQueueNode_t* self) {
+    if (!self) return NULL;
+    return QUEUE_NODE_DATA(self);
+}
+
+/* ------------------------------------------------------------------------------------------------------------------ */
+/*  */
+
+c_err_t c_LinkQueue_Init(c_LinkQueue_t* self, c_size_t item_size, c_Allocator_t* allocator);
+void    c_LinkQueue_Destroy(c_LinkQueue_t* self);
+
+// 核心链式队列操作 API (安全值复制模式)
+c_err_t c_LinkQueue_Enqueue(c_LinkQueue_t* self, const void* item);
+c_err_t c_LinkQueue_Dequeue(c_LinkQueue_t* self, void* out_item);
+void*   c_LinkQueue_Peek(const c_LinkQueue_t* self);
+void    c_LinkQueue_Clear(c_LinkQueue_t* self);
+
+// 内联高频辅助接口
+C_STATIC_FORCE_INLINE
+c_size_t c_LinkQueue_Size(const c_LinkQueue_t* self) {
+    if (!self) return 0;
+    return self->size; // O(1) 实时读取
 }
 
 C_STATIC_FORCE_INLINE
-c_bool_t c_LinkQueueIter_HasNext(c_LinkQueueIter_t* self) {
-    if (!self) return C_FALSE;
-    return (self->node != NULL) && (*(self->node) != NULL);
+bool c_LinkQueue_IsEmpty(const c_LinkQueue_t* self) {
+    return c_LinkQueue_Size(self) == 0;
 }
 
-C_STATIC_FORCE_INLINE
-void* c_LinkQueueIter_Next(c_LinkQueueIter_t* self) {
-    if (!self || !self->node || !*(self->node)) return NULL;
-    void* data = (*(self->node))->data;
-    self->node = &(*(self->node))->next;
-    return data;
-}
-
-C_STATIC_FORCE_INLINE
-void* c_LinkQueueIter_Get(c_LinkQueueIter_t* self) {
-    if (!self || !self->node || !*(self->node)) return NULL;
-    return (*(self->node))->data;
-}
-
-void c_LinkQueueIter_Remove(c_LinkQueueIter_t* self);
-
 #endif /*INCLUDED_C_LINKQUEUE_H*/