重构

Foundation/c_ArrayList.t.c

@@ -3,154 +3,250 @@
 #include <stdio.h>
 #include <c_Test.h>
 
-struct Vector2D {
-    double u, v;
-};
+/* ------------------------------------------------------------------------------------------------------------------ */
+/*  */
 
-/* ==============================================================================
- * 🧪 测试全新通用 void* 缓冲区的初始化、自动扩容与随机 Remove 重排全周期行为
- * ============================================================================== */
-TEST_CASE(test_array_list_full_lifecycle_and_removal)
-{
+typedef struct {
+    size_t active_allocations;
+    size_t total_alloc_bytes;
+    size_t total_free_bytes;
+    size_t realloc_calls;
+    size_t realloc_in_place_count; // 记录有多少次 Realloc 实现了就地复用（模拟伙伴系统）
+} TestMemoryTracker_t;
+
+static TestMemoryTracker_t g_tracker = {0};
+
+static size_t mock_buddy_power_of_two(size_t size) {
+    if (size == 0) return 0;
+    size_t p = 1;
+    while (p < size) p <<= 1;
+    return p;
+}
+
+static void* test_alloc(size_t size, void* ctx) {
+    TestMemoryTracker_t* tracker = (TestMemoryTracker_t*)ctx;
+    if (tracker) {
+        tracker->active_allocations++;
+        tracker->total_alloc_bytes += size;
+    }
+    return malloc(size);
+}
+static void test_free(void* ptr, void* ctx) {
+    TestMemoryTracker_t* tracker = (TestMemoryTracker_t*)ctx;
+    if (ptr && tracker) {
+        tracker->active_allocations--;
+    }
+    free(ptr);
+}
+
+static void* test_realloc(void* ptr, size_t old_size, size_t new_size, void* ctx) {
+    TestMemoryTracker_t* tracker = (TestMemoryTracker_t*)ctx;
+    if (tracker) tracker->realloc_calls++;
+
+    if (new_size == 0) {
+        test_free(ptr, ctx);
+        if (tracker) tracker->total_free_bytes += old_size;
+        return NULL;
+    }
+
+    if (!ptr) {
+        return test_alloc(new_size, ctx);
+    }
+
+    // 【模拟伙伴系统核心逻辑】：如果新旧大小落在同一个 2 的幂阶数区间，则直接原地返回，零搬迁！
+    size_t old_buddy = mock_buddy_power_of_two(old_size);
+    size_t new_buddy = mock_buddy_power_of_two(new_size);
+
+    if (old_buddy == new_buddy && old_buddy != 0) {
+        if (tracker) tracker->realloc_in_place_count++;
+        return ptr;
+    }
+
+    // 阶数改变，模拟搬迁
+    void* new_ptr = malloc(new_size);
+    if (!new_ptr) return NULL;
+
+    size_t copy_size = (old_size < new_size) ? old_size : new_size;
+    memcpy(new_ptr, ptr, copy_size);
+    free(ptr);
+
+    if (tracker) {
+        tracker->total_alloc_bytes += new_size;
+        tracker->total_free_bytes += old_size;
+    }
+    return new_ptr;
+}
+
+/* ------------------------------------------------------------------------------------------------------------------ */
+/*  */
+
+// 供 RUN_TEST_FIXTURE 使用的 Setup 和 Teardown 钩子
+static void custom_allocator_setup(void) {
+    memset(&g_tracker, 0, sizeof(TestMemoryTracker_t));
+}
+
+static void custom_allocator_teardown(void) {
+    // 每次测试结束，严格确保没有发生内存泄漏
+    // 注意：不能在此处直接调用带有返回的断言，因为破坏了测试函数的封装，仅在内部测试中做二次校验或由测试用例本身断言。
+}
+
+
+/* ------------------------------------------------------------------------------------------------------------------ */
+/*  */
+
+typedef struct {
+    int node_id;
+    float threshold;
+    char name[16];
+} SensorNode_t;
+
+/* ------------------------------------------------------------------------------------------------------------------ */
+/*  */
+
+// 测试一：基础生命周期与边界防御测试
+TEST_CASE(test_lifecycle_and_defense) {
     c_ArrayList_t list;
-    /* 1. 初始化：装载自定义 Vector2D 结构体，初始最大可容纳元素数量卡死限制为 2 */
-    c_err_t init_err = c_ArrayList_Init(&list, sizeof(struct Vector2D), 2);
-    ASSERT_INT_EQ_MSG(init_err, C_ERR_OK, "弹性自愈 ArrayList 初始化成功");
-    ASSERT_INT_EQ_MSG(list.size, 0, "有效初始记录必须为 0");
 
-    struct Vector2D vec1 = { 11.1, 22.2 };
-    struct Vector2D vec2 = { 33.3, 44.4 };
-    struct Vector2D vec3 = { 55.5, 66.6 };
+    // 防御测试：无效参数传入
+    ASSERT_INT_EQ_MSG(C_ERR_PARAM, c_ArrayList_Init(NULL, sizeof(int), 4, NULL), "Should return C_ERR_PARAM when self is NULL");
+    ASSERT_INT_EQ_MSG(C_ERR_PARAM, c_ArrayList_Init(&list, 0, 4, NULL), "Should return C_ERR_PARAM when item_size is 0");
+    ASSERT_INT_EQ(0, c_ArrayList_Size(NULL));
 
-    /* 2. 连续推入数据 */
-    c_ArrayList_Add(&list, &vec1);
-    c_ArrayList_Add(&list, &vec2);
+    // 正常原地初始化
+    c_err_t err = c_ArrayList_Init(&list, sizeof(int), 5, NULL);
+    ASSERT_INT_EQ(C_SUCCESS, err);
+    ASSERT_INT_EQ(0, c_ArrayList_Size(&list));
+    ASSERT_INT_EQ(5, list.capacity);
+    ASSERT_PTR_NOT_NULL(list.array);
 
-    /* 🎯 扩容看点：此时满员，第三次写入将强行逼迫池子在内部启动 2 -> 4 自动翻倍重分配 */
-    c_err_t add_err = c_ArrayList_Add(&list, &vec3);
-    ASSERT_INT_EQ_MSG(add_err, C_ERR_OK, "耗尽时追加写入，分配器必须完成全自动无感自愈扩容");
-    ASSERT_INT_EQ_MSG(list.size, 3, "当前有效装载数递增至 3");
+    // 销毁幂等性与清除检查
+    c_ArrayList_Destroy(&list);
+    ASSERT_TRUE(list.array == NULL);
+    ASSERT_INT_EQ(0, list.capacity);
+    ASSERT_INT_EQ(0, list.size);
 
-    /* 3. 验证数据内容的物理隔离完整度 */
-    struct Vector2D* p_check1 = (struct Vector2D*)c_ArrayList_Get(&list, 1);
-    ASSERT_MSG(p_check1 != NULL, "随机读取索引 1 节点成功");
-    ASSERT_DOUBLE_EQ_MSG(p_check1->u, 33.3, "重分配内存迁移后，原有位置 1 的数据必须毫发无损");
+    c_ArrayList_Destroy(&list); // 重复销毁不应崩溃
+}
 
-    /* 4. 🛠️ 高能测试点：随机抹除中间位置 1 的节点 (即删掉 vec2)
-       预期结果：原位置 2 的 vec3 ({55.5, 66.6}) 必须在 O(N) 速度下向前平移，填补顶替空位 1 */
-    c_err_t remove_err = c_ArrayList_Remove(&list, 1);
-    ASSERT_INT_EQ_MSG(remove_err, C_ERR_OK, "执行中途位置随机移除成功");
-    ASSERT_INT_EQ_MSG(list.size, 2, "移除数据后，有效数据计数平滑扣减为 2");
+// 测试二：泛型值复制存储、安全 Read/Get 访问测试
+TEST_CASE(test_value_copy_and_access) {
+    c_ArrayList_t list;
+    c_ArrayList_Init(&list, sizeof(SensorNode_t), 2, NULL);
 
-    /* 5. 终极完整性断言：现在去 Get 原本的位置 1 */
-    struct Vector2D* p_relocated = (struct Vector2D*)c_ArrayList_Get(&list, 1);
-    ASSERT_MSG(p_relocated != NULL, "重新获取平移顶替后的位置 1 节点成功");
+    SensorNode_t node1 = { .node_id = 101, .threshold = 45.2f, .name = "Temp01" };
+    SensorNode_t node2 = { .node_id = 102, .threshold = 12.8f, .name = "Humid02" };
 
-    /* 核心断言：原位置 2 的数据现在必须完美出现在位置 1 线上，且精度不发生移位错乱！ */
-    ASSERT_DOUBLE_EQ_MSG(p_relocated->u, 55.5, "元素向前滑动对齐后，浮点特征完好无损");
-    ASSERT_DOUBLE_EQ_MSG(p_relocated->v, 66.6, "元素向前滑动对齐后，浮点特征完好无损");
+    // 写入测试
+    ASSERT_INT_EQ(C_SUCCESS, c_ArrayList_Add(&list, &node1));
+    ASSERT_INT_EQ(C_SUCCESS, c_ArrayList_Add(&list, &node2));
+    ASSERT_INT_EQ(2, c_ArrayList_Size(&list));
 
-    /* 6. 边界越界捕获安全防御线 */
-    void* invalid_ptr = c_ArrayList_Get(&list, 2); /* 此时由于删了一个，索引 2 已变为空旷越界区 */
-    ASSERT_MSG(invalid_ptr == NULL, "越界获取已经被逻辑截断删除的位置必须安全回传 NULL");
+    // 强隔离隔离性检查：修改外部临时变量，内部数据不应被污染
+    node1.node_id = 999;
+
+    // 1. 测试 c_ArrayList_Read 拷出副本能力
+    SensorNode_t read_buffer;
+    ASSERT_INT_EQ(C_SUCCESS, c_ArrayList_Read(&list, 0, &read_buffer));
+    ASSERT_INT_EQ(101, read_buffer.node_id); // 应该依旧是原值 101
+    ASSERT_DOUBLE_EQ_MSG(45.2f, read_buffer.threshold, "Float precision checking");
+    ASSERT_TRUE(strcmp(read_buffer.name, "Temp01") == 0);
+
+    // 2. 测试 c_ArrayList_Get 直接指针读取能力
+    SensorNode_t* direct_ptr = (SensorNode_t*)c_ArrayList_Get(&list, 1);
+    ASSERT_PTR_NOT_NULL(direct_ptr);
+    ASSERT_INT_EQ(102, direct_ptr->node_id);
+
+    // 3. 越界保护检查
+    ASSERT_INT_EQ(C_ERR_PARAM, c_ArrayList_Read(&list, 2, &read_buffer));
+    ASSERT_TRUE(c_ArrayList_Get(&list, 5) == NULL);
 
     c_ArrayList_Destroy(&list);
 }
 
-static void test_list_auto_expansion() {
-    int data[] = {10, 20, 30};
+// 测试三：高危内存移动（memmove）及 Remove 位移正确性测试
+TEST_CASE(test_element_removal_and_shifting) {
     c_ArrayList_t list;
-    c_ArrayList_Init(&list, sizeof(int), 2);
+    c_ArrayList_Init(&list, sizeof(int), 5, NULL);
 
-    for (int i = 0; i < 3; i++) {
-        c_ArrayList_Add(&list, &data[i]);
+    int values[] = {10, 20, 30, 40, 50};
+    for(int i = 0; i < 5; i++) {
+        c_ArrayList_Add(&list, &values[i]);
     }
 
-    // 验证容量是否翻倍 (2 << 1 = 4)
-    ASSERT_INT_EQ_MSG(4, list.capacity, "Capacity should double to 4");
-    ASSERT_INT_EQ_MSG(3, list.size, "Size should be 3");
+    // 移除中间的数字 30 (索引 2) 并精准接住拷出值
+    int removed_val = 0;
+    ASSERT_INT_EQ(C_ERR_OK, c_ArrayList_Remove(&list, 2, &removed_val));
+    ASSERT_INT_EQ(30, removed_val);
+    ASSERT_INT_EQ(4, c_ArrayList_Size(&list));
 
-    // 验证最后一个元素有没有因为扩容导致内存搬移出错
-    int* p3 = (int*)c_ArrayList_Get(&list, 2);
-    ASSERT_MSG(p3 != NULL, "Expanded element should be accessible");
-    ASSERT_INT_EQ_MSG(30, *p3, "Expanded element data corruption");
+    // 极其严苛地检测后面所有元素的向前位移是否对齐正确
+    ASSERT_INT_EQ(10, *(int*)c_ArrayList_Get(&list, 0));
+    ASSERT_INT_EQ(20, *(int*)c_ArrayList_Get(&list, 1));
+    ASSERT_INT_EQ(40, *(int*)c_ArrayList_Get(&list, 2)); // 40 顶替了 30 的位置
+    ASSERT_INT_EQ(50, *(int*)c_ArrayList_Get(&list, 3)); // 50 顶替了 40 的位置
+
+    // 验证静默删除（out_item 为 NULL）
+    ASSERT_INT_EQ(C_SUCCESS, c_ArrayList_Remove(&list, 0, NULL));
+    ASSERT_INT_EQ(20, *(int*)c_ArrayList_Get(&list, 0)); // 20 变成了头元素
+
+    c_ArrayList_Destroy(&list);
 }
 
-static void test_list_remove_element() {
-    int data[] = {11, 22, 33, 44};
+// 测试四：挂载自定义分配器，并验证伙伴系统（Buddy System）的 O(1) 就地复用优化
+TEST_CASE(test_buddy_system_allocator_integration) {
+    c_Allocator_t buddy_allocator = {
+        .alloc = test_alloc,
+        .realloc = test_realloc,
+        .free = test_free,
+        .ud = &g_tracker
+    };
+
     c_ArrayList_t list;
-    c_ArrayList_Init(&list, sizeof(int), 2);
+    // 单个元素 8 字节，初始容量 2。整个缓冲区 = 2 * 8 = 16 字节
+    c_ArrayList_Init(&list, 8, 2, &buddy_allocator);
 
-    for(int i = 0; i < 4; i++) c_ArrayList_Add(&list, &data[i]);
+    // 验证 active_allocations 计数 (1控制头由调用者在栈分配，因此分配器内只有 1 个内部数据缓冲区 array)
+    ASSERT_INT_EQ(1, g_tracker.active_allocations);
 
-    // 删除索引为 1 的元素 (即数字 22)
-    c_err_t err = c_ArrayList_Remove(&list, 1);
-    ASSERT_INT_EQ_MSG(C_ERR_OK, err, "Remove operational failure");
-    ASSERT_INT_EQ_MSG(3, list.size, "Size should decrease to 3");
+    // 1. 显式调整容量从 2 -> 3
+    // 旧大小 16 字节 (2^4)，新大小 24 字节 (向上对齐到 2^5 = 32)，阶数改变，模拟真实搬迁
+    ASSERT_INT_EQ(C_SUCCESS, c_ArrayList_Resize(&list, 3));
+    ASSERT_INT_EQ(0, g_tracker.realloc_in_place_count); // 跨越了幂次墙，没有就地复用
 
-    // 此时索引 1 应该变成了 33，索引 2 应该变成了 44
-    int* p1 = (int*)c_ArrayList_Get(&list, 1);
-    int* p2 = (int*)c_ArrayList_Get(&list, 2);
+    // 2. 深度契合点：再次调整容量从 3 -> 4
+    // 旧大小 24 字节 (2^5 范围内)，新大小 32 字节 (刚好跨入 2^5 满额边界)
+    // 【期望结果】：落在同一阶数内，c_Buddy_Realloc 应当直接 O(1) 返回原指针！
+    ASSERT_INT_EQ(C_SUCCESS, c_ArrayList_Resize(&list, 4));
+    ASSERT_INT_EQ(1, g_tracker.realloc_in_place_count); // 完美！命中伙伴系统就地复用优化次数 1 次
 
-    ASSERT_INT_EQ_MSG(33, *p1, "Element forward-shift error at index 1");
-    ASSERT_INT_EQ_MSG(44, *p2, "Element forward-shift error at index 2");
+    // 3. 极限截断缩小到 0
+    ASSERT_INT_EQ(C_SUCCESS, c_ArrayList_Resize(&list, 0));
+    ASSERT_INT_EQ(0, c_ArrayList_Size(&list));
+    ASSERT_INT_EQ(0, list.capacity);
+    ASSERT_TRUE(list.array == NULL);
 
-    // 检查获取越界索引是否安全返回 NULL
-    ASSERT_MSG(c_ArrayList_Get(&list, 3) == NULL, "Out of bounds should return NULL");
+    c_ArrayList_Destroy(&list);
+
+    // 验证测试环境有没有发生任何内存泄漏
+    ASSERT_INT_EQ_MSG(0, g_tracker.active_allocations, "Memory leak detected inside allocator!");
 }
 
-static void test_list_zero_initial_capacity() {
-    c_ArrayList_t zero_list;
-    c_ArrayList_Init(&zero_list, sizeof(int), 0);
+/* ------------------------------------------------------------------------------------------------------------------ */
+/*  */
 
-    int val = 99;
-    // 如果你没有按照上方提示修复缺陷①，该断言将会失败（期望返回 OK 却返回了 PARAM 错误）
-    c_err_t err = c_ArrayList_Add(&zero_list, &val);
-    ASSERT_INT_EQ_MSG(C_ERR_OK, err, "Add failed when initial capacity is 0 (Bug ① Triggered!)");
+int main(int argc, char** argv){
 
-    c_ArrayList_Destroy(&zero_list);
-}
+    TEST_START(C_ArrayList_Module_Tests);
 
-static void test_list_auto_shrink() {
-    // 1. 连续添加 9 个元素触发扩容
-    // 初始化 0 -> 扩容到 4 -> 扩容到 8 -> 扩容到 16
-    c_ArrayList_t list;
-    c_ArrayList_Init(&list, sizeof(int), 2);
+    // 运行常规测试
+    RUN_TEST(test_lifecycle_and_defense);
+    RUN_TEST(test_value_copy_and_access);
+    RUN_TEST(test_element_removal_and_shifting);
 
-    for (int i = 0; i < 9; i++) {
-        c_ArrayList_Add(&list, &i);
-    }
-    ASSERT_INT_EQ_MSG(16, list.capacity, "Capacity should expand up to 16");
-
-    // 2. 依次删除元素，降低 size 以试图触发 1/4 缩容临界点
-    // 当 size 减少到 4 时 (即 16 / 4), 应该触发缩容：16 减半变成 8
-    for (int i = 0; i < 5; i++) {
-        c_ArrayList_Remove(&list, 0); // 总是移除首个元素
-    }
-
-    // 此时移除了 5 个，剩下 4 个元素
-    ASSERT_INT_EQ_MSG(4, list.size, "Current size should be 4");
-    ASSERT_INT_EQ_MSG(8, list.capacity, "Capacity should automatically shrink to 8");
-
-    // 3. 继续删除，观察是否会由于低于最小阈值(4)而停止缩容
-    for (int i = 0; i < 3; i++) {
-        c_ArrayList_Remove(&list, 0);
-    }
-    // 此时只剩 1 个元素了 (1 <= 8/4)，但由于 MIN_SHRINK_CAPACITY = 4 限制，容量不应该再减半到 2
-    ASSERT_INT_EQ_MSG(1, list.size, "Current size should be 1");
-    ASSERT_INT_EQ_MSG(2, list.capacity, "Capacity should hold at 2 to prevent thrashing");
-}
-
-int main(void) {
-    TEST_START(BaseArrayListNewSpecificationTestSuite);
-
-    RUN_TEST(test_array_list_full_lifecycle_and_removal);
-    RUN_TEST(test_list_auto_expansion);
-    RUN_TEST(test_list_remove_element);
-    RUN_TEST(test_list_zero_initial_capacity);
-    RUN_TEST(test_list_auto_shrink);
+    // 使用 Fixture 模式运行涉及自定义状态追踪的伙伴系统测试
+    RUN_TEST_FIXTURE(test_buddy_system_allocator_integration, custom_allocator_setup, custom_allocator_teardown);
 
     TEST_REPORT();
+
     RETURN_TEST_STATUS;
 }
-