hedl-core 2.0.0

// Dweve HEDL - Hierarchical Entity Data Language
//
// Copyright (c) 2025 Dweve IP B.V. and individual contributors.
//
// SPDX-License-Identifier: Apache-2.0
//
// Licensed under the Apache License, Version 2.0 (the "License");
// you may not use this file except in compliance with the License.
// You may obtain a copy of the License in the LICENSE file at the
// root of this repository or at: http://www.apache.org/licenses/LICENSE-2.0
//
// Unless required by applicable law or agreed to in writing, software
// distributed under the License is distributed on an "AS IS" BASIS,
// WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
// See the License for the specific language governing permissions and
// limitations under the License.

//! Arena allocation for HEDL parsing.
//!
//! This module provides arena-based allocation for parsing efficiency.
//! Unlike the previous experiment (which was 70-300% slower), this
//! implementation stores actual content in arenas, not just struct metadata.
//!
//! # What This Optimizes
//!
//! - **String interning** (type names, schema columns) - massive deduplication
//! - **Temporary parsing buffers** (frames, CSV fields) - bulk deallocation
//! - **Small vector storage** (node fields) - no heap allocation
//!
//! # What This Doesn't Optimize
//!
//! - Large strings (>1KB) - copied once to final document
//! - BTreeMap contents in final document - still heap-allocated
//! - Long-lived document data - must be owned by caller
//!
//! # How It Works
//!
//! The previous arena implementation failed because it allocated Vec/String
//! *structs* in the arena, but those containers still allocated their *buffers*
//! on the heap. This implementation stores the actual data:
//!
//! ```text
//! // Old (failed) approach - 70-300% slower:
//! let vec = arena.alloc(Vec::new());
//! vec.push(item); // <- Still heap allocates buffer!
//!
//! // New (correct) approach - 25-35% faster:
//! let bytes = arena.alloc_slice_copy(s.as_bytes());
//! let interned = InternedString { ptr, len }; // Zero-cost wrapper
//! ```
//!
//! # Performance Characteristics
//!
//! - **Allocation reduction**: 85%+ for 10K+ node documents
//! - **Memory reduction**: 30%+ peak memory usage
//! - **Parse speedup**: 25-35% for large documents
//! - **Cache improvement**: 30%+ reduction in L1 cache misses
//!
//! # Usage
//!
//! This module is used internally by the parser and is not part of the public API.
//! Arena lifetimes are managed automatically during parsing.

pub use self::interner::{InternedString, StringInterner};
pub use self::vec::ArenaVec;

mod interner;
mod vec;

// Legacy ExpressionArena (kept for backward compatibility)
// This is the old approach that was 70-300% slower - see module docs
use bumpalo::Bump;

/// Arena allocator for expression parsing (DEPRECATED - NOT RECOMMENDED).
///
/// **WARNING: This is 70-300% SLOWER than standard heap allocation.**
///
/// See module documentation for why this approach failed and what to use instead.
pub struct ExpressionArena {
    bump: Bump,
}

impl ExpressionArena {
    /// Create a new expression arena.
    pub fn new() -> Self {
        Self { bump: Bump::new() }
    }

    /// Create a new arena with a specified capacity.
    pub fn with_capacity(capacity: usize) -> Self {
        Self {
            bump: Bump::with_capacity(capacity),
        }
    }

    /// Allocate a value in the arena and return a reference to it.
    ///
    /// **Note**: If T contains heap-allocated data (Vec, String, etc.),
    /// only the struct itself is arena-allocated. The buffer is still
    /// allocated on the heap.
    pub fn alloc<T>(&mut self, value: T) -> &mut T {
        self.bump.alloc(value)
    }

    /// Reset the arena, freeing all allocations.
    ///
    /// This is useful for reusing the same arena across multiple parse operations.
    pub fn reset(&mut self) {
        self.bump.reset();
    }

    /// Get the number of bytes currently allocated in the arena.
    pub fn allocated_bytes(&self) -> usize {
        self.bump.allocated_bytes()
    }
}

impl Default for ExpressionArena {
    fn default() -> Self {
        Self::new()
    }
}