PyCyBase 0.1.10__cp315-cp315-win_amd64.whl

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

cbase/allocator_protocol/c_heap_allocator.pyx

@@ -0,0 +1,303 @@
+from libc.errno cimport errno
+from libc.stdint cimport uintptr_t
+
+
+cdef class HeapMemoryPage:
+    def __cinit__(self, uintptr_t page_addr=0):
+        self.page = <heap_page*> page_addr if page_addr else NULL
+
+    @staticmethod
+    cdef inline HeapMemoryPage c_from_header(heap_page* header):
+        cdef HeapMemoryPage instance = HeapMemoryPage.__new__(HeapMemoryPage, 0)
+        instance.page = header
+        return instance
+
+    def __repr__(self):
+        if self.page:
+            return f"<{self.__class__.__name__}>(capacity={self.capacity:,}, occupied={self.occupied:,})"
+        return f"<{self.__class__.__name__}>(uninitialized)"
+
+    @classmethod
+    def from_buffer(cls, uintptr_t buffer_addr) -> HeapMemoryPage:
+        cdef HeapMemoryPage instance = cls.__new__(cls, 0)
+        instance.page = <heap_page*> (<char*> buffer_addr - sizeof(heap_page))
+        return instance
+
+    def allocated(self):
+        if not self.page:
+            return
+        cdef heap_memory_block* block = self.page.allocated
+        while block:
+            yield HeapMemoryBlock.c_from_header(block, False)
+            block = block.next_allocated
+
+    cpdef void reclaim(self):
+        if not self.page:
+            raise RuntimeError(f"Uninitialized <{self.__class__.__name__}>")
+        c_heap_page_reclaim(self.page.allocator, self.page)
+
+    property capacity:
+        def __get__(self):
+            if self.page:
+                return <size_t> self.page.capacity
+            return 0
+
+    property occupied:
+        def __get__(self):
+            if self.page:
+                return <size_t> self.page.occupied
+            return 0
+
+    property allocator:
+        def __get__(self):
+            if not self.page:
+                return None
+            return HeapAllocator.c_from_header(self.page.allocator, False)
+
+    property address:
+        def __get__(self):
+            if not self.page:
+                return None
+            return f"{<uintptr_t> self.page.buffer:#0x}"
+
+
+cdef class HeapMemoryBlock:
+    def __cinit__(self, uintptr_t block=0, bint owner=False):
+        self.block = <heap_memory_block*> block if block else NULL
+        self.owner = owner
+
+    def __dealloc__(self):
+        if not self.owner:
+            return
+
+        if self.block:
+            c_heap_free(self.block.buffer, &self.block.parent_page.allocator.lock)
+
+    @staticmethod
+    cdef inline HeapMemoryBlock c_from_header(heap_memory_block* header, bint owner=False):
+        cdef HeapMemoryBlock instance = HeapMemoryBlock.__new__(HeapMemoryBlock, 0, owner)
+        instance.block = header
+        return instance
+
+    def __repr__(self):
+        if self.block:
+            return f"<{self.__class__.__name__}>(size={self.block.size}, capacity={self.block.capacity})"
+        return f"<{self.__class__.__name__}>(uninitialized)"
+
+    property size:
+        def __get__(self):
+            if not self.block:
+                return -1
+            return <size_t> self.block.size
+
+    property capacity:
+        def __get__(self):
+            if not self.block:
+                return -1
+            return <size_t> self.block.capacity
+
+    property next_free:
+        def __get__(self):
+            if self.block and self.block.next_free:
+                return HeapMemoryBlock.c_from_header(self.block.next_free, False)
+            return None
+
+    property next_allocated:
+        def __get__(self):
+            if self.block and self.block.next_allocated:
+                return HeapMemoryBlock.c_from_header(self.block.next_allocated, False)
+            return None
+
+    property parent_page:
+        def __get__(self):
+            if not self.block:
+                return None
+            return HeapMemoryPage.c_from_header(self.block.parent_page)
+
+    property buffer:
+        def __get__(self):
+            if not self.block:
+                return None
+            cdef size_t size = self.block.size
+            return <char[:size]> self.block.buffer
+
+    property address:
+        def __get__(self):
+            if not self.block:
+                return None
+            return f"{<uintptr_t> self.block.buffer:#0x}"
+
+
+cdef class HeapAllocator:
+    def __init__(self):
+        self.allocator = c_heap_allocator_new()
+        if not self.allocator:
+            raise OSError(errno, "Initialize heap allocator failed")
+        self.owner = True
+
+    def __dealloc__(self):
+        if not self.owner:
+            return
+
+        if self.allocator:
+            c_heap_allocator_free(self.allocator)
+
+    @staticmethod
+    cdef HeapAllocator c_from_header(heap_allocator* header, bint owner=False):
+        cdef HeapAllocator instance = HeapAllocator.__new__(HeapAllocator)
+        instance.allocator = header
+        instance.owner = owner
+        return instance
+
+    cdef inline heap_page* c_extend(self, size_t capacity=0, pthread_mutex_t* lock=NULL):
+        if not self.allocator:
+            raise RuntimeError(f'Uninitialized <{self.__class__.__name__}>')
+        return c_heap_allocator_extend(self.allocator, capacity, lock)
+
+    cdef inline void* c_calloc(self, size_t size, pthread_mutex_t* lock=NULL):
+        if not self.allocator:
+            raise RuntimeError(f'Uninitialized <{self.__class__.__name__}>')
+        return c_heap_calloc(self.allocator, size, lock)
+
+    cdef inline void* c_request(self, size_t size, int scan_all_pages=1, pthread_mutex_t* lock=NULL):
+        if not self.allocator:
+            raise RuntimeError(f'Uninitialized <{self.__class__.__name__}>')
+        return c_heap_request(self.allocator, size, scan_all_pages, lock)
+
+    cdef inline void c_free(self, void* ptr, pthread_mutex_t* lock=NULL):
+        if not self.allocator:
+            raise RuntimeError(f'Uninitialized <{self.__class__.__name__}>')
+        c_heap_free(ptr, lock)
+
+    cpdef HeapMemoryPage extend(self, size_t capacity=0, bint with_lock=True):
+        if not self.allocator:
+            raise RuntimeError(f'Uninitialized <{self.__class__.__name__}>')
+        cdef pthread_mutex_t* lock = &self.allocator.lock if with_lock else NULL
+        cdef heap_page* page = c_heap_allocator_extend(self.allocator, capacity, lock)
+        if not page:
+            raise OSError(errno, f'<{self.__class__.__name__}> failed to extend new page')
+        return HeapMemoryPage.c_from_header(page)
+
+    cpdef HeapMemoryBlock calloc(self, size_t size, bint with_lock=True):
+        if not self.allocator:
+            raise RuntimeError(f"Uninitialized <{self.__class__.__name__}>")
+        cdef pthread_mutex_t* lock = &self.allocator.lock if with_lock else NULL
+        cdef void* p = c_heap_calloc(self.allocator, size, lock)
+        if not p:
+            raise OSError(errno, f"<{self.__class__.__name__}> failed to calloc new buffer")
+        cdef heap_memory_block* block = <heap_memory_block*> (<char*> p - sizeof(heap_memory_block))
+        return HeapMemoryBlock.c_from_header(block, True)
+
+    cpdef HeapMemoryBlock request(self, size_t size, bint with_lock=True, bint scan_all_pages=True):
+        if not self.allocator:
+            raise RuntimeError(f'Uninitialized <{self.__class__.__name__}>')
+        cdef pthread_mutex_t* lock = &self.allocator.lock if with_lock else NULL
+        cdef void* p = c_heap_request(self.allocator, size, <int> scan_all_pages, lock)
+        if not p:
+            raise OSError(errno, f'<{self.__class__.__name__}> failed to request new buffer')
+        cdef heap_memory_block* block = <heap_memory_block*> (<char*> p - sizeof(heap_memory_block))
+        return HeapMemoryBlock.c_from_header(block, True)
+
+    cpdef void free(self, HeapMemoryBlock buffer, bint with_lock=True):
+        if not self.allocator:
+            raise RuntimeError(f'Uninitialized <{self.__class__.__name__}>')
+        if not buffer or not buffer.block:
+            return
+        cdef pthread_mutex_t* lock = &buffer.block.parent_page.allocator.lock if with_lock else NULL
+        c_heap_free(<void*> buffer.block.buffer, lock)
+        buffer.owner = False
+        buffer.block = NULL
+
+    cpdef void reclaim(self, bint with_lock=True):
+        if not self.allocator:
+            raise RuntimeError(f'Uninitialized <{self.__class__.__name__}>')
+        cdef pthread_mutex_t* lock = &self.allocator.lock if with_lock else NULL
+        c_heap_reclaim(self.allocator, lock)
+
+    def pages(self):
+        if not self.allocator:
+            raise RuntimeError(f'Uninitialized <{self.__class__.__name__}>')
+        cdef heap_page* page = self.allocator.active_page
+        while page:
+            yield HeapMemoryPage.c_from_header(page)
+            page = page.prev
+
+    def allocated(self):
+        if not self.allocator:
+            raise RuntimeError(f'Uninitialized <{self.__class__.__name__}>')
+        cdef heap_page* page = self.allocator.active_page
+        cdef heap_memory_block* block
+        while page:
+            block = page.allocated
+            while block:
+                yield HeapMemoryBlock.c_from_header(block, False)
+                block = block.next_allocated
+            page = page.prev
+
+    def free_list(self):
+        if not self.allocator:
+            raise RuntimeError(f'Uninitialized <{self.__class__.__name__}>')
+        cdef heap_memory_block* block
+        cdef size_t bin
+        for bin in range(AP_HEAP_BIN_COUNT):
+            block = self.allocator.bins[bin]
+            while block:
+                yield HeapMemoryBlock.c_from_header(block, False)
+                block = block.next_free
+
+    property mapped_pages:
+        def __get__(self):
+            if not self.allocator:
+                raise RuntimeError(f'Uninitialized <{self.__class__.__name__}>')
+            return <size_t> self.allocator.mapped_pages
+
+    property active_page:
+        def __get__(self):
+            if not self.allocator:
+                raise RuntimeError(f'Uninitialized <{self.__class__.__name__}> or no active page')
+            elif not self.allocator.active_page:
+                return None
+            return HeapMemoryPage.c_from_header(self.allocator.active_page)
+
+    property autopage_capacity:
+        def __get__(self):
+            if not self.allocator:
+                raise RuntimeError(f'Uninitialized <{self.__class__.__name__}>')
+            return <size_t> self.allocator.autopage_capacity
+
+        def __set__(self, size_t value):
+            if not self.allocator:
+                raise RuntimeError(f'Uninitialized <{self.__class__.__name__}>')
+            self.allocator.autopage_capacity = value
+
+    property autopage_capacity_max:
+        def __get__(self):
+            if not self.allocator:
+                raise RuntimeError(f'Uninitialized <{self.__class__.__name__}>')
+            return <size_t> self.allocator.autopage_capacity_max
+
+        def __set__(self, size_t value):
+            if not self.allocator:
+                raise RuntimeError(f'Uninitialized <{self.__class__.__name__}>')
+            self.allocator.autopage_capacity_max = value
+
+    property autopage_alignment:
+        def __get__(self):
+            if not self.allocator:
+                raise RuntimeError(f'Uninitialized <{self.__class__.__name__}>')
+            return <size_t> self.allocator.autopage_alignment
+
+        def __set__(self, size_t value):
+            if not self.allocator:
+                raise RuntimeError(f'Uninitialized <{self.__class__.__name__}>')
+            self.allocator.autopage_alignment = value
+
+
+cdef HeapAllocator ALLOCATOR = HeapAllocator()
+ALLOCATOR.owner = False
+cdef heap_allocator* C_ALLOCATOR = ALLOCATOR.allocator
+
+globals()['ALLOCATOR'] = ALLOCATOR
+globals()['DEFAULT_AUTOPAGE_CAPACITY'] = AP_HEAP_AUTOPAGE_CAPACITY
+globals()['MAX_AUTOPAGE_CAPACITY'] = AP_HEAP_AUTOPAGE_CAPACITY_MAX
+globals()['DEFAULT_AUTOPAGE_ALIGNMENT'] = AP_HEAP_AUTOPAGE_ALIGNMENT