xypriss 9.0.13 → 9.1.1

package/mods/memory-manager/src/types.rs

@@ -0,0 +1,285 @@
+//! # Core Types and Data Structures
+//! 
+//! This module defines all the core types, structures, and enums used throughout
+//! the XyPriss Memory Manager. These types provide a consistent interface for
+//! memory management operations and configuration.
+
+use serde::{Deserialize, Serialize};
+use std::time::{Duration, SystemTime};
+  
+/// Memory pool allocation strategies
+/// 
+/// Different strategies for managing object allocation and deallocation
+/// within memory pools. Each strategy has different performance characteristics
+/// and use cases.
+#[derive(Debug, Clone, Copy, PartialEq, Eq, Serialize, Deserialize)]
+pub enum PoolStrategy {
+    /// Last In, First Out - Most recently returned objects are reused first
+    /// Best for: Temporal locality, cache-friendly access patterns
+    LIFO,
+    
+    /// First In, First Out - Oldest objects are reused first
+    /// Best for: Fair distribution, preventing object starvation
+    FIFO,
+    
+    /// Least Recently Used - Objects not used for longest time are reused first
+    /// Best for: Memory efficiency, automatic cleanup of unused objects
+    LRU,
+    
+    /// Random selection - Objects are selected randomly for reuse
+    /// Best for: Load balancing, avoiding worst-case scenarios
+    Random,
+}
+
+/// Memory pool configuration
+/// 
+/// Configuration parameters for creating and managing memory pools.
+/// These settings control pool behavior, capacity, and cleanup policies.
+#[derive(Debug, Clone, Serialize, Deserialize)]
+pub struct PoolConfig {
+    /// Unique identifier for the pool
+    pub name: String,
+    
+    /// Maximum number of objects the pool can hold
+    pub capacity: usize,
+    
+    /// Allocation strategy to use for this pool
+    pub strategy: PoolStrategy,
+    
+    /// Maximum age of objects in the pool (in seconds)
+    /// Objects older than this will be automatically cleaned up
+    pub max_age_seconds: Option<u64>,
+    
+    /// Maximum idle time before an object is considered for cleanup (in seconds)
+    pub max_idle_seconds: Option<u64>,
+    
+    /// Whether to pre-allocate objects to fill the pool initially
+    pub pre_allocate: bool,
+    
+    /// Whether to enable detailed statistics collection for this pool
+    pub enable_stats: bool,
+    
+    /// Custom metadata associated with this pool
+    pub metadata: Option<String>,
+}
+
+impl Default for PoolConfig {
+    fn default() -> Self {
+        Self {
+            name: "default_pool".to_string(),
+            capacity: 100,
+            strategy: PoolStrategy::LIFO,
+            max_age_seconds: Some(3600), // 1 hour
+            max_idle_seconds: Some(300), // 5 minutes
+            pre_allocate: false,
+            enable_stats: true,
+            metadata: None,
+        }
+    }
+}
+
+/// Information about a memory allocation
+/// 
+/// Tracks metadata about individual memory allocations for monitoring
+/// and debugging purposes.
+#[derive(Debug, Clone, Serialize, Deserialize)]
+pub struct AllocationInfo {
+    /// Unique identifier for this allocation
+    pub id: u64,
+    
+    /// Size of the allocation in bytes
+    pub size: usize,
+    
+    /// Timestamp when the allocation was created
+    pub created_at: SystemTime,
+    
+    /// Timestamp when the allocation was last accessed
+    pub last_accessed: SystemTime,
+    
+    /// Number of times this allocation has been accessed
+    pub access_count: u64,
+    
+    /// Optional tag for categorizing allocations
+    pub tag: Option<String>,
+    
+    /// Stack trace where the allocation occurred (if available)
+    pub stack_trace: Option<String>,
+}
+
+/// Memory usage statistics
+/// 
+/// Comprehensive statistics about memory usage across the entire system.
+/// These stats are useful for monitoring, debugging, and optimization.
+#[derive(Debug, Clone, Serialize, Deserialize)]
+pub struct MemoryStats {
+    /// Total bytes currently allocated
+    pub total_allocated: usize,
+    
+    /// Total bytes deallocated since startup
+    pub total_deallocated: usize,
+    
+    /// Peak memory usage since startup
+    pub peak_usage: usize,
+    
+    /// Number of active memory pools
+    pub active_pools: usize,
+    
+    /// Number of active allocations being tracked
+    pub active_allocations: u64,
+    
+    /// Total number of allocations since startup
+    pub total_allocations: u64,
+    
+    /// Total number of deallocations since startup
+    pub total_deallocations: u64,
+    
+    /// Number of garbage collection cycles performed
+    pub gc_cycles: u64,
+    
+    /// Total time spent in garbage collection (in milliseconds)
+    pub gc_time_ms: u64,
+    
+    /// Current memory pressure level (0.0 to 1.0)
+    pub memory_pressure: f64,
+    
+    /// Timestamp when these stats were collected
+    pub collected_at: SystemTime,
+}
+
+impl Default for MemoryStats {
+    fn default() -> Self {
+        Self {
+            total_allocated: 0,
+            total_deallocated: 0,
+            peak_usage: 0,
+            active_pools: 0,
+            active_allocations: 0,
+            total_allocations: 0,
+            total_deallocations: 0,
+            gc_cycles: 0,
+            gc_time_ms: 0,
+            memory_pressure: 0.0,
+            collected_at: SystemTime::now(),
+        }
+    }
+}
+
+/// Pool-specific statistics
+/// 
+/// Detailed statistics for individual memory pools, useful for
+/// performance analysis and optimization.
+#[derive(Debug, Clone, Serialize, Deserialize)]
+pub struct PoolStats {
+    /// Pool name
+    pub name: String,
+    
+    /// Current number of objects in the pool
+    pub current_size: usize,
+    
+    /// Maximum capacity of the pool
+    pub capacity: usize,
+    
+    /// Total number of objects acquired from this pool
+    pub total_acquisitions: u64,
+    
+    /// Total number of objects returned to this pool
+    pub total_returns: u64,
+    
+    /// Number of cache hits (objects reused from pool)
+    pub cache_hits: u64,
+    
+    /// Number of cache misses (new objects created)
+    pub cache_misses: u64,
+    
+    /// Cache hit ratio (0.0 to 1.0)
+    pub hit_ratio: f64,
+    
+    /// Average object lifetime in the pool (in milliseconds)
+    pub avg_lifetime_ms: u64,
+    
+    /// Timestamp when this pool was created
+    pub created_at: SystemTime,
+    
+    /// Timestamp when these stats were collected
+    pub collected_at: SystemTime,
+}
+
+/// Garbage collection configuration
+/// 
+/// Settings that control when and how garbage collection is performed.
+#[derive(Debug, Clone, Serialize, Deserialize)]
+pub struct GCConfig {
+    /// Enable automatic garbage collection
+    pub enabled: bool,
+    
+    /// Memory pressure threshold to trigger GC (0.0 to 1.0)
+    pub pressure_threshold: f64,
+    
+    /// Interval between GC cycles (in seconds)
+    pub interval_seconds: u64,
+    
+    /// Maximum time to spend in a single GC cycle (in milliseconds)
+    pub max_gc_time_ms: u64,
+    
+    /// Whether to perform aggressive cleanup during GC
+    pub aggressive_cleanup: bool,
+}
+
+impl Default for GCConfig {
+    fn default() -> Self {
+        Self {
+            enabled: true,
+            pressure_threshold: 0.8,
+            interval_seconds: 60,
+            max_gc_time_ms: 100,
+            aggressive_cleanup: false,
+        }
+    }
+}
+
+/// Memory manager configuration
+/// 
+/// Global configuration for the entire memory management system.
+#[derive(Debug, Clone, Serialize, Deserialize)]
+pub struct MemoryManagerConfig {
+    /// Maximum total memory usage (in bytes)
+    pub max_memory_bytes: usize,
+    
+    /// Enable allocation tracking
+    pub enable_tracking: bool,
+    
+    /// Enable detailed logging
+    pub enable_logging: bool,
+    
+    /// Garbage collection configuration
+    pub gc_config: GCConfig,
+    
+    /// Default pool configuration for new pools
+    pub default_pool_config: PoolConfig,
+}
+
+impl Default for MemoryManagerConfig {
+    fn default() -> Self {
+        Self {
+            max_memory_bytes: 1024 * 1024 * 1024, // 1GB
+            enable_tracking: true,
+            enable_logging: false,
+            gc_config: GCConfig::default(),
+            default_pool_config: PoolConfig::default(),
+        }
+    }
+}
+
+/// Handle for a memory pool
+/// 
+/// Opaque handle that can be passed across FFI boundaries to identify
+/// a specific memory pool instance.
+#[derive(Debug, Clone, Copy, PartialEq, Eq, Hash)]
+pub struct PoolHandle(pub u64);
+
+/// Handle for a tracked allocation
+/// 
+/// Opaque handle that can be passed across FFI boundaries to identify
+/// a specific allocation instance.
+#[derive(Debug, Clone, Copy, PartialEq, Eq, Hash)]
+pub struct AllocationHandle(pub u64);

package/mods/memory-manager/src/utils.rs

@@ -0,0 +1,374 @@
+//! # Utility Functions
+//! 
+//! This module provides various utility functions for memory management,
+//! including memory size calculations, formatting helpers, and system
+//! information gathering.
+
+use std::time::{SystemTime, UNIX_EPOCH};
+ 
+/// Format bytes in a human-readable format
+///  
+/// Converts byte counts to human-readable strings with appropriate units
+/// (B, KB, MB, GB, TB).
+/// 
+/// # Arguments
+/// 
+/// * `bytes` - Number of bytes to format
+/// 
+/// # Returns
+/// 
+/// Returns a formatted string with the appropriate unit.
+/// 
+/// # Examples
+/// 
+/// ```rust
+/// use xypriss_memory_manager::utils::format_bytes;
+/// 
+/// assert_eq!(format_bytes(1024), "1.00 KB");
+/// assert_eq!(format_bytes(1048576), "1.00 MB");
+/// assert_eq!(format_bytes(1073741824), "1.00 GB");
+/// ```
+pub fn format_bytes(bytes: usize) -> String {
+    const UNITS: &[&str] = &["B", "KB", "MB", "GB", "TB", "PB"];
+    const THRESHOLD: f64 = 1024.0;
+    
+    if bytes == 0 {
+        return "0 B".to_string();
+    }
+    
+    let bytes_f = bytes as f64;
+    let unit_index = (bytes_f.log10() / THRESHOLD.log10()).floor() as usize;
+    let unit_index = unit_index.min(UNITS.len() - 1);
+    
+    let value = bytes_f / THRESHOLD.powi(unit_index as i32);
+    
+    format!("{:.2} {}", value, UNITS[unit_index])
+}
+
+/// Calculate percentage with proper handling of edge cases
+/// 
+/// # Arguments
+/// 
+/// * `value` - The value to calculate percentage for
+/// * `total` - The total value (100%)
+/// 
+/// # Returns
+/// 
+/// Returns the percentage as a float between 0.0 and 100.0.
+pub fn calculate_percentage(value: usize, total: usize) -> f64 {
+    if total == 0 {
+        return 0.0;
+    }
+    
+    (value as f64 / total as f64) * 100.0
+}
+
+/// Get current timestamp in milliseconds since Unix epoch
+/// 
+/// # Returns
+/// 
+/// Returns the current timestamp in milliseconds.
+pub fn current_timestamp_ms() -> u64 {
+    SystemTime::now()
+        .duration_since(UNIX_EPOCH)
+        .unwrap_or_default()
+        .as_millis() as u64
+}
+
+/// Estimate the size of a generic object in memory
+/// 
+/// This is a rough estimation and may not be accurate for all types.
+/// For more precise measurements, consider using specialized tools.
+/// 
+/// # Arguments
+/// 
+/// * `_obj` - Reference to the object to estimate
+/// 
+/// # Returns
+/// 
+/// Returns an estimated size in bytes.
+pub fn estimate_object_size<T>(_obj: &T) -> usize {
+    std::mem::size_of::<T>()
+}
+
+/// Round up to the nearest power of 2
+/// 
+/// Useful for memory allocation alignment and pool sizing.
+/// 
+/// # Arguments
+/// 
+/// * `value` - Value to round up
+/// 
+/// # Returns
+/// 
+/// Returns the next power of 2 greater than or equal to the input.
+pub fn next_power_of_2(value: usize) -> usize {
+    if value <= 1 {
+        return 1;
+    }
+    
+    let mut power = 1;
+    while power < value {
+        power <<= 1;
+    }
+    power
+}
+
+/// Check if a value is a power of 2
+/// 
+/// # Arguments
+/// 
+/// * `value` - Value to check
+/// 
+/// # Returns
+/// 
+/// Returns true if the value is a power of 2.
+pub fn is_power_of_2(value: usize) -> bool {
+    value != 0 && (value & (value - 1)) == 0
+}
+
+/// Calculate memory alignment for a given size
+/// 
+/// Returns the appropriate alignment for memory allocations of the given size.
+/// 
+/// # Arguments
+/// 
+/// * `size` - Size in bytes
+/// 
+/// # Returns
+/// 
+/// Returns the recommended alignment in bytes.
+pub fn calculate_alignment(size: usize) -> usize {
+    if size >= 8 {
+        8
+    } else if size >= 4 {
+        4
+    } else if size >= 2 {
+        2
+    } else {
+        1
+    }
+}
+
+/// Get system page size
+/// 
+/// Returns the system's memory page size, which is useful for
+/// memory allocation alignment and optimization.
+/// 
+/// # Returns
+/// 
+/// Returns the page size in bytes, or 4096 as a fallback.
+pub fn get_page_size() -> usize {
+    // On Unix systems, we could use libc::sysconf(libc::_SC_PAGESIZE)
+    // For now, return a common default
+    4096
+}
+
+/// Calculate optimal pool capacity based on object size and memory constraints
+/// 
+/// This function helps determine an appropriate pool capacity based on
+/// the size of objects being pooled and available memory.
+/// 
+/// # Arguments
+/// 
+/// * `object_size` - Size of each object in bytes
+/// * `max_memory` - Maximum memory to use for the pool in bytes
+/// * `min_capacity` - Minimum pool capacity
+/// * `max_capacity` - Maximum pool capacity
+/// 
+/// # Returns
+/// 
+/// Returns the recommended pool capacity.
+pub fn calculate_optimal_pool_capacity(
+    object_size: usize,
+    max_memory: usize,
+    min_capacity: usize,
+    max_capacity: usize,
+) -> usize {
+    if object_size == 0 {
+        return min_capacity;
+    }
+    
+    let theoretical_capacity = max_memory / object_size;
+    theoretical_capacity.max(min_capacity).min(max_capacity)
+}
+
+/// Generate a simple hash for string keys
+/// 
+/// This is a basic hash function for use in internal data structures.
+/// Not cryptographically secure.
+/// 
+/// # Arguments
+/// 
+/// * `key` - String to hash
+/// 
+/// # Returns
+/// 
+/// Returns a hash value as u64.
+pub fn simple_hash(key: &str) -> u64 {
+    let mut hash = 0xcbf29ce484222325u64; // FNV offset basis
+    
+    for byte in key.bytes() {
+        hash ^= byte as u64;
+        hash = hash.wrapping_mul(0x100000001b3); // FNV prime
+    }
+    
+    hash
+}
+
+/// Memory pressure level classification
+/// 
+/// Classifies memory pressure into discrete levels for easier decision making.
+#[derive(Debug, Clone, Copy, PartialEq, Eq)]
+pub enum MemoryPressureLevel {
+    /// Low pressure (0.0 - 0.5)
+    Low,
+    /// Medium pressure (0.5 - 0.8)
+    Medium,
+    /// High pressure (0.8 - 0.95)
+    High,
+    /// Critical pressure (0.95 - 1.0)
+    Critical,
+}
+
+impl MemoryPressureLevel {
+    /// Convert memory pressure ratio to pressure level
+    /// 
+    /// # Arguments
+    /// 
+    /// * `pressure` - Memory pressure ratio (0.0 to 1.0)
+    /// 
+    /// # Returns
+    /// 
+    /// Returns the corresponding pressure level.
+    pub fn from_ratio(pressure: f64) -> Self {
+        if pressure < 0.5 {
+            Self::Low
+        } else if pressure < 0.8 {
+            Self::Medium
+        } else if pressure < 0.95 {
+            Self::High
+        } else {
+            Self::Critical
+        }
+    }
+    
+    /// Get the string representation of the pressure level
+    pub fn as_str(&self) -> &'static str {
+        match self {
+            Self::Low => "Low",
+            Self::Medium => "Medium",
+            Self::High => "High",
+            Self::Critical => "Critical",
+        }
+    }
+    
+    /// Check if this pressure level requires immediate action
+    pub fn requires_action(&self) -> bool {
+        matches!(self, Self::High | Self::Critical)
+    }
+}
+
+/// Configuration validation utilities
+pub mod validation {
+    use crate::error::{MemoryError, Result};
+    
+    /// Validate pool capacity
+    pub fn validate_pool_capacity(capacity: usize) -> Result<()> {
+        if capacity == 0 {
+            return Err(MemoryError::InvalidConfiguration {
+                parameter: "capacity".to_string(),
+                reason: "capacity must be greater than 0".to_string(),
+            });
+        }
+        
+        if capacity > 1_000_000 {
+            return Err(MemoryError::InvalidConfiguration {
+                parameter: "capacity".to_string(),
+                reason: "capacity is too large (max: 1,000,000)".to_string(),
+            });
+        }
+        
+        Ok(())
+    }
+    
+    /// Validate memory size
+    pub fn validate_memory_size(size: usize, max_size: usize) -> Result<()> {
+        if size > max_size {
+            return Err(MemoryError::AllocationTooLarge {
+                size,
+                max_size,
+            });
+        }
+        
+        Ok(())
+    }
+    
+    /// Validate percentage value
+    pub fn validate_percentage(value: f64, name: &str) -> Result<()> {
+        if value < 0.0 || value > 1.0 {
+            return Err(MemoryError::InvalidConfiguration {
+                parameter: name.to_string(),
+                reason: "value must be between 0.0 and 1.0".to_string(),
+            });
+        }
+        
+        Ok(())
+    }
+}
+
+#[cfg(test)]
+mod tests {
+    use super::*;
+    
+    #[test]
+    fn test_format_bytes() {
+        assert_eq!(format_bytes(0), "0 B");
+        assert_eq!(format_bytes(512), "512.00 B");
+        assert_eq!(format_bytes(1024), "1.00 KB");
+        assert_eq!(format_bytes(1048576), "1.00 MB");
+        assert_eq!(format_bytes(1073741824), "1.00 GB");
+    }
+    
+    #[test]
+    fn test_calculate_percentage() {
+        assert_eq!(calculate_percentage(0, 100), 0.0);
+        assert_eq!(calculate_percentage(50, 100), 50.0);
+        assert_eq!(calculate_percentage(100, 100), 100.0);
+        assert_eq!(calculate_percentage(100, 0), 0.0); // Edge case
+    }
+    
+    #[test]
+    fn test_next_power_of_2() {
+        assert_eq!(next_power_of_2(0), 1);
+        assert_eq!(next_power_of_2(1), 1);
+        assert_eq!(next_power_of_2(2), 2);
+        assert_eq!(next_power_of_2(3), 4);
+        assert_eq!(next_power_of_2(8), 8);
+        assert_eq!(next_power_of_2(9), 16);
+    }
+    
+    #[test]
+    fn test_is_power_of_2() {
+        assert!(!is_power_of_2(0));
+        assert!(is_power_of_2(1));
+        assert!(is_power_of_2(2));
+        assert!(!is_power_of_2(3));
+        assert!(is_power_of_2(4));
+        assert!(is_power_of_2(8));
+        assert!(!is_power_of_2(9));
+    }
+    
+    #[test]
+    fn test_memory_pressure_level() {
+        assert_eq!(MemoryPressureLevel::from_ratio(0.3), MemoryPressureLevel::Low);
+        assert_eq!(MemoryPressureLevel::from_ratio(0.6), MemoryPressureLevel::Medium);
+        assert_eq!(MemoryPressureLevel::from_ratio(0.9), MemoryPressureLevel::High);
+        assert_eq!(MemoryPressureLevel::from_ratio(0.98), MemoryPressureLevel::Critical);
+        
+        assert!(!MemoryPressureLevel::Low.requires_action());
+        assert!(!MemoryPressureLevel::Medium.requires_action());
+        assert!(MemoryPressureLevel::High.requires_action());
+        assert!(MemoryPressureLevel::Critical.requires_action());
+    }
+}

package/mods/security/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2025 NEHONIX INC
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.