PyCyBase 0.1.8.post4__cp313-cp313-win_amd64.whl

cbase/allocator_protocol/c_heap_allocator.h

@@ -0,0 +1,444 @@
+#ifndef AP_HEAP_C_HEAP_ALLOCATOR_H
+#define AP_HEAP_C_HEAP_ALLOCATOR_H
+
+#include <errno.h>
+#include <stddef.h>
+#include <stdint.h>
+#include <stdlib.h>
+#include <string.h>
+
+#ifdef _WIN32
+#include "cbase/nt/pthread_nt_compat.h"
+#else
+#include <pthread.h>
+#endif
+
+// ========== Configuration ==========
+
+#ifndef AP_HEAP_AUTOPAGE_CAPACITY
+#define AP_HEAP_AUTOPAGE_CAPACITY (64 * 1024) /* 64 KiB */
+#endif
+
+#ifndef AP_HEAP_AUTOPAGE_CAPACITY_MAX
+#define AP_HEAP_AUTOPAGE_CAPACITY_MAX (16 * 1024 * 1024) /* 16 MiB */
+#endif
+
+#ifndef AP_HEAP_AUTOPAGE_ALIGNMENT
+#define AP_HEAP_AUTOPAGE_ALIGNMENT (4 * 1024) /* 4 KiB */
+#endif
+
+// ========== Heap Allocator Structs ==========
+
+typedef struct heap_memory_block {
+    size_t                    capacity;
+    size_t                    size;
+    struct heap_memory_block* next_free;
+    struct heap_memory_block* next_allocated;
+    struct heap_page*         parent_page;
+    char                      buffer[];
+} heap_memory_block;
+
+typedef struct heap_page {
+    size_t                    capacity;
+    size_t                    occupied;
+    struct heap_allocator*    allocator;
+    struct heap_page*         prev;
+    struct heap_memory_block* allocated;
+    char                      buffer[];
+} heap_page;
+
+typedef struct heap_allocator {
+    pthread_mutex_t           lock;
+    size_t                    mapped_pages;
+    struct heap_memory_block* free_list;
+    struct heap_page*         active_page;
+    size_t                    autopage_capacity;
+    size_t                    autopage_capacity_max;
+    size_t                    autopage_alignment;
+} heap_allocator;
+
+// ========== Utility Functions ==========
+
+static inline size_t c_heap_page_roundup(heap_allocator* allocator, size_t size) {
+    return (size + allocator->autopage_alignment - 1) & ~(allocator->autopage_alignment - 1);
+}
+
+static inline size_t c_heap_block_roundup(size_t size) {
+    return (size + sizeof(void*) - 1) & ~(sizeof(void*) - 1);
+}
+
+static inline void c_heap_page_reclaim(heap_allocator* allocator, heap_page* page) {
+    if (!allocator || !page) {
+        errno = EINVAL;
+        return;
+    }
+
+    heap_memory_block** prevp = &page->allocated;
+    while (*prevp) {
+        heap_memory_block* block = *prevp;
+        if (block->size != 0) {
+            break;
+        }
+
+        *prevp = block->next_allocated;
+        block->next_allocated = NULL;
+
+        heap_memory_block** free_prev = &allocator->free_list;
+        while (*free_prev && *free_prev != block) {
+            free_prev = &(*free_prev)->next_free;
+        }
+        if (*free_prev == block) {
+            *free_prev = block->next_free;
+        }
+        block->next_free = NULL;
+
+        size_t cap_total = block->capacity + sizeof(heap_memory_block);
+        if (page->occupied >= cap_total) {
+            page->occupied -= cap_total;
+        }
+    }
+}
+
+// ========== Public API Functions ==========
+
+static inline heap_page* c_heap_allocator_extend(heap_allocator* allocator, size_t capacity, pthread_mutex_t* lock) {
+    if (!allocator) {
+        errno = EINVAL;
+        return NULL;
+    }
+
+    uint8_t locked = 0;
+
+    if (lock) {
+        int ret = pthread_mutex_lock(lock);
+        if (ret != 0) {
+            errno = ret;
+            return NULL;
+        }
+        locked = 1;
+    }
+
+    if (capacity == 0) {
+        if (!allocator->active_page) {
+            capacity = allocator->autopage_capacity;
+        }
+        else {
+            size_t prev_cap = allocator->active_page->capacity;
+            capacity = prev_cap * 2;
+            if (capacity < allocator->autopage_capacity) {
+                capacity = allocator->autopage_capacity;
+            }
+            else if (capacity > allocator->autopage_capacity_max) {
+                capacity = allocator->autopage_capacity_max;
+            }
+        }
+    }
+
+    size_t     total_capacity = c_heap_page_roundup(allocator, capacity);
+
+    heap_page* page = (heap_page*) calloc(1, total_capacity);
+
+    if (!page) {
+        if (locked) pthread_mutex_unlock(lock);
+        return NULL;
+    }
+
+    page->capacity = total_capacity;
+    page->occupied = sizeof(heap_page);
+    page->allocator = allocator;
+    page->allocated = NULL;
+    page->prev = allocator->active_page;
+    allocator->active_page = page;
+    allocator->mapped_pages++;
+
+    if (locked) pthread_mutex_unlock(lock);
+    return page;
+}
+
+static inline heap_allocator* c_heap_allocator_new() {
+    heap_allocator* allocator = (heap_allocator*) calloc(1, sizeof(heap_allocator));
+    if (!allocator) {
+        return NULL;
+    }
+
+    if (pthread_mutex_init(&allocator->lock, NULL) != 0) {
+        free(allocator);
+        return NULL;
+    }
+
+    allocator->mapped_pages = 0;
+    allocator->free_list = NULL;
+    allocator->active_page = NULL;
+    allocator->autopage_capacity = AP_HEAP_AUTOPAGE_CAPACITY;
+    allocator->autopage_capacity_max = AP_HEAP_AUTOPAGE_CAPACITY_MAX;
+    allocator->autopage_alignment = AP_HEAP_AUTOPAGE_ALIGNMENT;
+
+    return allocator;
+}
+
+static inline void c_heap_allocator_free(heap_allocator* allocator) {
+    if (!allocator) {
+        return;
+    }
+
+    heap_page* page = allocator->active_page;
+    while (page) {
+        heap_page* prev = page->prev;
+        free(page);
+        page = prev;
+    }
+
+    pthread_mutex_destroy(&allocator->lock);
+    free(allocator);
+}
+
+static inline void* c_heap_calloc(heap_allocator* allocator, size_t size, pthread_mutex_t* lock) {
+    if (!allocator || size == 0) {
+        errno = EINVAL;
+        return NULL;
+    }
+
+    size_t           cap_net = c_heap_block_roundup(size);
+    size_t           overhead = sizeof(heap_memory_block);
+    size_t           cap_total = cap_net + overhead;
+
+    uint8_t          locked = 0;
+    pthread_mutex_t* builtin_lock = &allocator->lock;
+    pthread_mutex_t* child_lock = &allocator->lock;
+    if (lock) {
+        if (lock == builtin_lock) {
+            child_lock = NULL;
+        }
+        int ret = pthread_mutex_lock(lock);
+        if (ret != 0) {
+            errno = ret;
+            return NULL;
+        }
+        locked = 1;
+    }
+    else {
+        child_lock = NULL;
+    }
+
+    heap_page* page = allocator->active_page;
+    if (!page) {
+        size_t target_cap = allocator->autopage_capacity;
+        while (target_cap < cap_total + sizeof(heap_page)) {
+            target_cap *= 2;
+        }
+
+        page = c_heap_allocator_extend(allocator, target_cap, child_lock);
+        if (!page) {
+            if (locked) pthread_mutex_unlock(lock);
+            return NULL;
+        }
+    }
+
+    if (page->occupied + cap_total > page->capacity) {
+        size_t target_cap = page->capacity;
+
+        if (target_cap < allocator->autopage_capacity) {
+            target_cap = allocator->autopage_capacity;
+        }
+        else if (target_cap < allocator->autopage_capacity_max) {
+            target_cap *= 2;
+        }
+
+        while (target_cap < cap_total + sizeof(heap_page)) {
+            target_cap *= 2;
+        }
+        page = c_heap_allocator_extend(allocator, target_cap, child_lock);
+        if (!page) {
+            if (locked) pthread_mutex_unlock(lock);
+            return NULL;
+        }
+    }
+
+    size_t             offset = page->occupied;
+    heap_memory_block* block = (heap_memory_block*) ((char*) page + offset);
+    block->capacity = cap_net;
+    block->size = size;
+    block->next_free = NULL;
+
+    block->parent_page = page;
+    block->next_allocated = page->allocated;
+    page->allocated = block;
+    page->occupied += cap_total;
+
+    if (locked) pthread_mutex_unlock(lock);
+
+    memset(block + 1, 0, cap_net);
+    return (void*) block->buffer;
+}
+
+static inline void* c_heap_request(heap_allocator* allocator, size_t size, int scan_all_pages, pthread_mutex_t* lock) {
+    if (!allocator || size == 0) {
+        errno = EINVAL;
+        return NULL;
+    }
+
+    size_t           cap_net = c_heap_block_roundup(size);
+    size_t           overhead = sizeof(heap_memory_block);
+    size_t           cap_total = cap_net + overhead;
+
+    uint8_t          locked = 0;
+    pthread_mutex_t* builtin_lock = &allocator->lock;
+    pthread_mutex_t* child_lock = &allocator->lock;
+    if (lock) {
+        if (lock == builtin_lock) {
+            child_lock = NULL;
+        }
+        int ret = pthread_mutex_lock(lock);
+        if (ret != 0) {
+            errno = ret;
+            return NULL;
+        }
+        locked = 1;
+    }
+    else {
+        child_lock = NULL;
+    }
+
+    heap_memory_block** prevp = &allocator->free_list;
+    heap_memory_block*  free_blk = allocator->free_list;
+    while (free_blk) {
+        if (free_blk->capacity >= cap_net) {
+            *prevp = free_blk->next_free;
+            free_blk->next_free = NULL;
+            free_blk->size = size;
+            if (locked) pthread_mutex_unlock(lock);
+            memset(free_blk + 1, 0, cap_net);
+            return (void*) free_blk->buffer;
+        }
+        prevp = &free_blk->next_free;
+        free_blk = free_blk->next_free;
+    }
+
+    heap_page* target_page = NULL;
+    if (scan_all_pages) {
+        heap_page* iter = allocator->active_page;
+        while (iter) {
+            if (iter->occupied + cap_total <= iter->capacity) {
+                target_page = iter;
+                break;
+            }
+            iter = iter->prev;
+        }
+    }
+    else if (allocator->active_page) {
+        heap_page* meta = allocator->active_page;
+        if (meta && meta->occupied + cap_total <= meta->capacity) {
+            target_page = allocator->active_page;
+        }
+    }
+
+    if (!target_page) {
+        heap_page* current = allocator->active_page;
+        size_t     target_cap;
+
+        if (!current) {
+            target_cap = allocator->autopage_capacity;
+            while (target_cap < cap_total + sizeof(heap_page)) {
+                target_cap *= 2;
+            }
+        }
+        else {
+            size_t prev_cap = current->capacity;
+            size_t new_cap = prev_cap;
+
+            if (new_cap < allocator->autopage_capacity) {
+                new_cap = allocator->autopage_capacity;
+            }
+            else if (new_cap < allocator->autopage_capacity_max) {
+                new_cap *= 2;
+            }
+
+            while (new_cap < cap_total + sizeof(heap_page)) {
+                new_cap *= 2;
+            }
+            target_cap = new_cap;
+        }
+
+        target_page = c_heap_allocator_extend(allocator, target_cap, child_lock);
+        if (!target_page) {
+            if (locked) pthread_mutex_unlock(lock);
+            return NULL;
+        }
+    }
+
+    size_t             offset = target_page->occupied;
+    heap_memory_block* block = (heap_memory_block*) ((char*) target_page + offset);
+    block->capacity = cap_net;
+    block->size = size;
+    block->next_free = NULL;
+
+    block->parent_page = target_page;
+    block->next_allocated = target_page->allocated;
+    target_page->allocated = block;
+
+    target_page->occupied += cap_total;
+
+    if (locked) pthread_mutex_unlock(lock);
+
+    memset(block + 1, 0, cap_net);
+    return (void*) block->buffer;
+}
+
+static inline void c_heap_free(void* ptr, pthread_mutex_t* lock) {
+    if (!ptr) {
+        errno = EINVAL;
+        return;
+    }
+
+    heap_memory_block* block = (heap_memory_block*) ((char*) ptr - sizeof(heap_memory_block));
+    heap_page*         page = block->parent_page;
+    if (!page || !page->allocator) {
+        errno = EINVAL;
+        return;
+    }
+
+    heap_allocator* allocator = page->allocator;
+
+    uint8_t         locked = 0;
+    if (lock) {
+        int ret = pthread_mutex_lock(lock);
+        if (ret != 0) {
+            errno = ret;
+            return;
+        }
+        locked = 1;
+    }
+
+    block->size = 0;
+    block->next_free = allocator->free_list;
+    allocator->free_list = block;
+
+    if (locked) pthread_mutex_unlock(lock);
+}
+
+static inline void c_heap_reclaim(heap_allocator* allocator, pthread_mutex_t* lock) {
+    if (!allocator) {
+        errno = EINVAL;
+        return;
+    }
+
+    uint8_t locked = 0;
+    if (lock) {
+        int ret = pthread_mutex_lock(lock);
+        if (ret != 0) {
+            errno = ret;
+            return;
+        }
+        locked = 1;
+    }
+
+    heap_page* page = allocator->active_page;
+    while (page) {
+        c_heap_page_reclaim(allocator, page);
+        page = page->prev;
+    }
+
+    if (locked) pthread_mutex_unlock(lock);
+}
+
+#endif /* AP_HEAP_C_HEAP_ALLOCATOR_H */

cbase/allocator_protocol/c_heap_allocator.pxd

@@ -0,0 +1,97 @@
+
+cdef extern from "cbase/allocator_protocol/c_heap_allocator.h":
+    const size_t AP_HEAP_AUTOPAGE_CAPACITY
+    const size_t AP_HEAP_AUTOPAGE_CAPACITY_MAX
+    const size_t AP_HEAP_AUTOPAGE_ALIGNMENT
+
+    ctypedef struct pthread_mutex_t:
+        pass
+
+    ctypedef struct heap_memory_block:
+        size_t capacity
+        size_t size
+        heap_memory_block* next_free
+        heap_memory_block* next_allocated
+        heap_page* parent_page
+        char buffer[]
+
+    ctypedef struct heap_page:
+        size_t capacity
+        size_t occupied
+        heap_allocator* allocator
+        heap_page* prev
+        heap_memory_block* allocated
+        char buffer[]
+
+    ctypedef struct heap_allocator:
+        pthread_mutex_t lock
+        size_t mapped_pages
+        heap_memory_block* free_list
+        heap_page* active_page
+        size_t autopage_capacity
+        size_t autopage_capacity_max
+        size_t autopage_alignment
+
+    int pthread_mutex_init(pthread_mutex_t* mutex, void* attr) noexcept nogil
+    int pthread_mutex_lock(pthread_mutex_t* mutex) noexcept nogil
+    int pthread_mutex_unlock(pthread_mutex_t* mutex) noexcept nogil
+    int pthread_mutex_destroy(pthread_mutex_t* mutex) noexcept nogil
+
+    size_t c_heap_page_roundup(heap_allocator* allocator, size_t size) noexcept nogil
+    size_t c_heap_block_roundup(size_t size) noexcept nogil
+    void c_heap_page_reclaim(heap_allocator* allocator, heap_page* page) noexcept nogil
+
+    heap_page* c_heap_allocator_extend(heap_allocator* allocator, size_t capacity, pthread_mutex_t* lock) noexcept nogil
+    heap_allocator* c_heap_allocator_new() noexcept nogil
+    void c_heap_allocator_free(heap_allocator* allocator) noexcept nogil
+    void* c_heap_calloc(heap_allocator* allocator, size_t size, pthread_mutex_t* lock) noexcept nogil
+    void* c_heap_request(heap_allocator* allocator, size_t size, int scan_all_pages, pthread_mutex_t* lock) noexcept nogil
+    void c_heap_free(void* ptr, pthread_mutex_t* lock) noexcept nogil
+    void c_heap_reclaim(heap_allocator* allocator, pthread_mutex_t* lock) noexcept nogil
+
+
+cdef class HeapMemoryPage:
+    cdef heap_page* page
+
+    @staticmethod
+    cdef inline HeapMemoryPage c_from_header(heap_page* header)
+
+    cpdef void reclaim(self)
+
+
+cdef class HeapMemoryBlock:
+    cdef heap_memory_block* block
+    cdef readonly bint owner
+
+    @staticmethod
+    cdef inline HeapMemoryBlock c_from_header(heap_memory_block* header, bint owner=?)
+
+
+cdef class HeapAllocator:
+    cdef heap_allocator* allocator
+    cdef readonly bint owner
+
+    @staticmethod
+    cdef HeapAllocator c_from_header(heap_allocator* header, bint owner=?)
+
+    cdef inline heap_page* c_extend(self, size_t capacity=?, pthread_mutex_t* lock=?)
+
+    cdef inline void* c_calloc(self, size_t size, pthread_mutex_t* lock=?)
+
+    cdef inline void* c_request(self, size_t size, int scan_all_pages=?, pthread_mutex_t* lock=?)
+
+    cdef inline void c_free(self, void* ptr, pthread_mutex_t* lock=?)
+
+    cpdef HeapMemoryPage extend(self, size_t capacity=?, bint with_lock=?)
+
+    cpdef HeapMemoryBlock calloc(self, size_t size, bint with_lock=?)
+
+    cpdef HeapMemoryBlock request(self, size_t size, bint with_lock=?, bint scan_all_pages=?)
+
+    cpdef void free(self, HeapMemoryBlock buffer, bint with_lock=?)
+
+    cpdef void reclaim(self, bint with_lock=?)
+
+
+cdef HeapAllocator ALLOCATOR
+cdef heap_allocator* C_ALLOCATOR

cbase/allocator_protocol/c_heap_allocator.pyi

@@ -0,0 +1,161 @@
+import ctypes
+from collections.abc import Generator
+from dataclasses import dataclass
+from typing import Annotated
+
+
+@dataclass
+class ValueRange:
+    lo: int
+    hi: int
+
+
+UINTPTR_MAX = ctypes.c_void_p(-1).value
+uintptr_t = Annotated[int, ValueRange(0, UINTPTR_MAX), ctypes.c_void_p]
+
+
+class HeapMemoryBlock:
+    """Typed wrapper around an allocator block header."""
+
+    owner: bool
+
+    def __init__(self, block: uintptr_t = 0, owner: bool = False) -> None: ...
+
+    def __repr__(self) -> str: ...
+
+    @property
+    def size(self) -> int:
+        """Requested payload size in bytes (-1 if uninitialized)."""
+
+    @property
+    def capacity(self) -> int:
+        """Aligned capacity of the block (-1 if uninitialized)."""
+
+    @property
+    def next_free(self) -> HeapMemoryBlock | None:
+        """Next entry in the allocator free list, if any."""
+
+    @property
+    def next_allocated(self) -> HeapMemoryBlock | None:
+        """Next entry in the owning page's allocation list, if any."""
+
+    @property
+    def parent_page(self) -> HeapMemoryPage | None:
+        """Owning page wrapper, or None when detached."""
+
+    @property
+    def buffer(self) -> memoryview:
+        """Memoryview of the user buffer."""
+
+    @property
+    def address(self) -> str | None:
+        """Hex string of the buffer address."""
+
+
+class HeapMemoryPage:
+    """Represents a single heap-managed page."""
+
+    def __init__(self, page_addr: uintptr_t = 0) -> None: ...
+
+    def __repr__(self) -> str: ...
+
+    @classmethod
+    def from_buffer(cls, buffer_addr: uintptr_t) -> HeapMemoryPage:
+        """Reconstruct a page wrapper from one of its block buffers."""
+
+    def allocated(self) -> Generator[HeapMemoryBlock]:
+        """Iterate allocated blocks newest-first."""
+
+    def reclaim(self) -> None:
+        """Best-effort reclaim of freed blocks back to unused space."""
+
+    @property
+    def capacity(self) -> int:
+        """Total payload capacity of the page in bytes."""
+
+    @property
+    def occupied(self) -> int:
+        """Currently occupied bytes on the page."""
+
+    @property
+    def address(self) -> str | None:
+        """Hex string of the page buffer address."""
+
+    @property
+    def allocator(self) -> HeapAllocator | None:
+        """Owning allocator wrapper, or None."""
+
+
+class HeapAllocator:
+    """Top-level heap allocator."""
+
+    owner: bool
+
+    def __init__(self) -> None: ...
+
+    def __repr__(self) -> str: ...
+
+    def extend(self, capacity: int = 0, with_lock: bool = True) -> HeapMemoryPage:
+        """Add a page (auto-sized when capacity is 0)."""
+
+    def calloc(self, size: int, with_lock: bool = True) -> HeapMemoryBlock:
+        """Allocate zeroed memory from the active page (auto-extending)."""
+
+    def request(
+            self,
+            size: int,
+            with_lock: bool = True,
+            scan_all_pages: bool = True,
+    ) -> HeapMemoryBlock:
+        """Request a zeroed block, optionally scanning older pages."""
+
+    def free(self, buffer: HeapMemoryBlock, with_lock: bool = True) -> None:
+        """Return a block to the allocator free list."""
+
+    def reclaim(self, with_lock: bool = True) -> None:
+        """Reclaim freed space across all pages."""
+
+    def pages(self) -> Generator[HeapMemoryPage]:
+        """Iterate mapped pages newest-first."""
+
+    def allocated(self) -> Generator[HeapMemoryBlock]:
+        """Iterate allocated blocks across all pages."""
+
+    def free_list(self) -> Generator[HeapMemoryBlock]:
+        """Iterate the allocator-wide free list."""
+
+    @property
+    def mapped_pages(self) -> int:
+        """Count of pages currently mapped by the allocator."""
+
+    @property
+    def active_page(self) -> HeapMemoryPage | None:
+        """Most recently mapped page, if any."""
+
+    @property
+    def autopage_capacity(self) -> int:
+        """Default capacity for auto-sized pages (read/write)."""
+
+    @autopage_capacity.setter
+    def autopage_capacity(self, value: int) -> None: ...
+
+    @property
+    def autopage_capacity_max(self) -> int:
+        """Maximum capacity a page can grow to (read/write)."""
+
+    @autopage_capacity_max.setter
+    def autopage_capacity_max(self, value: int) -> None: ...
+
+    @property
+    def autopage_alignment(self) -> int:
+        """Page alignment in bytes (read/write)."""
+
+    @autopage_alignment.setter
+    def autopage_alignment(self, value: int) -> None: ...
+
+
+ALLOCATOR: HeapAllocator
+
+DEFAULT_AUTOPAGE_CAPACITY: int
+MAX_AUTOPAGE_CAPACITY: int
+DEFAULT_AUTOPAGE_ALIGNMENT: int