cKit/Foundation/c_PtrLinkBag.h

#ifndef INCLUDED_C_PTRLINKBAG_H
#define INCLUDED_C_PTRLINKBAG_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*/
#include "c_PtrBag.h"

/* ------------------------------------------------------------------------------------------------------------------ */
/*  */

typedef struct c_PtrLinkNode_t {
    void* ptr;
    struct c_PtrLinkNode_t* next;
}c_PtrLinkNode_t;

typedef struct {
    c_PtrLinkNode_t* head;
    c_size_t size;
    c_Allocator_t allocator;
}c_PtrLinkBag_t;

typedef struct {
    c_PtrLinkBag_t* bag;   // 绑定的非 const 宿主袋子控制头，自主提取内置 allocator 并联动 size
    c_PtrLinkNode_t** pp;  // 二级指针灵魂：前驱 next 指针域内存地址的直接隐射
} c_PtrLinkBagIter_t;

/* ------------------------------------------------------------------------------------------------------------------ */
/*  */

c_err_t          c_PtrLinkBag_Init(c_PtrLinkBag_t* self, c_Allocator_t* allocator);
void             c_PtrLinkBag_Destroy(c_PtrLinkBag_t* self);

c_PtrLinkNode_t* c_PtrLinkBag_Add(c_PtrLinkBag_t* self, void* ptr);
c_err_t          c_PtrLinkBag_Remove(c_PtrLinkBag_t* self, void* ptr);

// C_STATIC_FORCE_INLINE 极致高频内联提速接口
C_STATIC_FORCE_INLINE
c_size_t c_PtrLinkBag_Size(const c_PtrLinkBag_t* self) {
    if (!self) return 0;
    return self->size; // 真正的实时 O(1) 返回
}

C_STATIC_FORCE_INLINE
bool c_PtrLinkBag_IsEmpty(const c_PtrLinkBag_t* self) {
    return c_PtrLinkBag_Size(self) == 0;
}

/* ------------------------------------------------------------------------------------------------------------------ */
/*  */

C_STATIC_FORCE_INLINE
void c_PtrLinkBagIter_Init(c_PtrLinkBagIter_t* self, c_PtrLinkBag_t* bag) {
    if (!self) return;
    self->bag = bag;
    if (!bag || !bag->head) {
        self->pp = NULL;
        return;
    }
    // 二级指针初始死死咬定宿主 Dummy Head 内部的 next 指针域
    self->pp = &(bag->head);
}

C_STATIC_FORCE_INLINE
bool c_PtrLinkBagIter_HasNext(const c_PtrLinkBagIter_t* self) {
    return (self != NULL && self->pp != NULL && *self->pp != NULL);
}

C_STATIC_FORCE_INLINE
void* c_PtrLinkBagIter_Get(c_PtrLinkBagIter_t* self) {
    if (!c_PtrLinkBagIter_HasNext(self)) return NULL;
    return (*self->pp)->ptr; // 只读窥探数据，绝对不产生位移副作用
}

C_STATIC_FORCE_INLINE
void* c_PtrLinkBagIter_Next(c_PtrLinkBagIter_t* self) {
    if (!c_PtrLinkBagIter_HasNext(self)) return NULL;

    void* user_data = (*self->pp)->ptr;
    // 顺理成章地推进二级指针到当前节点的 next 域内存坑位地址上
    self->pp = &((*self->pp)->next);

    return user_data;
}

/**
 * @brief 极致防跑飞的 100% 内部自主闭环擦除接口 (完美免疫 SIGSEGV 段错误异常)
 */
C_STATIC_FORCE_INLINE
void c_PtrLinkBagIter_Remove(c_PtrLinkBagIter_t* self) {
    // 强御级边界拦截：粉碎一切高危越界或失效呼叫
    if (!c_PtrLinkBagIter_HasNext(self) || !self->bag) return;

    c_PtrLinkBag_t* host_bag = self->bag;

    // 1. 通过局部临时的栈变量把当前即将解体释放的单链表包装壳锁死
    c_PtrLinkNode_t* node_to_free = *self->pp;

    // 2. 二级指针惊绝裁剪：修改前驱 next 指针的值，令其直跳到目标节点的下一跳位置
    // 在修改的这一微秒内，*self->pp 天然等同并对齐到了新一任有效节点，迭代状态干净地自我康复
    *self->pp = node_to_free->next;

    // 3. 【内部自主化闭环】：利用宿主内置的 allocator，物理退还该节点外壳，干净利落
    c_Allocator_Free(&host_bag->allocator, node_to_free);

    // 4. 联动宿主袋子将计数器实时压减，做到账实相符
    host_bag->size--;
}

#endif /*INCLUDED_C_PTRLINKBAG_H*/