cKit/Foundation/c_LinkQueue.h

#ifndef INCLUDED_C_LINKQUEUE_H
#define INCLUDED_C_LINKQUEUE_H

#ifndef INCLUDED_C_TYPES_H
#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 {
    struct c_LinkQueueNode_t* next; // 后驱节点指针
    // 后面会紧跟一整块大小为 item_size 的物理连续内存直接存放真实数据值
} c_LinkQueueNode_t;

// 终极闭环泛型链式队列控制头（无哨兵极致架构）
typedef struct {
    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_STATIC_FORCE_INLINE
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
bool c_LinkQueue_IsEmpty(const c_LinkQueue_t* self) {
    return c_LinkQueue_Size(self) == 0;
}

#endif /*INCLUDED_C_LINKQUEUE_H*/