重构

Foundation/c_PtrLinkBag.h

@@ -5,58 +5,110 @@
 #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_PtrLinkBagNode_t {
+typedef struct c_PtrLinkNode_t {
     void* ptr;
-    struct c_PtrLinkBagNode_t* next;
-}c_PtrLinkBagNode_t;
+    struct c_PtrLinkNode_t* next;
+}c_PtrLinkNode_t;
 
 typedef struct {
-    c_PtrLinkBagNode_t* head;
+    c_PtrLinkNode_t* head;
+    c_size_t size;
+    c_Allocator_t allocator;
 }c_PtrLinkBag_t;
 
 typedef struct {
-    c_PtrLinkBag_t* bag;
-    c_PtrLinkBagNode_t** node;
-}c_PtrLinkBagIter_t;
+    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);
+/* ------------------------------------------------------------------------------------------------------------------ */
+/*  */
 
-void c_PtrLinkBag_Destroy(c_PtrLinkBag_t* self);
+c_err_t          c_PtrLinkBag_Init(c_PtrLinkBag_t* self, c_Allocator_t* allocator);
+void             c_PtrLinkBag_Destroy(c_PtrLinkBag_t* self);
 
-c_err_t c_PtrLinkBag_Add(c_PtrLinkBag_t* self, void* item);
+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_err_t c_PtrLinkBag_Remove(c_PtrLinkBag_t* self, const void* item);
+// 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 || !bag) return;
+    if (!self) return;
     self->bag = bag;
-    self->node = &bag->head;
+    if (!bag || !bag->head) {
+        self->pp = NULL;
+        return;
+    }
+    // 二级指针初始死死咬定宿主 Dummy Head 内部的 next 指针域
+    self->pp = &(bag->head);
 }
 
 C_STATIC_FORCE_INLINE
-c_bool_t c_PtrLinkBagIter_HasNext(c_PtrLinkBagIter_t* self) {
-    if (!self) return C_FALSE;
-    return (self->node!=NULL) && (*(self->node)!=NULL);
-}
-
-C_STATIC_FORCE_INLINE
-void* c_PtrLinkBagIter_Next(c_PtrLinkBagIter_t* self) {
-    if (!self || !self->node) return NULL;
-    void* ptr = (*(self->node))->ptr;
-    self->node = &(*(self->node))->next;
-    return ptr;
+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 (!self || !self->node) return NULL;
-    return (*(self->node))->ptr;
+    if (!c_PtrLinkBagIter_HasNext(self)) return NULL;
+    return (*self->pp)->ptr; // 只读窥探数据，绝对不产生位移副作用
 }
 
-void c_PtrLinkBagIter_Remove(c_PtrLinkBagIter_t* self);
+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*/