cKit/Foundation/c_SmartPtr.h

#ifndef INCLUDED_C_SMARTPTR_H
#define INCLUDED_C_SMARTPTR_H

#ifndef INCLUDED_C_TYPES_H
#include <c_Types.h>
#endif /*INCLUDED_C_TYPES_H*/

#ifndef INCLUDED_C_ATOMIC_H
#include <c_Atomic.h>
#endif /*INCLUDED_C_ATOMIC_H*/

#ifndef INCLUDED_C_ALLOCATOR_H
#include <c_Allocator.h>
#endif /*INCLUDED_C_ALLOCATOR_H*/

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


// 釋放資源的函數指標類型
typedef void (*c_SmartPtrFreeFn_t)(void* ptr, void* args);

// 智慧指標結構體
typedef struct {
    void* ptr;
    c_SmartPtrFreeFn_t free_fn;
    void* args;
    c_atomic_int_t* ref_count;
    c_Allocator_t allocator;
} c_SmartPtr_t;

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


C_STATIC_FORCE_INLINE
c_err_t c_SmartPtr_Init(c_SmartPtr_t* self, void* ptr, const c_SmartPtrFreeFn_t free_fn, void* args, c_Allocator_t* allocator) {
    if (!self || ptr == NULL) return C_ERR_PARAM;

    // 內置自我管理宣告
    self->allocator = (allocator != NULL) ? *allocator : c_DefaultAllocator;
    self->ptr = ptr;
    self->free_fn = free_fn;
    self->args = args;

    // 從自己內嵌的多態記憶體管理器中為共享原子計數核申請空間，完全避免全域大堆抖動
    self->ref_count = (c_atomic_int_t*)c_Allocator_Alloc(&self->allocator, sizeof(c_atomic_int_t));
    if (self->ref_count == NULL) {
        return C_ERR_NOMEM;
    }

    c_atomic_init_int(self->ref_count, 1);
    return C_ERR_OK;
}


C_STATIC_FORCE_INLINE
c_SmartPtr_t c_SmartPtr_Make(void* ptr, const c_SmartPtrFreeFn_t free_fn, void* args, c_Allocator_t* allocator) {
    c_SmartPtr_t sptr = { .ptr = ptr, .free_fn = free_fn, .args = args, .ref_count = NULL, .allocator = c_DefaultAllocator };
    if (ptr == NULL) return sptr;
    c_SmartPtr_Init(&sptr, ptr, free_fn, args, allocator);
    return sptr;
}

C_STATIC_FORCE_INLINE
void c_SmartPtr_Destroy(c_SmartPtr_t* self) {
    if (!self || !self->ref_count) return;

    // 原子 FETCH_SUB 遞減計數。若返回 1，證明當前線程手握全宇宙最後一個所有權控制權
    if (C_ATOMIC_FETCH_SUB(self->ref_count, 1) == 1) {
        // ① 驅動用戶自定義的析構回呼，物理渡越火化業務物件
        if (self->free_fn && self->ptr) {
            self->free_fn(self->ptr, self->args);
        }
        // ② 【核心進化】：精準呼叫自身攜帶的多態管理器，火化回收共享計數核空間
        c_Allocator_Free(&self->allocator, self->ref_count);
    }

    // 乾淨原位抹零（包括內建的 allocator 同步抹除），防止 Use-After-Free 野指针高危
    memset(self, 0, sizeof(c_SmartPtr_t));
}

C_STATIC_FORCE_INLINE
c_err_t c_SmartPtr_Copy(c_SmartPtr_t* dest, const c_SmartPtr_t* src) {
    if (!dest || !src || dest == src) return C_ERR_PARAM;

    if (!src->ptr || !src->ref_count) {
        c_SmartPtr_Destroy(dest);
        return C_ERR_OK;
    }

    // ① 先安全解除接收器舊有的生命線
    c_SmartPtr_Destroy(dest);

    // ② 結構體拷貝：新克隆體直接承襲源頭的所有控制域，並【深度克隆繼承】其內嵌的多態分配器
    dest->ptr = src->ptr;
    dest->free_fn = src->free_fn;
    dest->args = src->args;
    dest->ref_count = src->ref_count;
    dest->allocator = src->allocator; // 分配器血脈賡續

    // ③ 原子級加一
    C_ATOMIC_FETCH_ADD(dest->ref_count, 1);
    return C_ERR_OK;
}

C_STATIC_FORCE_INLINE
c_err_t c_SmartPtr_Move(c_SmartPtr_t* dest, c_SmartPtr_t* src) {
    if (!dest || !src || dest == src) return C_ERR_PARAM;

    c_SmartPtr_Destroy(dest);
    *dest = *src;
    memset(src, 0, sizeof(c_SmartPtr_t));

    return C_ERR_OK;
}

C_STATIC_FORCE_INLINE
int c_SmartPtr_UseCount(const c_SmartPtr_t* self) {
    if (!self || !self->ref_count) return 0;
    return (int)C_ATOMIC_LOAD(self->ref_count);
}



#endif /*INCLUDED_C_SMARTPTR_H*/