PyCyBase 0.1.8.post4__cp313-cp313-win_amd64.whl

cbase/includes/cbase/nt/regex_nt_compat.h

@@ -0,0 +1,133 @@
+#ifndef REGEX_NT_COMPAT_H
+#define REGEX_NT_COMPAT_H
+
+#ifndef _WIN32
+#error "regex_nt_compat.h is intended for Windows builds only"
+#endif
+
+#include <errno.h>
+#include <stddef.h>
+
+#if defined(__has_include)
+#if __has_include(<Python.h>)
+#include <Python.h>
+#define REGEX_NT_COMPAT_HAS_PYTHON 1
+#else
+#define REGEX_NT_COMPAT_HAS_PYTHON 0
+#endif
+#else
+#include <Python.h>
+#define REGEX_NT_COMPAT_HAS_PYTHON 1
+#endif
+
+#ifndef REG_EXTENDED
+#define REG_EXTENDED 1
+#endif
+
+#ifndef REG_NOMATCH
+#define REG_NOMATCH 1
+#endif
+
+#ifndef REG_BADPAT
+#define REG_BADPAT 2
+#endif
+
+typedef struct regex_t {
+    PyObject* compiled;
+} regex_t;
+
+typedef struct regmatch_t {
+    ptrdiff_t rm_so;
+    ptrdiff_t rm_eo;
+} regmatch_t;
+
+#if REGEX_NT_COMPAT_HAS_PYTHON
+
+static inline int regcomp(regex_t* regex, const char* pattern, int cflags) {
+    (void) cflags;
+    if (!regex || !pattern) {
+        return REG_BADPAT;
+    }
+
+    regex->compiled = NULL;
+
+    PyGILState_STATE gil_state = PyGILState_Ensure();
+    PyObject*        re_module = PyImport_ImportModule("re");
+    if (!re_module) {
+        PyErr_Clear();
+        PyGILState_Release(gil_state);
+        return REG_BADPAT;
+    }
+
+    PyObject* compiled = PyObject_CallMethod(re_module, "compile", "s", pattern);
+    Py_DECREF(re_module);
+    if (!compiled) {
+        PyErr_Clear();
+        PyGILState_Release(gil_state);
+        return REG_BADPAT;
+    }
+
+    regex->compiled = compiled;
+    PyGILState_Release(gil_state);
+    return 0;
+}
+
+static inline int regexec(const regex_t* regex, const char* string, size_t nmatch, regmatch_t pmatch[], int eflags) {
+    (void) nmatch;
+    (void) pmatch;
+    (void) eflags;
+
+    if (!regex || !regex->compiled || !string) {
+        return REG_NOMATCH;
+    }
+
+    PyGILState_STATE gil_state = PyGILState_Ensure();
+    PyObject*        match = PyObject_CallMethod(regex->compiled, "search", "s", string);
+    if (!match) {
+        PyErr_Clear();
+        PyGILState_Release(gil_state);
+        return REG_NOMATCH;
+    }
+
+    int result = (match == Py_None) ? REG_NOMATCH : 0;
+    Py_DECREF(match);
+    PyGILState_Release(gil_state);
+    return result;
+}
+
+static inline void regfree(regex_t* regex) {
+    if (!regex || !regex->compiled) {
+        return;
+    }
+
+    PyGILState_STATE gil_state = PyGILState_Ensure();
+    Py_DECREF(regex->compiled);
+    regex->compiled = NULL;
+    PyGILState_Release(gil_state);
+}
+
+#else
+
+static inline int regcomp(regex_t* regex, const char* pattern, int cflags) {
+    (void) regex;
+    (void) pattern;
+    (void) cflags;
+    return REG_BADPAT;
+}
+
+static inline int regexec(const regex_t* regex, const char* string, size_t nmatch, regmatch_t pmatch[], int eflags) {
+    (void) regex;
+    (void) string;
+    (void) nmatch;
+    (void) pmatch;
+    (void) eflags;
+    return REG_NOMATCH;
+}
+
+static inline void regfree(regex_t* regex) {
+    (void) regex;
+}
+
+#endif
+
+#endif /* REGEX_NT_COMPAT_H */

cbase/includes/cbase/nt/time_sched_nt_compat.h

@@ -0,0 +1,32 @@
+#ifndef TIME_SCHED_NT_COMPAT_H
+#define TIME_SCHED_NT_COMPAT_H
+
+#ifndef _WIN32
+#error "time_sched_nt_compat.h is intended for Windows builds only"
+#endif
+
+#include <time.h>
+
+#ifndef WIN32_LEAN_AND_MEAN
+#define WIN32_LEAN_AND_MEAN
+#endif
+#include <windows.h>
+
+#ifndef CLOCK_REALTIME
+#define CLOCK_REALTIME 0
+#endif
+
+static inline int clock_gettime(int clock_id, struct timespec* ts) {
+    (void) clock_id;
+    if (!ts) {
+        return -1;
+    }
+
+    return timespec_get(ts, TIME_UTC) == TIME_UTC ? 0 : -1;
+}
+
+static inline void sched_yield(void) {
+    SwitchToThread();
+}
+
+#endif /* TIME_SCHED_NT_COMPAT_H */

cbase/int128.h

@@ -0,0 +1,81 @@
+#ifndef C_CBASE_INT128_H
+#define C_CBASE_INT128_H
+
+#include <stdint.h>
+#include <string.h>
+
+#if defined(__SIZEOF_INT128__)
+typedef __int128_t     int128_t;
+typedef __uint128_t    uint128_t;
+
+static const uint128_t UINT128_MAX = (((uint128_t) 1) << 127) * 2 - 1;
+static const int128_t  INT128_MAX = (int128_t) (UINT128_MAX >> 1);
+static const int128_t  INT128_MIN = -((int128_t) (UINT128_MAX)) - 1;
+
+static inline int      c_u128_cmp(const uint128_t v1, const uint128_t v2) {
+    if (v1 < v2) return -1;
+    if (v1 > v2) return 1;
+    return 0;
+}
+
+static inline int c_i128_cmp(const int128_t v1, const int128_t v2) {
+    if (v1 < v2) return -1;
+    if (v1 > v2) return 1;
+    return 0;
+}
+#else
+/**
+ * @brief MSVC has no native 128-bit integer -- emulate with a two-limb
+ *        little-endian struct (memory layout identical to __uint128_t on
+ *        x86-64, so 16-byte ID slots stay byte-compatible).
+ *
+ * The Cython boundary converts via int.to_bytes/from_bytes, so no 128-bit
+ * arithmetic is required -- only 16-byte round-trips and ordered comparison.
+ */
+typedef struct {
+    uint64_t lo;
+    int64_t  hi;
+} int128_t;
+typedef struct {
+    uint64_t lo;
+    uint64_t hi;
+} uint128_t;
+
+static const uint128_t UINT128_MAX = {UINT64_MAX, UINT64_MAX};
+static const int128_t  INT128_MAX = {UINT64_MAX, INT64_MAX};
+static const int128_t  INT128_MIN = {0u, INT64_MIN};
+
+static inline int      c_u128_cmp(const uint128_t v1, const uint128_t v2) {
+    if (v1.hi != v2.hi) return v1.hi < v2.hi ? -1 : 1;
+    if (v1.lo != v2.lo) return v1.lo < v2.lo ? -1 : 1;
+    return 0;
+}
+
+static inline int c_i128_cmp(const int128_t v1, const int128_t v2) {
+    if (v1.hi != v2.hi) return v1.hi < v2.hi ? -1 : 1;
+    if (v1.lo != v2.lo) return v1.lo < v2.lo ? -1 : 1;
+    return 0;
+}
+#endif
+
+static inline void c_write_uint128(void* data, uint128_t value) {
+    memcpy(data, &value, sizeof(uint128_t));
+}
+
+static inline uint128_t c_read_uint128(const void* data) {
+    uint128_t value;
+    memcpy(&value, data, sizeof(uint128_t));
+    return value;
+}
+
+static inline void c_write_int128(void* data, int128_t value) {
+    memcpy(data, &value, sizeof(int128_t));
+}
+
+static inline int128_t c_read_int128(const void* data) {
+    int128_t value;
+    memcpy(&value, data, sizeof(int128_t));
+    return value;
+}
+
+#endif  // C_CBASE_INT128_H

cbase/int128.pxd

@@ -0,0 +1,15 @@
+cdef extern from "cbase/int128.h":
+    ctypedef unsigned long long uint128_t
+    ctypedef long long int128_t
+
+    const uint128_t UINT128_MAX
+    const int128_t INT128_MAX
+    const int128_t INT128_MIN
+
+    uint128_t c_read_uint128(const void* data)
+    void      c_write_uint128(void* data, uint128_t value)
+    int128_t  c_read_int128(const void* data)
+    void      c_write_int128(void* data, int128_t value)
+
+    int c_u128_cmp(uint128_t v1, uint128_t v2)
+    int c_i128_cmp(int128_t v1, int128_t v2)

cbase/intern_string/BENCHMARK.md

@@ -0,0 +1,157 @@
+# InternString Performance Benchmark
+
+## Realistic Workload — Miss-Rate Controlled
+
+**Scenario:** 1,000,000 operations with controlled miss rates from 1/1K to 1/1M  
+**Config:** 256 MiB buffer, 1M available segments, 32-byte max, 10 iterations  
+**Method:** Misses (new unique strings) evenly distributed; hits randomly pick from already-seen set
+
+| Miss Rate   | n_misses | istr (ns) | py_unicode (ns) |  Speedup |
+| ----------- | -------: | --------: | --------------: | -------: |
+| 1/1,000     |    1,000 |   16.7 ns |         28.5 ns | **1.7×** |
+| 1/10,000    |      100 |   14.2 ns |         26.6 ns | **1.9×** |
+| 1/100,000   |       10 |   11.1 ns |         21.1 ns | **1.9×** |
+| 1/1,000,000 |        1 |    7.3 ns |         16.4 ns | **2.2×** |
+
+### Analysis
+
+- At **1/1M** miss rate (typical for production ticker/data feeds): istr is **2.2× faster** than Python `str` creation
+- As miss rate → 0, istr latency approaches the raw hash+probe cost (7.3 ns) — almost all operations are hash-table hits
+- Python `str` creation is independent of miss rate — it always allocates a new object (~16–28 ns)
+- The crossover point where istr becomes faster than Python `str` is at approximately **1/10 miss rate** (10% new strings)
+- Below 1/100 miss rate, istr provides **1.7–2.2× speedup** PLUS string deduplication, stable C pointers, and cached FNV-1a hashes
+
+### What istr provides beyond raw speed
+
+| Feature              | istr                               | Python str                     |
+| -------------------- | ---------------------------------- | ------------------------------ |
+| String deduplication | ✅ Same pointer for same key        | ❌ New object every time        |
+| Stable C pointer     | ✅ `const char*` usable as hash key | ❌ Must call `PyUnicode_AsUTF8` |
+| Cached hash          | ✅ FNV-1a stored in entry           | ❌ Computed on first `hash()`   |
+| Memory               | One copy per unique string         | One copy per creation          |
+
+---
+
+## Backend Comparison — Pure C-level
+
+**Dataset:** 256 MiB buffer, 50,000 segments, max 64 bytes/segment, 10 iterations
+**Total key bytes:** ~1.6 MB
+
+### Per-operation latency (ns)
+
+| Benchmark                |   Native |  Bytemap | Winner          |
+| ------------------------ | -------: | -------: | --------------- |
+| `fnv1a_hash` (raw C)     |  48.8 ns |  38.3 ns | Bytemap (1.27×) |
+| `istr_intern` (unlocked) | 291.6 ns | 532.8 ns | Native (1.83×)  |
+| `istr_intern_synced`     | 192.2 ns | 390.5 ns | Native (2.03×)  |
+| `istr_lookup` (unlocked) |  57.3 ns |  28.2 ns | Bytemap (2.03×) |
+| `istr_lookup_synced`     |  54.5 ns |  26.3 ns | Bytemap (2.07×) |
+| `istr_eq` (Python)       | 215.1 ns | 197.7 ns | Bytemap (1.09×) |
+| `py_unicode` (create)    |  52.4 ns |  46.0 ns | —               |
+| `py_hash` (str)          |   3.8 ns |   4.2 ns | —               |
+| `py_eq` (str)            |   4.7 ns |   4.7 ns | —               |
+
+### Mutex overhead (synced − unlocked, per op)
+
+| Operation | Native  | Bytemap |
+| --------- | ------- | ------- |
+| Intern    | *noise* | *noise* |
+| Lookup    | ~1.0 ns | ~1.9 ns |
+
+> Mutex overhead is within measurement noise — the pthread_mutex_lock/unlock cost
+> (~15–25 ns) is dwarfed by the hash+probe cost at 50k iterations. The negative
+> values sometimes seen are run-ordering artifacts (heap warm-up from prior
+> unlocked run).
+
+### Analysis
+
+| Operation            | Result                                                                                   |
+| -------------------- | ---------------------------------------------------------------------------------------- |
+| **Intern speed**     | Native 1.83× faster — simpler insert path (no tombstone logic, no XXH3 wrapper overhead) |
+| **Lookup speed**     | Bytemap 2.03× faster — XXH3 hash + `memcmp` with stored `key_length` beats FNV-1a        |
+| **Hash speed**       | XXH3 beats FNV-1a by 1.27× on raw `const char*`                                          |
+| **Pure C vs Python** | Both now hit C fast path via `PyUnicode_AsUTF8AndSize` + `key_length` — zero strlen      |
+
+### Backend behavioral differences
+
+| Behavior            | Native                     | Bytemap                                        |
+| ------------------- | -------------------------- | ---------------------------------------------- |
+| Iteration order     | LIFO (reverse insertion)   | FIFO (insertion order via doubly-linked list)  |
+| Empty string (`""`) | Valid (1-byte allocation)  | Rejected (`BYTEMAP_ERR_INVALID_KEY`)           |
+| Hash function       | FNV-1a                     | XXH3 (with per-map salt)                       |
+| Capacity rounding   | Power-of-2                 | Internal (MIN_BYTEMAP_CAPACITY = 16)           |
+| Resize trigger      | `size >= capacity/2`       | `occupied * 2 >= capacity`                     |
+| Thread safety       | Internal `pthread_mutex_t` | Embedded `pthread_mutex_t` in istr_map wrapper |
+
+### Optimizations applied
+
+- `c_istr` / `c_istr_map_lookup` accept `size_t key_length` — `strlen` skipped when known
+- `strcmp` replaced with `key_length` comparison + `memcmp` shortcut
+- `PyUnicode_AsUTF8AndSize` passes pre-computed UTF-8 length from Python layer
+- C-level benchmark routines bypass Python `str` entirely — raw `const char*` + `size_t`
+
+---
+
+## NT Cross-Platform — Native Backend
+
+**Quick benchmark:** 1 MiB buffer, 5,000 segments, max 64 bytes, 5 iterations
+**Unit tests:** 220/220 pass, 0 fail, 5 skipped (fork-related)
+
+### Per-operation latency (ns)
+
+| Benchmark                | Linux (gcc -O2) | Windows NT (MSVC /O2) | Δ    |
+| ------------------------ | --------------: | --------------------: | ---- |
+| `fnv1a_hash`             |         13.5 ns |               15.5 ns | +15% |
+| `istr_intern` (unlocked) |        116.6 ns |              120.8 ns | +4%  |
+| `istr_intern` (synced)   |        102.6 ns |              107.0 ns | +4%  |
+| `istr_lookup` (unlocked) |         24.6 ns |               30.2 ns | +23% |
+| `istr_lookup` (synced)   |         25.6 ns |               31.6 ns | +23% |
+| `istr_eq` (Python)       |        177.5 ns |              208.0 ns | +17% |
+| `py_unicode` (create)    |         27.9 ns |               34.1 ns | +22% |
+| `py_hash`                |          4.6 ns |                6.3 ns | +37% |
+| `py_eq`                  |          4.6 ns |                6.8 ns | +48% |
+
+### NT compatibility
+
+| Component                                                      | Status                                  |
+| -------------------------------------------------------------- | --------------------------------------- |
+| `pthread_nt_compat.h` (`pthread_mutex_t` → `CRITICAL_SECTION`) | ✅                                       |
+| MSVC build (`/std:c17 /experimental:c11atomics`)               | ✅                                       |
+| Cython 3.x on Windows                                          | ✅                                       |
+| All 220 unit tests                                             | ✅                                       |
+| Thread safety (concurrent tests)                               | ✅                                       |
+| Performance delta vs Linux                                     | ~15–23% (expected: MSVC vs GCC codegen) |
+
+---
+
+## Running Benchmarks
+
+```bash
+# Linux — native backend (default)
+python tests/intern_string/test_perf.py          # full (1 GiB, 100k segs, 10 iters)
+python tests/intern_string/test_perf.py --quick  # quick (1 MiB, 5k segs, 5 iters)
+
+# Linux — bytemap backend (requires rebuild)
+# Add -DISTR_USE_BYTEMAP_BACKEND=1 to extra_compile_args in setup.py, rebuild, then:
+python tests/intern_string/test_perf.py --quick
+
+# Windows NT
+python nt_build.py                    # full sync→build→test cycle
+# Then run test_perf.py on the VM
+```
+
+## Test Toolkit API
+
+```python
+from cbase.intern_string.c_intern_string import IstrTestToolkit
+
+tk = IstrTestToolkit(
+    buf_size=2**30,    # 1 GiB character buffer
+    n_seg=100_000,     # number of random segments
+    max_seg_len=64,    # max segment length in bytes
+    n_iters=10,        # benchmark repetitions
+)
+
+results = tk.run_test()
+# Returns dict with per-op nanosecond latencies + raw timings
+```

cbase/intern_string/__infra__.pxd

@@ -0,0 +1,11 @@
+from .c_intern_string cimport (
+    InternString,
+    InternStringPool,
+    C_POOL, POOL,
+    C_INTRA_POOL, INTRA_POOL,
+    istr_map,
+    c_istr_map_new,
+    c_istr_map_free,
+    c_istr,
+    c_istr_synced,
+)

cbase/intern_string/__init__.pxd

@@ -0,0 +1,11 @@
+from .c_intern_string cimport (
+    InternString,
+    InternStringPool,
+    C_POOL, POOL,
+    C_INTRA_POOL, INTRA_POOL,
+    istr_map,
+    c_istr_map_new,
+    c_istr_map_free,
+    c_istr,
+    c_istr_synced,
+)

cbase/intern_string/__init__.py

@@ -0,0 +1,19 @@
+from .c_intern_string import (
+    InternString,
+    InternStringPool,
+    IstrTestToolkit,
+    POOL,
+    INTRA_POOL,
+    C_POOL,
+    C_INTRA_POOL,
+)
+
+__all__ = [
+    'InternString',
+    'InternStringPool',
+    'IstrTestToolkit',
+    'POOL',
+    'INTRA_POOL',
+    'C_POOL',
+    'C_INTRA_POOL',
+]