ByteMap

Module: cbase.bytemap

A family of fast, C-backed hash maps for byte-string keys with several variants: basic ByteMap, extended ByteMapEx, and bound convenience wrappers.

class cbase.bytemap.c_bytemap.BoundByteMap(*args, **kwargs)

Bases: _BoundByteMapBase

__init__(*args, **kwargs)
class cbase.bytemap.c_bytemap.BoundByteMapEx(size_t slot_capacity=0, *args, **kwargs)

Bases: _BoundByteMapBase

__init__(*args, **kwargs)
class cbase.bytemap.c_bytemap.BoundByteMapExDouble(*args, **kwargs)

Bases: _BoundByteMapBase

__init__(*args, **kwargs)
ws
class cbase.bytemap.c_bytemap.BoundByteSet(*args, **kwargs)

Bases: set

__init__(*args, **kwargs)
add(self, py_key)
clear(self)
discard(self, py_key)
fork(self)
pop(self)
rebind(self, src)
remove(self, py_key)
update(self, *args)
class cbase.bytemap.c_bytemap.ByteMap(size_t init_capacity=DEFAULT_BYTEMAP_CAPACITY)

Bases: _ByteMapBase

__copy__(self)
__deepcopy__(self, memo)
__init__(*args, **kwargs)
bytes_keys(self)
capacity
contains(key)
Parameters:

key (str | bytes)

get(self, key, default=None)
get_addr(self, key)
hash(self, key) → uint64_t
pop(self, key, default=NO_DEFAULT)
salt
set(self, key, value)
set_addr(self, key, uintptr_t value)
str_keys(self)
values(self)
class cbase.bytemap.c_bytemap.ByteMapEx(size_t slot_capacity, size_t init_capacity=DEFAULT_BYTEMAP_CAPACITY)

Bases: _ByteMapBase

__copy__(self)
__deepcopy__(self, memo)
__init__(*args, **kwargs)
as_dict
contains(self, str key)
fork(self)
get(self, str key, bytes default=None)
items(self)
keys(self)
pop(self, str key, bytes default=NO_DEFAULT_BYTES)
set(self, str key, bytes value)
values(self)
class cbase.bytemap.c_bytemap.ByteMapExDouble(size_t init_capacity=DEFAULT_BYTEMAP_CAPACITY)

Bases: _ByteMapBase

__copy__(self)
__deepcopy__(self, memo)
__init__(*args, **kwargs)
as_dict
contains(self, str key)
fork(self)
get(self, str key, double default=NAN)
items(self)
keys(self)
pop(self, str key, default=NO_DEFAULT)
set(self, str key, double value)
values(self)
class cbase.bytemap.c_bytemap.ByteMapPerformanceTestToolkit

Bases: object

c_map_get_routine(self) → double
c_map_set_routine(self) → double
static gen_seq_id(uintptr_t addr)

Generate a seq_id from an address using c_bytemap_gen_seq_id.

Public for testing multiprocessing seq_id uniqueness across processes.

n_iters
n_payloads
py_keys
py_map_get_routine(self) → double
py_map_set_routine(self) → double
py_payloads
run_test(self) → dict
cbase.bytemap.c_bytemap.__reduce_cython__(self)
cbase.bytemap.c_bytemap.__setstate_cython__(self, __pyx_state)

Map Variants

ByteMap

The simplest variant — maps bytes keys to bytes values. Stores references to PyObject* keys and values.

from cbase.bytemap import ByteMap

bm = ByteMap()
bm[b"key"] = b"value"
assert bm[b"key"] == b"value"
assert b"key" in bm
del bm[b"key"]

ByteMapEx

Extended variant — maps arbitrary PyObject* keys to PyObject* values with callback support, cloning, and fine-grained control.

Callback registration:

from cbase.bytemap import ByteMapEx

def on_set(event, entry, ctx):
    print(f"Set: {event}, key={entry.key}")

bm = ByteMapEx()
bm.register_callback(on_set)
bm["key"] = "value"  # Fires callback

ByteMapExDouble

Variant that maps bytes keys to C double values (not Python float objects), avoiding boxing overhead.

Bound Wrappers

Bound map variants lock the key to a specific bytes object for convenience and performance:

from cbase.bytemap import BoundByteMap, BoundByteMapEx, BoundByteMapExDouble, BoundByteSet

# BoundByteMap — fixed key, variable bytes value
bbm = BoundByteMap(b"my_key")
bbm.set(b"my_value")
val = bbm.get()

# BoundByteSet — membership-only, no value storage
bbs = BoundByteSet(b"my_key")
bbs.add()  # Mark as present
assert bbs.contains()

Usage Examples

Rehashing to reduce collisions:

bm = ByteMap()
for i in range(10000):
    bm[f"key_{i}".encode()] = f"val_{i}".encode()
bm.rehash()  # Rebalance with larger capacity if needed

Compile-Time Constants

from cbase.bytemap.c_bytemap import (
    MIN_BYTEMAP_CAPACITY,       # Minimum hash table capacity
    DEFAULT_BYTEMAP_CAPACITY,   # Default initial capacity
    BYTEMAP_GROWTH_FACTOR,      # Growth multiplier on rehash
    MAX_BYTEMAP_CAPACITY,       # Maximum capacity ceiling
)

Hashing

The ByteMap uses xxHash3 (64-bit) for key hashing. The xxhash.h and xxhash.c files in cbase/bytemap/ provide a vendored copy of the xxHash library.

Thread Safety

ByteMap operations are not internally synchronized. Use external locking or the with_lock parameter of the allocator protocol when accessing maps from multiple threads.

See also