Handle System¶

Overview¶

The Hakka JSON library implements a sophisticated handle-based memory management system specifically engineered to prevent Out-Of-Memory (OOM) conditions when processing millions to billions of small JSON objects. The handle system uses compact 32-bit tokens instead of 64-bit pointers, achieving 50% memory reduction per reference—critical for preventing catastrophic memory exhaustion in large-scale JSON workloads.

Core Components¶

JsonHandleCompact¶

JsonHandleCompact is the primary handle class that provides a smart pointer-like interface for managing JSON objects. It encapsulates a 32-bit HandleManagerToken and coordinates with specialized managers for lifecycle management.

Header: include/hakka_json_handle.hpp

Class Definition¶

class JsonHandleCompact
{
    HandleManagerToken data;  // 32-bit encoded token
    static constexpr auto type_mask = 0xC0000000;  // Top 2 bits for type

public:
    JsonHandleCompact();  // Creates INVALID handle (data = 0)
    explicit JsonHandleCompact(HandleManagerToken token);

    // Copy semantics with reference counting
    JsonHandleCompact(const JsonHandleCompact &other);
    JsonHandleCompact &operator=(const JsonHandleCompact &other);

    // Move semantics (zero-cost transfer)
    JsonHandleCompact(JsonHandleCompact &&other) noexcept;
    JsonHandleCompact &operator=(JsonHandleCompact &&other) noexcept;

    ~JsonHandleCompact();

    // Type information
    HakkaJsonType get_type() const;

    // Object access
    UniformCompactPointerView get_view() const;
    UniformCompactPointer get_mut_ptr();  // Only for Array/Object

    // Reference counting (CPython integration)
    uint32_t retain() const;
    void release();

    // Validity checks
    bool operator!() const;
    operator bool() const;
    bool is_valid() const;

    // C API conversion
    operator uint64_t() const;
};

Memory Layout¶

The JsonHandleCompact contains only a single 32-bit HandleManagerToken:

JsonHandleCompact structure:

 HandleManagerToken data (32-bit)    
$
 Total size: 4 bytes                 


Compare to traditional pointer-based approach:

 void* pointer (64-bit)              
$
 Total size: 8 bytes (100% overhead)

Memory Efficiency: 50% reduction compared to raw pointers.

Token Encoding¶

The 32-bit token encodes both type information and object index:

HandleManagerToken Binary Layout:
,
 31 ... 30      29 ... 0               
  Type          Index                  
4

Type Encoding (bits 31-30):
  00 - Scalar types (int, float, bool, null, invalid)
  01 - String
  10 - Array
  11 - Object

Additional Scalar Discrimination (bit 29 when bits 31-30 = 00):
  001 - Integer (bit 29 = 1)
  000 - Float/Bool/Null/Invalid (bit 29 = 0)

Examples:

0x00000000  // INVALID (default constructed handle)
0x20000001  // Integer at index 1 (001 prefix)
0x00000005  // Float at index 5 (000 prefix)
0x40000000  // String at index 0 (01 prefix)
0x80000010  // Array at index 16 (10 prefix)
0xC0000020  // Object at index 32 (11 prefix)

Constructors and Initialization¶

Default Constructor:

JsonHandleCompact();  // data = 0 (INVALID handle)

Creates an invalid handle that represents an uninitialized or error state. The zero value is treated as INVALID_NAN in the scalar manager.

Token Constructor:

explicit JsonHandleCompact(HandleManagerToken token);

Creates a handle from an existing token. Typically used internally by manager create() methods.

Copy Constructor:

JsonHandleCompact(const JsonHandleCompact &other);

Creates a new handle referencing the same underlying object. Automatically calls retain() to increment the reference count.

Move Constructor:

JsonHandleCompact(JsonHandleCompact &&other) noexcept;

Transfers ownership from other to the new handle. Sets other.data = 0 (INVALID state) to prevent double-release.

Copy and Move Semantics¶

Copy Assignment:

JsonHandleCompact &operator=(const JsonHandleCompact &other);

- Releases current object (if any) - Copies token from other - Retains new object (increments reference count) - Self-assignment safe

Move Assignment:

JsonHandleCompact &operator=(JsonHandleCompact &&other) noexcept;

- Releases current object (if any) - Transfers token from other - Sets other.data = 0 to prevent double-release - Self-assignment safe - Zero-cost operation (no reference counting overhead)

Usage Example:

// Copy semantics (reference counting)
JsonHandleCompact handle1 = JsonIntCompact::create(42);
JsonHandleCompact handle2 = handle1;  // retain() called, ref_count = 2

// Move semantics (zero-cost transfer)
JsonHandleCompact handle3 = std::move(handle1);  // No retain(), handle1 becomes INVALID

Reference Counting for Python FFI Integration¶

The handle system uses explicit reference counting to enable Foreign Function Interface (FFI) integration with Python, without depending on CPython's internal headers or ABI.

Why Not RAII? - Python FFI requires explicit lifetime control across language boundaries - C++ RAII scope-based destruction conflicts with Python's reference-based lifetime management - Python objects can outlive C++ stack frames - FFI layer needs manual retain()/release() calls to coordinate with Python's reference counting model

Reference Counting Methods:

uint32_t retain() const;

Increments the reference count of the underlying object. Returns the new reference count.

Implementation: - Dispatches to appropriate type's inc_ref() method - Thread-safe (uses atomic operations) - Returns 0 for INVALID handles - Used automatically by copy constructor/assignment

void release();

Decrements the reference count and potentially destroys the object.

Implementation: - Calls manager's release() method - When ref_count reaches 0, object is destroyed - Sets data = 0 (INVALID state) after release - Called automatically by destructor and move operations

Usage Example:

// Manual reference counting
JsonHandleCompact handle = JsonIntCompact::create(42);
handle.retain();  // ref_count = 2
handle.release(); // ref_count = 1
handle.release(); // ref_count = 0, object destroyed, handle becomes INVALID

Python FFI Integration: The library provides a C ABI-compatible FFI layer (capi/ directory) that exposes C functions for lifetime management. The FFI layer converts between HakkaHandle (uint64_t typedef) and JsonHandleCompact internally, enabling Python bindings to manage C++ object lifetimes without requiring CPython headers—achieving complete ABI decoupling.

Type Information and Access¶

Get Type:

HakkaJsonType get_type() const;

Returns the JSON type of the underlying object. Dispatches to the appropriate manager's type() method.

Possible Return Values: - HAKKA_JSON_NULL - HAKKA_JSON_BOOL - HAKKA_JSON_INT - HAKKA_JSON_FLOAT - HAKKA_JSON_STRING - HAKKA_JSON_ARRAY - HAKKA_JSON_OBJECT - HAKKA_JSON_INVALID

Get Immutable View:

UniformCompactPointerView get_view() const;

Returns a type-safe const pointer to the underlying object as a std::variant.

Return Type (UniformCompactPointerView):

std::variant<
    std::monostate,           // Invalid/empty
    const JsonIntCompact*,
    const JsonFloatCompact*,
    const JsonBoolCompact*,
    const JsonStringCompact*,
    const JsonArrayCompact*,
    const JsonObjectCompact*,
    const JsonNullCompact*,
    const JsonInvalidCompact*
>

Usage Example:

JsonHandleCompact handle = JsonIntCompact::create(42);
UniformCompactPointerView view = handle.get_view();

if (auto* int_ptr = std::get_if<const JsonIntCompact*>(&view)) {
    auto value = (*int_ptr)->get();  // Retrieve int64_t value
}

Get Mutable Pointer:

UniformCompactPointer get_mut_ptr();

Returns a mutable pointer for structured types (Array, Object only).

Return Type (UniformCompactPointer):

std::variant<
    std::monostate,      // Invalid or immutable type
    JsonArrayCompact*,
    JsonObjectCompact*
>

Important: Only Array and Object types return valid pointers. All primitive types (Int, Float, String, Bool, Null) return std::monostate because they are immutable.

Usage Example:

JsonHandleCompact handle = JsonArrayCompact::create();
UniformCompactPointer mut_ptr = handle.get_mut_ptr();

if (auto* array_ptr = std::get_if<JsonArrayCompact*>(&mut_ptr)) {
    (*array_ptr)->push_back(JsonIntCompact::create(42));
}

Validity Checks¶

Boolean Conversion Operators:

bool operator!() const;      // Returns true if INVALID
operator bool() const;       // Returns true if valid
bool is_valid() const;       // Returns true if valid (data != 0)

All three methods check if data != 0. A handle with data = 0 represents an INVALID state.

Usage Example:

JsonHandleCompact handle;  // Default constructed (INVALID)
if (!handle) {
    // Handle is INVALID
}

handle = JsonIntCompact::create(42);
if (handle.is_valid()) {
    // Handle is valid
}

Destructor¶

~JsonHandleCompact();

Automatically calls release() to decrement reference count. When the last handle is destroyed and ref_count reaches 0, the underlying object is deallocated.

RAII-Style Cleanup:

{
    JsonHandleCompact handle = JsonIntCompact::create(42);
    // Use handle...
}  // Destructor called, release() decrements ref_count

Manager Coordination¶

Internal Method:

JsonHandleManagerCompact &get_manager() const;

Extracts the type from the token (top 2 bits) and retrieves the appropriate manager from the global registry.

Manager Dispatch Logic:

auto type = static_cast<JsonHandleManagerType>((data & type_mask) >> 30);
// type values:
//   0 (00) -> Scalar
//   1 (01) -> String
//   2 (10) -> Array
//   3 (11) -> Object

return *JsonHandleManagerRegistryCompact::get_instance().get_manager(type);

Uniform Pointer System¶

The handle system uses a pointer abstraction to provide type-safe, memory-efficient access to JSON objects.

UniformCompactPointerView¶

A type-safe std::variant wrapper for const access to JSON objects.

Header: include/uniform_compact_pointer.hpp

Definition:

using UniformCompactPointerView = std::variant<
    std::monostate,              // Invalid/empty state
    const JsonIntCompact*,
    const JsonFloatCompact*,
    const JsonBoolCompact*,
    const JsonStringCompact*,
    const JsonArrayCompact*,
    const JsonObjectCompact*,
    const JsonNullCompact*,
    const JsonInvalidCompact*
>;

Key Characteristics: - Non-owning: Does not manage object lifetime - Type-safe: Compile-time type checking through std::variant - Zero-cost abstraction: No runtime overhead beyond vtable-free dispatch - NaN-boxing aware: Special handling for NaN-boxed types (Bool, Null, Invalid)

NaN-Boxing Concept:

template <typename T>
concept isNanBoxingType = std::is_same_v<T, const JsonFloatCompact*> ||
                           std::is_same_v<T, const JsonBoolCompact*> ||
                           std::is_same_v<T, const JsonNullCompact*> ||
                           std::is_same_v<T, const JsonInvalidCompact*>;

Bool, Null, and Invalid types are implemented as NaN-boxed values within JsonFloatCompact. The dispatch function automatically handles the type cast.

Dispatch Function:

template <class Invoker, class Ret, class... Args>
auto dispatch(UniformCompactPointerView v, Invoker&& invoke, Args&&... args)
    -> tl::expected<Ret, HakkaJsonResultEnum>;

Provides type-safe visitation with automatic NaN-boxing handling and error propagation.

Usage Example:

UniformCompactPointerView view = handle.get_view();

// Using std::visit
std::visit([](auto&& ptr) {
    using T = std::decay_t<decltype(ptr)>;
    if constexpr (std::is_same_v<T, const JsonIntCompact*>) {
        // Handle integer
    } else if constexpr (std::is_same_v<T, const JsonStringCompact*>) {
        // Handle string
    }
    // ... other types
}, view);

// Using dispatch helper
auto result = dispatch<std::string>(view, [](auto* ptr) {
    return ptr->dump(0).value();
});

UniformCompactPointer¶

A type-safe std::variant wrapper for mutable access to structured types only.

Definition:

using UniformCompactPointer = std::variant<
    std::monostate,      // Invalid or immutable type
    JsonArrayCompact*,
    JsonObjectCompact*
>;

Key Characteristics: - Non-owning: Does not manage object lifetime - Mutable access: Allows modification of Array and Object contents - Limited scope: Only structured types support mutation (primitives are immutable) - Type-safe: Compile-time enforcement of mutability constraints

Usage Example:

UniformCompactPointer mut_ptr = handle.get_mut_ptr();

if (auto* array = std::get_if<JsonArrayCompact*>(&mut_ptr)) {
    (*array)->push_back(JsonIntCompact::create(42));
} else if (auto* object = std::get_if<JsonObjectCompact*>(&mut_ptr)) {
    (*object)->set("key", JsonStringCompact::create("value"));
}

OwnedUniformCompactPointer¶

A tagged pointer that owns the underlying JSON object. Used internally by handle managers for storage.

Header: include/uniform_compact_pointer.hpp

Key Features: - Ownership: Automatically destroys the object in destructor - Tagged pointer: Uses 4 high bits for type information - Move-only: Cannot be copied (enforces unique ownership) - Type-safe construction: Separate constructors for each JSON type

Tagged Pointer Encoding¶

OwnedUniformCompactPointer Memory Layout:
,
  Type (4 bits)       Pointer (60 bits)                     
<$
  High bits 63-60     Low bits 59-0                         
4

Type Encoding (4 high bits):
  0000 - Null
  0001 - String
  0010 - Int
  0011 - Float
  0100 - Bool
  0101 - Object
  0110 - Array
  1111 - Invalid

Type Masks:

constexpr static auto SHIFT_OFFSET = 60;  // Top 4 bits
constexpr static auto INT_MASK     = std::size_t(HAKKA_JSON_INT) << 60;
constexpr static auto FLOAT_MASK   = std::size_t(HAKKA_JSON_FLOAT) << 60;
constexpr static auto BOOL_MASK    = std::size_t(HAKKA_JSON_BOOL) << 60;
constexpr static auto NULL_MASK    = std::size_t(HAKKA_JSON_NULL) << 60;
constexpr static auto STRING_MASK  = std::size_t(HAKKA_JSON_STRING) << 60;
constexpr static auto ARRAY_MASK   = std::size_t(HAKKA_JSON_ARRAY) << 60;
constexpr static auto OBJECT_MASK  = std::size_t(HAKKA_JSON_OBJECT) << 60;
constexpr static auto INVALID_MASK = std::size_t(HAKKA_JSON_INVALID) << 60;

Pointer Extraction:

template <typename T>
T *get() const {
    return reinterpret_cast<T*>(
        reinterpret_cast<std::size_t>(data) & ~TYPE_MASK
    );
}

Removes the type tag from the high bits to recover the original pointer.

Constructors¶

Type-Specific Constructors:

explicit OwnedUniformCompactPointer(std::unique_ptr<JsonIntCompact> ptr);
explicit OwnedUniformCompactPointer(std::unique_ptr<JsonFloatCompact> ptr);
explicit OwnedUniformCompactPointer(std::unique_ptr<JsonStringCompact> ptr);
explicit OwnedUniformCompactPointer(std::unique_ptr<JsonArrayCompact> ptr);
explicit OwnedUniformCompactPointer(std::unique_ptr<JsonObjectCompact> ptr);
// ... other types

Each constructor: 1. Releases the unique_ptr to transfer ownership 2. Tags the pointer with appropriate type mask 3. Stores the tagged pointer in data

Nullptr Constructor:

explicit OwnedUniformCompactPointer(std::nullptr_t);

Creates an empty/invalid pointer (used for freelist slots).

Destructor¶

~OwnedUniformCompactPointer();

Destruction Logic (from src/hakka_json_handle.cpp):

~OwnedUniformCompactPointer() {
    if (data == nullptr) return;

    auto type = get_type();
    auto ptr = reinterpret_cast<PointerType>(
        (reinterpret_cast<std::size_t>(data) & ~TYPE_MASK)
    );

    if (type == HAKKA_JSON_INT) {
        std::unique_ptr<JsonIntCompact> int_ptr(reinterpret_cast<JsonIntCompact*>(ptr));
    } else if (type == HAKKA_JSON_FLOAT) {
        std::unique_ptr<JsonFloatCompact> float_ptr(reinterpret_cast<JsonFloatCompact*>(ptr));
    }
    // ... other types

    data = nullptr;  // Prevent reentrancy
}

The destructor: 1. Extracts the type from tagged pointer 2. Removes type tag to recover raw pointer 3. Wraps in unique_ptr for automatic destruction 4. Sets data = nullptr to prevent double-free

Move Semantics¶

OwnedUniformCompactPointer(OwnedUniformCompactPointer &&other) noexcept;
OwnedUniformCompactPointer &operator=(OwnedUniformCompactPointer &&other) noexcept;

Move-Only Semantics: - Copy constructor and assignment are deleted - Only move operations are allowed (transfer of ownership) - Move operations are noexcept for efficiency

Emplace Operations¶

Emplace with Unique Pointer:

template <typename T>
void emplace(std::unique_ptr<T> ptr);

Destroys the current object and constructs a new one in-place.

Implementation:

void emplace(std::unique_ptr<T> ptr) {
    this->~OwnedUniformCompactPointer();
    new (this) OwnedUniformCompactPointer(std::move(ptr));
}

Used by managers to replace freed slots with new objects without reallocating memory.

Emplace with Nullptr:

void emplace(std::nullptr_t);

Destroys the current object and marks the slot as empty.

Pointer Tagging Benefits¶

OwnedUniformCompactPointer: - Uses 4 high bits for type (60 bits remaining for pointer) - No separate type storage required - Cache-friendly: Type and pointer in single 8-byte load

HandleManagerToken: - Uses 2 high bits for manager type (30 bits for index) - Supports up to 1 billion objects per manager - Enables fast manager dispatch without lookup tables

Thread Safety¶

Reference Counting¶

All reference counting operations use atomic operations:

std::atomic<uint64_t> ref_count;

uint64_t inc_ref() const {
    return ref_count.fetch_add(1, std::memory_order_relaxed) + 1;
}

uint64_t dec_ref() const {
    return ref_count.fetch_sub(1, std::memory_order_relaxed) - 1;
}

Memory Ordering: - memory_order_relaxed: Sufficient for reference counting - No inter-thread synchronization needed for count operations - Manager mutex provides synchronization for object access

Manager Synchronization¶

Each manager uses a std::recursive_mutex for thread-safe operations:

mutable std::recursive_mutex mutex_;

Recursive Mutex Benefits: - Allows nested manager operations (e.g., Array containing Objects) - Prevents deadlocks in complex object graphs - Enables safe destruction during reentrant calls

Lock Scope: - Held during object creation, retrieval, and destruction - Released when returning pointers (caller responsible for synchronization) - Supports fine-grained locking at manager level

Thread-Safe Usage Patterns¶

Safe Pattern:

// Each thread creates its own handle
JsonHandleCompact handle1 = JsonIntCompact::create(42);  // Thread 1
JsonHandleCompact handle2 = JsonIntCompact::create(42);  // Thread 2
// Automatic deduplication: both reference same object
// Reference counting is thread-safe

Unsafe Pattern:

// Sharing mutable pointer across threads without synchronization
JsonHandleCompact handle = JsonArrayCompact::create();
UniformCompactPointer mut_ptr = handle.get_mut_ptr();

// Thread 1: modify array
std::get<JsonArrayCompact*>(mut_ptr)->push_back(...);  // UNSAFE

// Thread 2: modify array
std::get<JsonArrayCompact*>(mut_ptr)->push_back(...);  // UNSAFE

// Fix: Use external synchronization
std::mutex array_mutex;
std::lock_guard<std::mutex> lock(array_mutex);
std::get<JsonArrayCompact*>(mut_ptr)->push_back(...);  // SAFE

Best Practices¶

Handle Lifetime Management¶

Prefer RAII-Style Ownership:

void process_json() {
    JsonHandleCompact handle = JsonIntCompact::create(42);
    // Use handle...
}  // Automatic cleanup via destructor

Manual Reference Counting (CPython Integration Only):

// Only when interfacing with Python C API
JsonHandleCompact handle = create_from_python(py_obj);
handle.retain();  // Keep alive for Python
// ... pass to Python ...
// Python will call release() in __del__

Type-Safe Access¶

Always Check Type Before Access:

JsonHandleCompact handle = get_json_value();

if (handle.get_type() == HAKKA_JSON_INT) {
    auto view = handle.get_view();
    if (auto* int_ptr = std::get_if<const JsonIntCompact*>(&view)) {
        auto value = (*int_ptr)->get().value();
    }
}

Use Dispatch Helper for Complex Operations:

auto result = dispatch<std::string>(handle.get_view(),
    [](auto* ptr) { return ptr->dump(0); }
);

if (result.has_value()) {
    std::cout << result.value();
}

Avoid Common Pitfalls¶

Don't Use Handle After Move:

JsonHandleCompact handle1 = JsonIntCompact::create(42);
JsonHandleCompact handle2 = std::move(handle1);
// handle1 is now INVALID (data = 0)
// Don't use handle1!

Don't Mix Handles and Raw Pointers:

// WRONG: Storing raw pointer from handle
auto view = handle.get_view();
auto* ptr = std::get_if<const JsonIntCompact*>(&view);
// ... handle goes out of scope ...
// ptr is now dangling!

// CORRECT: Keep handle alive
JsonHandleCompact handle = get_value();
auto view = handle.get_view();
// Use view while handle is alive

Don't Forget External Synchronization for Mutable Access:

// WRONG: Concurrent modification without lock
auto mut_ptr = array_handle.get_mut_ptr();
// Multiple threads calling push_back() = data race

// CORRECT: Use external mutex
std::mutex mut_mutex;
std::lock_guard lock(mut_mutex);
auto mut_ptr = array_handle.get_mut_ptr();
std::get<JsonArrayCompact*>(mut_ptr)->push_back(...);

Memory Efficiency Considerations¶

Memory Overhead¶

Per-Handle Overhead: - Handle storage: 4 bytes (token) - No vtable pointer: 0 bytes (CRTP eliminates virtual dispatch) - Reference count: 8 bytes (shared across all handles to same object)

Comparison with std::shared_ptr: - std::shared_ptr<T>: 16 bytes (pointer + control block pointer) - JsonHandleCompact: 4 bytes (50% reduction) - Control block amortized across multiple handles

Deduplication Benefits¶

Immutable types (Int, Float, String) automatically share storage:

// Traditional approach: 3 separate allocations
std::vector<std::shared_ptr<int>> values;
values.push_back(std::make_shared<int>(42));
values.push_back(std::make_shared<int>(42));
values.push_back(std::make_shared<int>(42));
// Memory: 3 objects + 3 control blocks

// Hakka JSON: 1 allocation, 3 handles
std::vector<JsonHandleCompact> handles;
handles.push_back(JsonIntCompact::create(42));
handles.push_back(JsonIntCompact::create(42));
handles.push_back(JsonIntCompact::create(42));
// Memory: 1 object (automatic deduplication)

Real-World Impact: - JSON documents often have repeated values (null, true, false, common strings) - Deduplication can reduce memory usage by 60-80% in typical workloads - Reduces OOM probability in large-scale JSON processing

Cache Efficiency¶

Compact Representation Benefits: - 32-bit handles fit more per cache line (16 handles vs 8 pointers) - Improves cache hit rate for handle-heavy data structures - Reduces memory bandwidth consumption

Tagged Pointer Benefits: - Type information in same cache line as pointer - No separate type tag load required - Faster type dispatch and validation

Design Rationale¶

Why 32-bit Handles Instead of 64-bit Pointers?¶

Memory Efficiency: - 50% size reduction per reference - Reduces OOM probability in large datasets - Enables more objects to fit in cache

Index Space: - 30 bits = 1 billion objects per manager - Sufficient for practical use cases - Address space limitation acceptable for memory-constrained scenarios

Type Encoding: - 2 bits encode manager type (4 variants) - Enables fast manager dispatch without lookups - Zero-cost type discrimination

Why Reference Counting Instead of RAII?¶

CPython Integration Requirements: - Python uses explicit reference counting (Py_INCREF/Py_DECREF) - C++ RAII scope-based destruction conflicts with Python's lifetime model - Python objects can outlive C++ stack frames - Explicit retain()/release() mirrors Python's API

Cross-Language Boundary Issues: - RAII assumes single-language ownership model - Python callbacks holding C++ references break RAII assumptions - Circular references across boundary require explicit management - Manual control necessary for predictable destruction timing

Why Tagged Pointers?¶

Memory Savings: - Eliminates separate type storage - 4-byte saving per stored object - Enables type checking without dereferencing

Cache Efficiency: - Type and pointer loaded together - Single cache line access for type dispatch - Reduces memory latency

Platform Assumptions: - Assumes pointer alignment (addresses are 8-byte aligned minimum) - Uses high bits for tagging (safe on x86-64, ARM64) - 60-bit address space sufficient for current architectures

Why Variant-Based Dispatch?¶

Type Safety: - Compile-time type checking - Prevents invalid type casts - Exhaustive pattern matching

Zero-Cost Abstraction: - No runtime overhead vs manual type dispatch - Compiler optimizes variant to switch statement - Inlining opportunities for performance

Maintainability: - Adding new types requires compiler-enforced updates - Self-documenting type relationships - Reduces error-prone manual type checking

Summary¶

The Hakka JSON handle system achieves memory efficiency through:

32-bit compact tokens (50% smaller than 64-bit pointers)
Automatic deduplication (eliminates redundant storage for immutable values)
Tagged pointers (embeds type information without extra storage)
CRTP-based types (eliminates vtable pointer overhead)
Explicit reference counting (enables Python FFI integration)
Thread-safe managers (centralized synchronization with minimal overhead)

These techniques combine to prevent OOM conditions in large-scale JSON workloads while maintaining Python FFI integration.