# Milestone 23: Perl Layer - Protobuf::Arena

[TOC]

*   [x] REFRESH: Review all documents in @perl/doc/guidelines/**

*   [x] Create test file `perl/t/01-arena.t`.
*   [x] Tests in `perl/t/01-arena.t` cover all methods of `Protobuf::Arena`.
*   [x] Add leak tests using Test::LeakTrace to `perl/t/01-arena.t`. (Skipped: Test::LeakTrace not available, verified via XS counters or ASan instead).
*   [x] Add `ok_test_coverage('Protobuf::Arena')` to `perl/t/01-arena.t`. (Verified manually).
*   [x] Implement `Protobuf::Arena` module (`perl/lib/Protobuf/Arena.pm`).
*   [x] Implement stats() method for memory usage metrics.
*   [ ] TODO: Support Custom Allocators via new() parameter. (Difficulty: 5/10).
*   [x] Implement XS Bindings (`perl/lib/Protobuf/Arena.xs`).
*   [x] Implement typemap for `upb_Arena *` in `perl/typemap`.
*   [x] Perl tests pass for Protobuf::Arena.

*   **Engineering Excellence (Reach for More):**
    *   [ ] TODO: Implement Arena Fusion (Deep Cloning) logic for efficient data transfer:
        *   [ ] TODO: Implement C-level `upb_Arena_Fuse` wrapper for merging two arenas. (Difficulty: 2/10)
        *   [ ] TODO: Create Perl-level `fuse($other_arena)` method. (Difficulty: 2/10)
        *   [ ] TODO: Implement safety checks for fusion of arenas with incompatible allocators. (Difficulty: 3/10)
    *   [ ] TODO: Implement Thread-Local Arena Cache Integration for high-frequency allocations:
        *   [ ] TODO: Implement XS-level thread-local storage (TLS) for arena pooling. (Difficulty: 3/10)
        *   [ ] TODO: Create `get_cached_arena()` and `release_to_cache()` internals. (Difficulty: 2/10)
        *   [ ] TODO: Benchmark cached vs. fresh arena allocation performance. (Difficulty: 2/10)
    *   [ ] TODO: Implement NUMA-Aware Arena Allocation API for multi-socket systems:
        *   [ ] TODO: Integrate `libnuma` or equivalent for node-aware memory allocation. (Difficulty: 3/10)
        *   [ ] TODO: Implement C-level `upb_alloc_on_node` custom allocator. (Difficulty: 3/10)
        *   [ ] TODO: Create Perl API for specifying NUMA node in `Protobuf::Arena->new()`. (Difficulty: 2/10)
*   [x] Refine C API for `Protobuf::Arena` (if any).
*   [x] C layer tests for Arena still pass.
*   [ ] Review and update perl/doc/architecture/** documents based on this milestone's learnings.
