PyCyBase 0.1.8.post4__cp313-cp313-win_amd64.whl

cbase/allocator_protocol/c_allocator_protocol.h

@@ -0,0 +1,352 @@
+#ifndef C_ALLOCATOR_PROTOCOL_H
+#define C_ALLOCATOR_PROTOCOL_H
+
+#include <stdatomic.h>
+#include <stdbool.h>
+#include <stdint.h>
+#include <stdio.h>
+#include <stdlib.h>
+
+#include <cbase/allocator_protocol/c_heap_allocator.h>
+
+#ifdef _WIN32
+#include <cbase/allocator_protocol/c_nt_shm_allocator.h>
+// Type aliases -- NT structs masquerade as POSIX names
+typedef nt_shm_allocator     shm_allocator;
+typedef nt_shm_allocator_ctx shm_allocator_ctx;
+typedef nt_shm_page          shm_page;
+typedef nt_shm_page_ctx      shm_page_ctx;
+typedef nt_shm_memory_block  shm_memory_block;
+// Function aliases -- NT implementations with identical signatures
+#define c_shm_allocator_new c_nt_shm_allocator_new
+#define c_shm_allocator_free c_nt_shm_allocator_free
+#define c_shm_request c_nt_shm_request
+#define c_shm_calloc c_nt_shm_calloc
+#define c_shm_free c_nt_shm_free
+#define c_shm_reclaim c_nt_shm_reclaim
+#else
+#include <cbase/allocator_protocol/c_shm_allocator.h>
+#endif
+
+// ========== Constants ==========
+
+#ifndef AP_ALLOC_VIGILANT
+#define AP_ALLOC_VIGILANT 1
+#endif
+
+#ifndef AP_ALLOC_MAGIC
+#define AP_ALLOC_MAGIC 0xCFBBBBFCULL
+#endif
+
+#ifndef AP_DEALLOC_MAGIC
+#define AP_DEALLOC_MAGIC 0xDEADDEADULL
+#endif
+
+#ifndef AP_DECREF_AUTOFREE
+#define AP_DECREF_AUTOFREE 1
+#endif
+
+#ifndef AP_ALLOC_WITH_LOCK
+#define AP_ALLOC_WITH_LOCK 1
+#endif
+
+#ifndef AP_ALLOC_WITH_SHM
+#define AP_ALLOC_WITH_SHM 0
+#endif
+
+#ifndef AP_ALLOC_WITH_FREELIST
+#define AP_ALLOC_WITH_FREELIST 1
+#endif
+
+// ========== Structs ==========
+
+typedef struct allocator_protocol {
+    shm_allocator*     shm_allocator;
+    shm_allocator_ctx* shm_allocator_ctx;
+    heap_allocator*    heap_allocator;
+    bool               with_lock;
+    bool               with_shm;
+    bool               with_freelist;
+    size_t             size;
+#if AP_ALLOC_VIGILANT > 0
+    uint64_t magic;
+#endif
+    _Atomic int64_t ref_count;
+    char            buf[];
+} allocator_protocol;
+
+// ========== Forward Declaration ==========
+
+static inline allocator_protocol* c_ap_allocator_protocol_new(size_t size, shm_allocator_ctx* shm_allocator, heap_allocator* heap_allocator, bool with_lock);
+static inline void                c_ap_allocator_protocol_free(allocator_protocol* protocol);
+static inline int64_t             c_ap_allocator_protocol_acquire_owner(allocator_protocol* protocol);
+static inline int64_t             c_ap_allocator_protocol_release_owner(allocator_protocol* protocol);
+
+static inline allocator_protocol* c_ap_protocol_from_ptr(const void* ptr);
+static inline void*               c_ap_alloc(size_t size, allocator_protocol* schematic);
+static inline void                c_ap_free(void* ptr);
+static inline void                c_ap_incref(void* ptr);
+static inline void                c_ap_decref(void* ptr);
+static inline char*               c_ap_strdup(const char* src, allocator_protocol* allocator);
+static inline void*               c_ap_realloc(void* src, size_t new_size, allocator_protocol* allocator);
+static inline bool                c_ap_is_allocator_buf(const void* ptr);
+
+// ========== Utilities Functions ==========
+
+static inline allocator_protocol* c_ap_allocator_protocol_new(size_t size, shm_allocator_ctx* shm_allocator, heap_allocator* heap_allocator, bool with_lock) {
+    if (size == 0) return NULL;
+    size_t              ttl_size = sizeof(allocator_protocol) + size;
+    allocator_protocol* protocol;
+
+    if (shm_allocator) {
+        pthread_mutex_t* lock = with_lock ? &shm_allocator->shm_allocator->lock : NULL;
+        protocol = (allocator_protocol*) c_shm_request(shm_allocator, ttl_size, 0, lock);
+        if (!protocol) return NULL;
+        protocol->shm_allocator = shm_allocator->shm_allocator;
+        protocol->shm_allocator_ctx = shm_allocator;
+        protocol->with_lock = with_lock;
+        protocol->with_shm = true;
+    }
+    else if (heap_allocator) {
+        pthread_mutex_t* lock = with_lock ? &heap_allocator->lock : NULL;
+        protocol = (allocator_protocol*) c_heap_request(heap_allocator, ttl_size, 0, lock);
+        if (!protocol) return NULL;
+        protocol->heap_allocator = heap_allocator;
+        protocol->with_lock = with_lock;
+        protocol->with_freelist = true;
+    }
+    else {
+        protocol = (allocator_protocol*) calloc(1, ttl_size);
+        if (!protocol) return NULL;
+    }
+
+    protocol->with_lock = with_lock;
+    protocol->size = size;
+    // _new method DOES NOT manipulate ref_count! So as the _free method.
+    // atomic_store_explicit(&protocol->ref_count, 1, memory_order_release);
+
+#if AP_ALLOC_VIGILANT > 0
+    protocol->magic = AP_ALLOC_MAGIC;
+#endif
+
+    return protocol;
+}
+
+static inline void c_ap_allocator_protocol_free(allocator_protocol* protocol) {
+    if (!protocol) return;
+
+#if AP_ALLOC_VIGILANT > 0
+    // Invalidate magic to catch double free or invalid free attempts
+    protocol->magic = AP_DEALLOC_MAGIC;
+#endif
+    bool with_lock = protocol->with_lock;
+    bool with_shm = protocol->with_shm;
+    bool with_freelist = protocol->with_freelist;
+
+    // _free method DOES NOT manipulate ref_count! So as the _new method.
+    // atomic_store_explicit(&protocol->ref_count, 0, memory_order_release);
+
+    if (with_shm && with_freelist) {
+        fprintf(stderr, "[c_ap_allocator_protocol_free] ERROR: Protocol cannot have both with_shm and with_freelist set to true!\n");
+        abort();
+    }
+    else if (with_shm) {
+        shm_allocator*   shm_allocator = protocol->shm_allocator;
+        pthread_mutex_t* lock = with_lock ? &shm_allocator->lock : NULL;
+        c_shm_free((void*) protocol, lock);
+    }
+    else if (with_freelist) {
+        heap_allocator*  heap_allocator = protocol->heap_allocator;
+        pthread_mutex_t* lock = with_lock ? &heap_allocator->lock : NULL;
+        c_heap_free((void*) protocol, lock);
+    }
+    else {
+        free((void*) protocol);
+    }
+}
+
+static inline int64_t c_ap_allocator_protocol_acquire_owner(allocator_protocol* protocol) {
+    if (!protocol) return 0;
+    return atomic_fetch_add_explicit(&protocol->ref_count, 1, memory_order_acq_rel) + 1;
+}
+
+static inline int64_t c_ap_allocator_protocol_release_owner(allocator_protocol* protocol) {
+    if (!protocol) return 0;
+    return atomic_fetch_sub_explicit(&protocol->ref_count, 1, memory_order_acq_rel) - 1;
+}
+
+// ========== Public APIs ==========
+
+static inline allocator_protocol* c_ap_protocol_from_ptr(const void* ptr) {
+    if (!ptr) return NULL;
+    allocator_protocol* protocol = (allocator_protocol*) ((char*) ptr - offsetof(allocator_protocol, buf));
+#if AP_ALLOC_VIGILANT > 0
+    if (protocol->magic != AP_ALLOC_MAGIC) {
+        if (protocol->magic == AP_DEALLOC_MAGIC) {
+            fprintf(stderr, "[AP_ALLOC_VIGILANT] ERROR: Use-after-free detected in c_ap_protocol_from_ptr!\n");
+            fprintf(stderr, "[AP_ALLOC_VIGILANT] Pointer %p was already freed (dealloc magic: 0x%llx).\n", ptr, (unsigned long long) AP_DEALLOC_MAGIC);
+        }
+        else {
+            fprintf(stderr, "[AP_ALLOC_VIGILANT] ERROR: Magic mismatch in c_ap_protocol_from_ptr! Not an ap-allocated pointer!\n");
+            fprintf(stderr, "[AP_ALLOC_VIGILANT] Expected: 0x%llx, Got: 0x%llx\n", (unsigned long long) AP_ALLOC_MAGIC, (unsigned long long) protocol->magic);
+            fprintf(stderr, "[AP_ALLOC_VIGILANT] This is likely a raw malloc / calloc'd pointer.\n");
+        }
+        fflush(stderr);
+        abort();
+    }
+#endif
+
+    return protocol;
+}
+
+static inline void* c_ap_alloc(size_t size, allocator_protocol* schematic) {
+    allocator_protocol* clone;
+
+    if (!schematic) {
+        clone = (allocator_protocol*) calloc(1, sizeof(allocator_protocol) + size);
+        if (!clone) return NULL;
+        clone->size = size;
+        atomic_store_explicit(&clone->ref_count, 1, memory_order_release);
+#if AP_ALLOC_VIGILANT > 0
+        clone->magic = AP_ALLOC_MAGIC;
+#endif
+        return (void*) clone->buf;
+    }
+
+    if (schematic->with_shm) {
+        bool               with_lock = schematic->with_lock;
+        shm_allocator_ctx* ctx = schematic->shm_allocator_ctx;
+        shm_allocator*     allocator = schematic->shm_allocator;
+        pthread_mutex_t*   lock = with_lock ? &allocator->lock : NULL;
+        clone = (allocator_protocol*) c_shm_request(ctx, sizeof(allocator_protocol) + size, 0, lock);
+        if (!clone) return NULL;
+        clone->shm_allocator = allocator;
+        clone->shm_allocator_ctx = ctx;
+        clone->with_lock = with_lock;
+        clone->with_shm = 1;
+    }
+    else if (schematic->with_freelist) {
+        bool             with_lock = schematic->with_lock;
+        heap_allocator*  allocator = schematic->heap_allocator;
+        pthread_mutex_t* lock = with_lock ? &allocator->lock : NULL;
+        clone = (allocator_protocol*) c_heap_request(allocator, sizeof(allocator_protocol) + size, 0, lock);
+        if (!clone) return NULL;
+        clone->heap_allocator = allocator;
+        clone->with_lock = with_lock;
+        clone->with_freelist = 1;
+    }
+    else {
+        clone = (allocator_protocol*) calloc(1, sizeof(allocator_protocol) + size);
+        if (!clone) return NULL;
+    }
+
+    clone->with_lock = schematic->with_lock;
+    clone->size = size;
+    atomic_store_explicit(&clone->ref_count, 1, memory_order_release);
+#if AP_ALLOC_VIGILANT > 0
+    clone->magic = AP_ALLOC_MAGIC;
+#endif
+    return (void*) clone->buf;
+}
+
+static inline void c_ap_free(void* ptr) {
+    if (!ptr) return;
+    allocator_protocol* protocol = c_ap_protocol_from_ptr(ptr);
+
+#if AP_ALLOC_VIGILANT > 0
+    if (protocol->magic != AP_ALLOC_MAGIC) {
+        if (protocol->magic == AP_DEALLOC_MAGIC) {
+            fprintf(stderr, "[AP_ALLOC_VIGILANT] ERROR: Double free detected in c_ap_free!\n");
+            fprintf(stderr, "[AP_ALLOC_VIGILANT] Pointer %p was already freed (dealloc magic: 0x%llx).\n", ptr, (unsigned long long) AP_DEALLOC_MAGIC);
+        }
+        else {
+            fprintf(stderr, "[AP_ALLOC_VIGILANT] ERROR: Magic mismatch in c_ap_free! Not an ap-allocated pointer!\n");
+            fprintf(stderr, "[AP_ALLOC_VIGILANT] Expected: 0x%llx, Got: 0x%llx\n", (unsigned long long) AP_ALLOC_MAGIC, (unsigned long long) protocol->magic);
+            fprintf(stderr, "[AP_ALLOC_VIGILANT] This is likely a raw malloc / calloc'd pointer.\n");
+        }
+        fflush(stderr);
+        abort();
+    }
+
+    if (atomic_load_explicit(&protocol->ref_count, memory_order_acquire) > 1) {
+        fprintf(stderr, "[AP_ALLOC_VIGILANT] ERROR: c_ap_free is not allowed while buffer is shared (ref_count>1)!\n");
+        fflush(stderr);
+        abort();
+    }
+#endif
+
+    atomic_store_explicit(&protocol->ref_count, 0, memory_order_release);
+    c_ap_allocator_protocol_free(protocol);
+}
+
+static inline void c_ap_incref(void* ptr) {
+    if (!ptr) return;
+    allocator_protocol* protocol = c_ap_protocol_from_ptr(ptr);
+    int64_t             ref_count = c_ap_allocator_protocol_acquire_owner(protocol);
+
+#if AP_ALLOC_VIGILANT > 0
+    if (ref_count <= 1) {
+        fprintf(stderr, "[AP_ALLOC_VIGILANT] ERROR: incref on non-owned allocator protocol (new_ref_count=%lld)!\n", (long long) ref_count);
+        fflush(stderr);
+        abort();
+    }
+#endif
+}
+
+static inline void c_ap_decref(void* ptr) {
+    if (!ptr) return;
+    allocator_protocol* protocol = c_ap_protocol_from_ptr(ptr);
+    int64_t             ref_count = c_ap_allocator_protocol_release_owner(protocol);
+
+#if AP_ALLOC_VIGILANT > 0
+    if (ref_count < 0) {
+        fprintf(stderr, "[AP_ALLOC_VIGILANT] ERROR: decref on unowned allocator protocol (new_ref_count=%lld)!\n", (long long) ref_count);
+        fflush(stderr);
+        abort();
+    }
+#endif
+
+#if AP_DECREF_AUTOFREE > 0
+    if (ref_count == 0) {
+        c_ap_allocator_protocol_free(protocol);
+    }
+#endif
+}
+
+static inline char* c_ap_strdup(const char* src, allocator_protocol* allocator) {
+    if (!src) return NULL;
+    size_t len = strlen(src);
+    char*  trg = (char*) c_ap_alloc(len + 1, allocator);
+    if (!trg) return NULL;
+    memcpy(trg, src, len);
+    return trg;
+}
+
+static inline void* c_ap_realloc(void* src, size_t new_size, allocator_protocol* allocator) {
+    if (!src) return c_ap_alloc(new_size, allocator);
+    if (new_size == 0) {
+        c_ap_free(src);
+        return NULL;
+    }
+
+    allocator_protocol* protocol = c_ap_protocol_from_ptr(src);
+    size_t              copy_size = protocol->size < new_size ? protocol->size : new_size;
+    void*               new_ptr = c_ap_alloc(new_size, allocator);
+    if (!new_ptr) return NULL;
+    memcpy(new_ptr, src, copy_size);
+    c_ap_free(src);
+    return new_ptr;
+}
+
+static inline bool c_ap_is_allocator_buf(const void* ptr) {
+    if (!ptr) return false;
+#if AP_ALLOC_VIGILANT > 0
+    allocator_protocol* protocol = (allocator_protocol*) ((char*) ptr - offsetof(allocator_protocol, buf));
+    return protocol->magic == AP_ALLOC_MAGIC;
+#else
+    (void) ptr;
+    return true;
+#endif
+}
+
+#endif /* C_ALLOCATOR_PROTOCOL_H */

cbase/allocator_protocol/c_allocator_protocol.pxd

@@ -0,0 +1,64 @@
+from libc.stdint cimport int64_t, uint64_t, uint8_t
+from libcpp cimport bool as c_bool
+
+from cbase.env cimport EnvConfigContext
+
+from .c_heap_allocator cimport heap_allocator as heap_allocator_t
+from .c_shm_comp cimport shm_allocator as shm_allocator_t, shm_allocator_ctx as shm_allocator_ctx_t
+
+
+cdef extern from "cbase/allocator_protocol/c_allocator_protocol.h":
+    const uint8_t AP_ALLOC_VIGILANT
+    const uint64_t AP_ALLOC_MAGIC
+    const c_bool AP_ALLOC_WITH_LOCK
+    const c_bool AP_ALLOC_WITH_SHM
+    const c_bool AP_ALLOC_WITH_FREELIST
+
+    ctypedef struct allocator_protocol:
+        shm_allocator_t* shm_allocator
+        shm_allocator_ctx_t* shm_allocator_ctx
+        heap_allocator_t* heap_allocator
+        c_bool with_lock
+        c_bool with_shm
+        c_bool with_freelist
+        size_t size
+        uint64_t magic
+        int64_t ref_count
+        char buf[]
+
+    allocator_protocol* c_ap_allocator_protocol_new(size_t size, shm_allocator_ctx_t* shm_allocator, heap_allocator_t* heap_allocator, c_bool with_lock) noexcept nogil
+    void c_ap_allocator_protocol_free(allocator_protocol* protocol) noexcept nogil
+    int64_t c_ap_allocator_protocol_acquire_owner(allocator_protocol* protocol) noexcept nogil
+    int64_t c_ap_allocator_protocol_release_owner(allocator_protocol* protocol) noexcept nogil
+
+    allocator_protocol* c_ap_protocol_from_ptr(const void* ptr) noexcept nogil
+    void* c_ap_alloc(size_t size, allocator_protocol* schematic) noexcept nogil
+    void c_ap_free(void* ptr) noexcept nogil
+    void c_ap_incref(void* ptr) noexcept nogil
+    void c_ap_decref(void* ptr) noexcept nogil
+    char* c_ap_strdup(const char* src, allocator_protocol* allocator) noexcept nogil
+    void* c_ap_realloc(void* src, size_t new_size, allocator_protocol* allocator) noexcept nogil
+    c_bool c_ap_is_allocator_buf(const void* ptr) noexcept nogil
+
+
+cdef class AllocatorConfigContext(EnvConfigContext):
+    cdef allocator_protocol* allocator_schematic
+
+    cdef void c_bind(self, allocator_protocol* schematic=?)
+
+
+cdef class AllocatorProtocol:
+    cdef allocator_protocol* protocol
+
+    @staticmethod
+    cdef AllocatorProtocol c_from_protocol(allocator_protocol* protocol)
+
+
+cdef allocator_protocol* AP_DEFAULT_ALLOCATOR
+cdef allocator_protocol* AP_SHM_ALLOCATOR
+cdef allocator_protocol* AP_HEAP_ALLOCATOR
+
+cdef AllocatorConfigContext AP_SHARED
+cdef AllocatorConfigContext AP_LOCKED
+cdef AllocatorConfigContext AP_LOCKFREE
+cdef AllocatorConfigContext AP_FREELIST

cbase/allocator_protocol/c_allocator_protocol.pyi

@@ -0,0 +1,144 @@
+from typing import Any
+
+from cbase.env import EnvConfigContext
+
+
+class AllocatorConfigContext(EnvConfigContext):
+    """Context manager that extends EnvConfigContext to also dispatch config
+    changes to the underlying heap and shared-memory allocators.
+
+    Accepted keyword arguments (in addition to those inherited):
+
+    * ``locked: bool`` — enable/disable mutex locking
+    * ``shared: bool`` — enable/disable shared memory
+    * ``freelist: bool`` — enable/disable free list
+    * ``autopage_capacity: int`` — propagated to both heap and SHM allocators
+    * ``autopage_capacity_max: int`` — propagated to both heap and SHM allocators
+    * ``autopage_alignment: int`` — propagated to both heap and SHM allocators
+    """
+
+    def __init__(self, **kwargs: Any) -> None:
+        """
+        Initialize the context with configuration changes.
+
+        Args:
+            **kwargs: Configuration key-value pairs to set temporarily
+        """
+        ...
+
+    def __or__(self, other: AllocatorConfigContext) -> AllocatorConfigContext:
+        """
+        Combine two AllocatorConfigContext instances.
+
+        Args:
+            other: Another AllocatorConfigContext instance
+
+        Returns:
+            A new AllocatorConfigContext with combined configurations
+        """
+        ...
+
+    def __invert__(self) -> AllocatorConfigContext:
+        """
+        Invert the AllocatorConfigContext.
+
+        Returns:
+            A new AllocatorConfigContext that reverts the configurations.
+        """
+        ...
+
+
+AP_SHARED: AllocatorConfigContext
+"""
+AllocatorConfigContext instance to set flag for cbase to use SHM allocator.
+"""
+
+AP_LOCKED: AllocatorConfigContext
+"""
+AllocatorConfigContext instance to set flag for cbase to use thread safe mode.
+"""
+
+AP_LOCKFREE: AllocatorConfigContext
+"""
+AllocatorConfigContext instance to set flag for cbase to disable thread safe mode.
+"""
+
+AP_FREELIST: AllocatorConfigContext
+"""
+AllocatorConfigContext instance to set flag for cbase to use freelist. Have no effect when in AP_SHARED mode, which enforces its own free list.
+"""
+
+
+class AllocatorProtocol:
+    """Protocol for memory allocation with environment-based configuration.
+
+    Manages an underlying `allocator_protocol` C structure, handling memory
+    allocation and deallocation based on global environment settings.
+
+    Attributes:
+        protocol: **cython internal** Pointer to the underlying `allocator_protocol` C structure.
+        owner: **cython internal** Boolean indicating if this instance owns the protocol and is
+            responsible for its deallocation.
+    """
+
+    def __init__(self, size: int) -> None:
+        """Initialize the AllocatorProtocol with a specified buffer size.
+
+        Args:
+            size: The size of the buffer to allocate in bytes.
+        """
+        ...
+
+    @property
+    def buf(self) -> memoryview:
+        """Memory buffer managed by this allocator protocol.
+
+        Returns:
+            A memoryview representing the allocated buffer.
+        """
+        ...
+
+    @property
+    def size(self) -> int:
+        """Size of the allocated buffer.
+
+        Returns:
+            The size of the buffer in bytes.
+        """
+        ...
+
+    @property
+    def with_shm(self) -> bool:
+        """Indicates if the allocator uses shared memory.
+
+        Returns:
+            True if shared memory is used, False otherwise.
+        """
+        ...
+
+    @property
+    def with_lock(self) -> bool:
+        """Indicates if the allocator uses locking for thread safety.
+
+        Returns:
+            True if locking is enabled, False otherwise.
+        """
+        ...
+
+    @property
+    def with_freelist(self) -> bool:
+        """Indicates if the allocator uses a free list.
+
+        Returns:
+            True if free list is enabled, False otherwise.
+        """
+        ...
+
+    @property
+    def addr(self) -> int:
+        """Memory address of the underlying allocator protocol structure.
+
+        Returns:
+            The memory address as an integer.
+        """
+        ...