zipora 3.1.5

//! Error Handling System for Zipora
//!
//! This module provides distributed verification macros and error handling patterns
//! using fail-fast philosophy with rich contextual error reporting throughout data structures.


//! Verification macros providing fail-fast error handling with rich contextual information

/// Fatal error macro for immediate termination
/// Prints error context and terminates the program immediately
#[macro_export]
macro_rules! zipora_die {
    ($fmt:expr $(, $args:expr)*) => {
        {
            eprintln!("{}:{}: in {}: die: {} !",
                file!(), line!(),
                std::any::type_name::<()>(),
                format!($fmt $(, $args)*));
            std::process::abort();
        }
    };
}

/// Runtime verification macro with fail-fast behavior
/// Checks condition and aborts with context if false
/// In test mode, panics instead of aborting to allow test recovery
#[macro_export]
macro_rules! zipora_verify {
    ($expr:expr) => {
        if !($expr) {
            let msg = format!("{}:{}: verify({}) failed !",
                file!(), line!(), stringify!($expr));
            eprintln!("{}", msg);
            #[cfg(test)]
            panic!("{}", msg);
            #[cfg(not(test))]
            std::process::abort();
        }
    };
    ($expr:expr, $fmt:expr $(, $args:expr)*) => {
        if !($expr) {
            let msg = format!("{}:{}: verify({}) failed: {} !",
                file!(), line!(), stringify!($expr),
                format!($fmt $(, $args)*));
            eprintln!("{}", msg);
            #[cfg(test)]
            panic!("{}", msg);
            #[cfg(not(test))]
            std::process::abort();
        }
    };
}

/// Memory allocation verification with size context
#[macro_export]
macro_rules! zipora_verify_alloc {
    ($ptr:expr, $size:expr) => {
        zipora_verify!(!$ptr.is_null(), "allocation of {} bytes failed", $size);
    };
}

/// Alignment verification for memory operations
#[macro_export]
macro_rules! zipora_verify_aligned {
    ($ptr:expr, $align:expr) => {
        zipora_verify!(($ptr as usize) % $align == 0, 
            "pointer {:p} not aligned to {} bytes", $ptr, $align);
    };
    ($size:expr, $align:expr) => {
        zipora_verify!($size % $align == 0,
            "size {} not aligned to {} bytes", $size, $align);
    };
}

/// Power-of-2 verification for sizes and alignments
#[macro_export]
macro_rules! zipora_verify_pow2 {
    ($val:expr) => {
        zipora_verify!(($val & ($val - 1)) == 0,
            "value {} (0x{:X}) is not a power of 2", $val, $val);
    };
}

/// Comparison verification macros with value display
#[macro_export]
macro_rules! zipora_verify_eq {
    ($x:expr, $y:expr) => {
        {
            let x_val = $x;
            let y_val = $y;
            zipora_verify!(x_val == y_val, "{} != {}", x_val, y_val);
        }
    };
}

#[macro_export]
macro_rules! zipora_verify_ne {
    ($x:expr, $y:expr) => {
        {
            let x_val = $x;
            let y_val = $y;
            zipora_verify!(x_val != y_val, "{} == {}", x_val, y_val);
        }
    };
}

#[macro_export]
macro_rules! zipora_verify_lt {
    ($x:expr, $y:expr) => {
        {
            let x_val = $x;
            let y_val = $y;
            zipora_verify!(x_val < y_val, "{} >= {}", x_val, y_val);
        }
    };
}

#[macro_export]
macro_rules! zipora_verify_le {
    ($x:expr, $y:expr) => {
        {
            let x_val = $x;
            let y_val = $y;
            zipora_verify!(x_val <= y_val, "{} > {}", x_val, y_val);
        }
    };
}

#[macro_export]
macro_rules! zipora_verify_gt {
    ($x:expr, $y:expr) => {
        {
            let x_val = $x;
            let y_val = $y;
            zipora_verify!(x_val > y_val, "{} <= {}", x_val, y_val);
        }
    };
}

#[macro_export]
macro_rules! zipora_verify_ge {
    ($x:expr, $y:expr) => {
        {
            let x_val = $x;
            let y_val = $y;
            zipora_verify!(x_val >= y_val, "{} < {}", x_val, y_val);
        }
    };
}

/// Zero verification - common pattern
#[macro_export]
macro_rules! zipora_verify_ez {
    ($x:expr) => {
        {
            let x_val = $x;
            zipora_verify!(x_val == 0, "expected 0, got {}", x_val);
        }
    };
}

/// Non-null pointer verification
#[macro_export]
macro_rules! zipora_verify_not_null {
    ($ptr:expr) => {
        zipora_verify!(!$ptr.is_null(), "pointer is null");
    };
}

/// Bounds checking with context
#[macro_export]
macro_rules! zipora_verify_bounds {
    ($index:expr, $size:expr) => {
        {
            let idx = $index;
            let sz = $size;
            zipora_verify!(idx < sz, "index {} out of bounds for size {}", idx, sz);
        }
    };
}

/// Range verification 
#[macro_export]
macro_rules! zipora_verify_range {
    ($start:expr, $end:expr, $size:expr) => {
        {
            let s = $start;
            let e = $end;
            let sz = $size;
            zipora_verify!(s <= e, "invalid range: start {} > end {}", s, e);
            zipora_verify!(e <= sz, "range end {} exceeds size {}", e, sz);
        }
    };
}

/// Capacity verification for container operations
#[macro_export]
macro_rules! zipora_verify_capacity {
    ($current:expr, $required:expr, $max:expr) => {
        {
            let curr = $current;
            let req = $required;
            let max_cap = $max;
            zipora_verify!(req <= max_cap, 
                "required capacity {} exceeds maximum {}", req, max_cap);
            zipora_verify!(curr <= req,
                "current size {} exceeds required capacity {}", curr, req);
        }
    };
}

/// System call result verification
#[macro_export]
macro_rules! zipora_verify_syscall {
    ($result:expr, $syscall:expr) => {
        {
            let res = $result;
            zipora_verify!(res == 0, "syscall {} failed with error {}: {}", 
                $syscall, res, std::io::Error::last_os_error());
        }
    };
}

/// Export convenience functions for use in generic contexts
pub fn verify_alignment(ptr: *const u8, align: usize) {
    zipora_verify_aligned!(ptr, align);
}

pub fn verify_power_of_2(val: usize) {
    zipora_verify_pow2!(val);
}

pub fn verify_allocation_success(ptr: *const u8, size: usize) {
    zipora_verify_alloc!(ptr, size);
}

pub fn verify_bounds_check(index: usize, size: usize) {
    zipora_verify_bounds!(index, size);
}

pub fn verify_range_check(start: usize, end: usize, size: usize) {
    zipora_verify_range!(start, end, size);
}

#[cfg(test)]
mod tests {
    use super::*;

    #[test]
    fn test_verify_macros_success() {
        // These should not panic
        zipora_verify!(true);
        zipora_verify!(1 == 1, "should be equal");
        zipora_verify_eq!(42, 42);
        zipora_verify_ne!(1, 2);
        zipora_verify_lt!(1, 2);
        zipora_verify_le!(1, 1);
        zipora_verify_gt!(2, 1);
        zipora_verify_ge!(2, 2);
        zipora_verify_ez!(0);
        zipora_verify_bounds!(5, 10);
        zipora_verify_range!(2, 8, 10);
        zipora_verify_pow2!(16);
    }

    #[test]
    fn test_verify_alignment() {
        let aligned_ptr = Box::into_raw(Box::new(42u64)) as *const u8;
        verify_alignment(aligned_ptr, 8); // Should not panic for u64 alignment
        // SAFETY: aligned_ptr is from Box::into_raw above (line 268), reconstructing same Box for cleanup
        unsafe { Box::from_raw(aligned_ptr as *mut u64) }; // Cleanup
    }

    #[test]
    fn test_verify_power_of_2() {
        verify_power_of_2(1);
        verify_power_of_2(2);
        verify_power_of_2(4);
        verify_power_of_2(8);
        verify_power_of_2(1024);
    }

    #[test]
    fn test_verify_bounds() {
        verify_bounds_check(0, 10);
        verify_bounds_check(5, 10);
        verify_bounds_check(9, 10);
    }

    #[test]
    fn test_verify_range() {
        verify_range_check(0, 5, 10);
        verify_range_check(2, 8, 10);
        verify_range_check(0, 10, 10);
    }

    // Note: Tests that would cause abort() are not included as they would terminate the test process
    // These macros are designed to fail-fast in production
}