oxirs_core/

interning.rs

//! String interning system for performance optimization
//!
//! This module provides efficient string interning for commonly used strings
//! like IRIs, datatype URIs, and other RDF terms. String interning reduces
//! memory usage and improves comparison performance by ensuring that equal
//! strings are stored only once and can be compared by pointer equality.
//!
//! ## Performance Monitoring
//!
//! The interner integrates SciRS2-core metrics for comprehensive monitoring:
//! - Cache hit/miss rates
//! - Intern operation timing
//! - Memory usage tracking
//! - Deduplication effectiveness

use scirs2_core::metrics::{Counter, Histogram, Timer};
use std::collections::HashMap;
use std::hash::{Hash, Hasher};
use std::sync::{Arc, RwLock, Weak};

/// A thread-safe string interner that deduplicates strings with ID mapping
///
/// Integrates SciRS2-core metrics for production-grade performance monitoring:
/// - Automatic cache hit/miss tracking
/// - Intern operation timing
/// - Memory usage histograms
/// - Deduplication effectiveness metrics
pub struct StringInterner {
    /// Map from string content to weak references of interned strings
    strings: RwLock<HashMap<String, Weak<str>>>,
    /// Bidirectional mapping between strings and numeric IDs
    string_to_id: RwLock<HashMap<String, u32>>,
    /// Map from ID back to string
    id_to_string: RwLock<HashMap<u32, Arc<str>>>,
    /// Next available ID
    next_id: AtomicU32,
    /// Statistics for monitoring performance
    stats: RwLock<InternerStats>,
    /// SciRS2 metrics
    cache_hit_counter: Arc<Counter>,
    cache_miss_counter: Arc<Counter>,
    intern_timer: Arc<Timer>,
    string_length_histogram: Arc<Histogram>,
    memory_usage_histogram: Arc<Histogram>,
}

/// Atomic 32-bit unsigned integer type for thread-safe ID generation
use std::sync::atomic::AtomicU32;

/// Statistics for monitoring string interner performance
#[derive(Debug, Clone, Default)]
pub struct InternerStats {
    pub total_requests: usize,
    pub cache_hits: usize,
    pub cache_misses: usize,
    pub total_strings_stored: usize,
    pub memory_saved_bytes: usize,
}

/// Memory usage statistics for performance monitoring
#[derive(Debug, Clone)]
pub struct MemoryUsage {
    pub interned_strings: usize,
    pub id_mappings: usize,
    pub estimated_memory_bytes: usize,
    pub memory_saved_bytes: usize,
    pub compression_ratio: f64,
}

/// SciRS2 metrics for interner performance
#[derive(Debug, Clone)]
pub struct InternerMetrics {
    /// Total cache hits
    pub cache_hits: u64,
    /// Total cache misses
    pub cache_misses: u64,
    /// Total intern requests
    pub total_requests: u64,
    /// Cache hit ratio (0.0 to 1.0)
    pub hit_ratio: f64,
    /// Average intern operation time in seconds
    pub avg_intern_time_secs: f64,
    /// Total timing observations recorded
    pub total_intern_observations: u64,
    /// Average string length
    pub avg_string_length: f64,
    /// Total memory tracked in bytes
    pub total_memory_tracked_bytes: u64,
}

impl InternerStats {
    pub fn hit_ratio(&self) -> f64 {
        if self.total_requests == 0 {
            0.0
        } else {
            self.cache_hits as f64 / self.total_requests as f64
        }
    }
}

impl StringInterner {
    /// Create a new string interner with ID mapping and SciRS2 metrics
    ///
    /// Automatically tracks:
    /// - Cache hit/miss rates for intern operations
    /// - Operation timing for performance analysis
    /// - String length distribution
    /// - Memory usage patterns
    pub fn new() -> Self {
        Self::with_capacity(1024) // Default capacity for typical usage
    }

    /// Create a new string interner with specified capacity
    ///
    /// Pre-allocates HashMaps to the given capacity to reduce reallocation overhead.
    /// Initializes all SciRS2 metrics for comprehensive monitoring.
    pub fn with_capacity(capacity: usize) -> Self {
        StringInterner {
            strings: RwLock::new(HashMap::with_capacity(capacity)),
            string_to_id: RwLock::new(HashMap::with_capacity(capacity)),
            id_to_string: RwLock::new(HashMap::with_capacity(capacity)),
            next_id: AtomicU32::new(0),
            stats: RwLock::new(InternerStats::default()),
            cache_hit_counter: Arc::new(Counter::new("interner.cache_hits".to_string())),
            cache_miss_counter: Arc::new(Counter::new("interner.cache_misses".to_string())),
            intern_timer: Arc::new(Timer::new("interner.intern_time".to_string())),
            string_length_histogram: Arc::new(Histogram::new("interner.string_length".to_string())),
            memory_usage_histogram: Arc::new(Histogram::new("interner.memory_usage".to_string())),
        }
    }

    /// Intern a string, returning an `Arc<str>` that can be cheaply cloned and compared
    ///
    /// This operation is tracked with SciRS2 metrics:
    /// - Cache hits/misses
    /// - Operation timing
    /// - String length distribution
    pub fn intern(&self, s: &str) -> Arc<str> {
        let _guard = self.intern_timer.start();

        // Track string length
        self.string_length_histogram.observe(s.len() as f64);

        // Fast path: try to get existing string with read lock
        {
            let strings = self
                .strings
                .read()
                .unwrap_or_else(|poisoned| poisoned.into_inner());
            if let Some(weak_ref) = strings.get(s) {
                if let Some(arc_str) = weak_ref.upgrade() {
                    // Update stats
                    self.cache_hit_counter.inc();
                    {
                        let mut stats = self
                            .stats
                            .write()
                            .unwrap_or_else(|poisoned| poisoned.into_inner());
                        stats.total_requests += 1;
                        stats.cache_hits += 1;
                    }
                    return arc_str;
                }
            }
        }

        // Slow path: need to create new string with write lock
        let mut strings = self
            .strings
            .write()
            .unwrap_or_else(|poisoned| poisoned.into_inner());

        // Double-check in case another thread added it while we were waiting
        if let Some(weak_ref) = strings.get(s) {
            if let Some(arc_str) = weak_ref.upgrade() {
                // Update stats
                self.cache_hit_counter.inc();
                drop(strings); // Release write lock early
                {
                    let mut stats = self
                        .stats
                        .write()
                        .unwrap_or_else(|poisoned| poisoned.into_inner());
                    stats.total_requests += 1;
                    stats.cache_hits += 1;
                }
                return arc_str;
            }
        }

        // Create new interned string
        let arc_str: Arc<str> = Arc::from(s);
        let weak_ref = Arc::downgrade(&arc_str);
        strings.insert(s.to_string(), weak_ref);

        // Update stats
        self.cache_miss_counter.inc();
        drop(strings); // Release write lock early
        {
            let mut stats = self
                .stats
                .write()
                .unwrap_or_else(|poisoned| poisoned.into_inner());
            stats.total_requests += 1;
            stats.cache_misses += 1;
            stats.total_strings_stored += 1;
            stats.memory_saved_bytes += s.len(); // Approximate memory saved on subsequent hits
        }

        arc_str
    }

    /// Intern a string and return both the `Arc<str>` and its numeric ID
    pub fn intern_with_id(&self, s: &str) -> (Arc<str>, u32) {
        // Fast path: check if we already have this string and its ID
        {
            let string_to_id = self
                .string_to_id
                .read()
                .unwrap_or_else(|poisoned| poisoned.into_inner());
            if let Some(&id) = string_to_id.get(s) {
                // We have the ID, now get the Arc<str>
                let id_to_string = self
                    .id_to_string
                    .read()
                    .unwrap_or_else(|poisoned| poisoned.into_inner());
                if let Some(arc_str) = id_to_string.get(&id) {
                    // Update stats
                    {
                        let mut stats = self
                            .stats
                            .write()
                            .unwrap_or_else(|poisoned| poisoned.into_inner());
                        stats.total_requests += 1;
                        stats.cache_hits += 1;
                    }
                    return (arc_str.clone(), id);
                }
            }
        }

        // Slow path: need to create new entry. Interning the string itself is
        // already race-safe and dedups the `Arc<str>` allocation, so do that
        // first; then take the `string_to_id` write lock and re-check under
        // it before minting a new id -- mirroring `intern()`'s
        // double-checked-locking pattern. Without this re-check, two
        // concurrent callers could both miss the fast-path read-lock check
        // above, each `fetch_add` a *distinct* id for the same string, and
        // both insert into the maps (last writer wins), leaving
        // `string_to_id` pointing at one id while `id_to_string` retains a
        // stale duplicate entry for the other -- violating the interner's
        // same-string-implies-same-id invariant.
        let arc_str = self.intern(s); // This will handle the string interning

        let mut string_to_id = self
            .string_to_id
            .write()
            .unwrap_or_else(|poisoned| poisoned.into_inner());

        // Double-check: another thread may have raced us and already
        // assigned an id to this string while we were interning it / waiting
        // for this lock.
        if let Some(&existing_id) = string_to_id.get(s) {
            return (arc_str, existing_id);
        }

        let id = self
            .next_id
            .fetch_add(1, std::sync::atomic::Ordering::Relaxed);
        string_to_id.insert(s.to_string(), id);
        drop(string_to_id);

        {
            let mut id_to_string = self
                .id_to_string
                .write()
                .unwrap_or_else(|poisoned| poisoned.into_inner());
            id_to_string.insert(id, arc_str.clone());
        }

        (arc_str, id)
    }

    /// Get the ID for a string if it's already interned
    pub fn get_id(&self, s: &str) -> Option<u32> {
        let string_to_id = self
            .string_to_id
            .read()
            .unwrap_or_else(|poisoned| poisoned.into_inner());
        string_to_id.get(s).copied()
    }

    /// Get the string for an ID if it exists
    pub fn get_string(&self, id: u32) -> Option<Arc<str>> {
        let id_to_string = self
            .id_to_string
            .read()
            .unwrap_or_else(|poisoned| poisoned.into_inner());
        id_to_string.get(&id).cloned()
    }

    /// Get all ID mappings (useful for serialization/debugging)
    pub fn get_all_mappings(&self) -> Vec<(u32, Arc<str>)> {
        let id_to_string = self
            .id_to_string
            .read()
            .unwrap_or_else(|poisoned| poisoned.into_inner());
        id_to_string
            .iter()
            .map(|(&id, s)| (id, s.clone()))
            .collect()
    }

    /// Clean up expired weak references to save memory
    ///
    /// Returns the number of entries cleaned up
    pub fn cleanup(&self) -> usize {
        let mut strings = self
            .strings
            .write()
            .unwrap_or_else(|poisoned| poisoned.into_inner());
        let before = strings.len();
        strings.retain(|_, weak_ref| weak_ref.strong_count() > 0);
        let after = strings.len();
        before - after
    }

    /// Get current statistics
    pub fn stats(&self) -> InternerStats {
        self.stats
            .read()
            .unwrap_or_else(|poisoned| poisoned.into_inner())
            .clone()
    }

    /// Get the number of unique strings currently stored
    pub fn len(&self) -> usize {
        // Return the maximum of both counts to handle mixed usage
        let id_count = self
            .string_to_id
            .read()
            .unwrap_or_else(|poisoned| poisoned.into_inner())
            .len();
        let string_count = self
            .strings
            .read()
            .unwrap_or_else(|poisoned| poisoned.into_inner())
            .len();
        std::cmp::max(id_count, string_count)
    }

    /// Get the number of strings with ID mappings
    pub fn id_mapping_count(&self) -> usize {
        self.string_to_id
            .read()
            .unwrap_or_else(|poisoned| poisoned.into_inner())
            .len()
    }

    /// Check if the interner is empty
    pub fn is_empty(&self) -> bool {
        self.strings
            .read()
            .unwrap_or_else(|poisoned| poisoned.into_inner())
            .is_empty()
    }

    /// Batch intern multiple strings for improved performance
    /// Returns a Vec of `Arc<str>` in the same order as input
    pub fn intern_batch(&self, strings: &[&str]) -> Vec<Arc<str>> {
        let mut result = Vec::with_capacity(strings.len());
        let mut to_create = Vec::new();

        // First pass: collect existing strings with read lock
        {
            let string_map = self
                .strings
                .read()
                .unwrap_or_else(|poisoned| poisoned.into_inner());
            for &s in strings {
                if let Some(weak_ref) = string_map.get(s) {
                    if let Some(arc_str) = weak_ref.upgrade() {
                        result.push(arc_str);
                        continue;
                    }
                }
                to_create.push((result.len(), s));
                result.push(Arc::from("")); // Placeholder
            }
        }

        // Second pass: create missing strings with write lock
        if !to_create.is_empty() {
            let mut string_map = self
                .strings
                .write()
                .unwrap_or_else(|poisoned| poisoned.into_inner());
            let mut stats = self
                .stats
                .write()
                .unwrap_or_else(|poisoned| poisoned.into_inner());

            for (index, s) in to_create {
                // Double-check in case another thread added it
                if let Some(weak_ref) = string_map.get(s) {
                    if let Some(arc_str) = weak_ref.upgrade() {
                        result[index] = arc_str;
                        stats.cache_hits += 1;
                        continue;
                    }
                }

                // Create new interned string
                let arc_str: Arc<str> = Arc::from(s);
                let weak_ref = Arc::downgrade(&arc_str);
                string_map.insert(s.to_string(), weak_ref);
                result[index] = arc_str;

                stats.cache_misses += 1;
                stats.total_strings_stored += 1;
                stats.memory_saved_bytes += s.len();
            }

            stats.total_requests += strings.len();
        }

        result
    }

    /// Prefetch strings into the interner cache for improved performance
    /// This is useful when you know you'll need certain strings soon
    pub fn prefetch(&self, strings: &[&str]) {
        let _ = self.intern_batch(strings);
    }

    /// Get memory usage statistics for performance monitoring
    pub fn memory_usage(&self) -> MemoryUsage {
        let string_map_size = self
            .strings
            .read()
            .unwrap_or_else(|poisoned| poisoned.into_inner())
            .len();
        let id_map_size = self
            .string_to_id
            .read()
            .unwrap_or_else(|poisoned| poisoned.into_inner())
            .len();
        let stats = self
            .stats
            .read()
            .unwrap_or_else(|poisoned| poisoned.into_inner());

        MemoryUsage {
            interned_strings: string_map_size,
            id_mappings: id_map_size,
            estimated_memory_bytes: string_map_size * 64 + id_map_size * 8, // Rough estimate
            memory_saved_bytes: stats.memory_saved_bytes,
            compression_ratio: if stats.memory_saved_bytes > 0 {
                stats.memory_saved_bytes as f64
                    / (stats.memory_saved_bytes + string_map_size * 32) as f64
            } else {
                0.0
            },
        }
    }

    /// Get comprehensive performance metrics from SciRS2
    ///
    /// Returns detailed statistics including:
    /// - Cache hit/miss counts and ratios
    /// - Operation timing statistics
    /// - String length distribution
    /// - Memory usage patterns
    pub fn get_metrics(&self) -> InternerMetrics {
        let cache_hits = self.cache_hit_counter.get();
        let cache_misses = self.cache_miss_counter.get();
        let total_requests = cache_hits + cache_misses;
        let hit_ratio = if total_requests > 0 {
            cache_hits as f64 / total_requests as f64
        } else {
            0.0
        };

        let timer_stats = self.intern_timer.get_stats();
        let string_length_stats = self.string_length_histogram.get_stats();
        let memory_stats = self.memory_usage_histogram.get_stats();

        InternerMetrics {
            cache_hits,
            cache_misses,
            total_requests,
            hit_ratio,
            avg_intern_time_secs: timer_stats.mean,
            total_intern_observations: timer_stats.count,
            avg_string_length: string_length_stats.mean,
            total_memory_tracked_bytes: memory_stats.sum as u64,
        }
    }

    /// Optimize the interner by cleaning up and compacting data structures
    ///
    /// Performs comprehensive optimization:
    /// - Cleans up expired weak references
    /// - Rehashes HashMaps with optimal capacity
    /// - Updates memory usage statistics
    /// - Tracks optimization impact with SciRS2 metrics
    pub fn optimize(&self) {
        let start = std::time::Instant::now();

        // Clean up expired weak references
        let cleaned_count = self.cleanup();

        // Get current sizes
        let current_size = {
            let strings = self
                .strings
                .read()
                .unwrap_or_else(|poisoned| poisoned.into_inner());
            strings.len()
        };

        // Rehash with optimal capacity (1.3x current size to reduce future reallocations)
        let optimal_capacity = ((current_size as f64 * 1.3) as usize).max(1024);

        {
            let mut strings = self
                .strings
                .write()
                .unwrap_or_else(|poisoned| poisoned.into_inner());
            let mut string_to_id = self
                .string_to_id
                .write()
                .unwrap_or_else(|poisoned| poisoned.into_inner());
            let mut id_to_string = self
                .id_to_string
                .write()
                .unwrap_or_else(|poisoned| poisoned.into_inner());

            // Create new maps with optimal capacity
            let mut new_strings = HashMap::with_capacity(optimal_capacity);
            let mut new_string_to_id = HashMap::with_capacity(optimal_capacity);
            let mut new_id_to_string = HashMap::with_capacity(optimal_capacity);

            // Move data to new maps (rehashing in the process)
            for (key, value) in strings.drain() {
                new_strings.insert(key, value);
            }
            for (key, value) in string_to_id.drain() {
                new_string_to_id.insert(key, value);
            }
            for (key, value) in id_to_string.drain() {
                new_id_to_string.insert(key, value);
            }

            // Replace with optimized maps
            *strings = new_strings;
            *string_to_id = new_string_to_id;
            *id_to_string = new_id_to_string;
        }

        // Calculate and track memory usage
        let mem_usage = self.memory_usage();
        self.memory_usage_histogram
            .observe(mem_usage.estimated_memory_bytes as f64);

        // Update stats
        {
            let mut stats = self
                .stats
                .write()
                .unwrap_or_else(|poisoned| poisoned.into_inner());
            stats.total_strings_stored = current_size;
        }

        let duration = start.elapsed();
        tracing::debug!(
            "Interner optimized: cleaned {} entries, rehashed to capacity {}, took {:?}",
            cleaned_count,
            optimal_capacity,
            duration
        );
    }
}

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

impl std::fmt::Debug for StringInterner {
    fn fmt(&self, f: &mut std::fmt::Formatter<'_>) -> std::fmt::Result {
        f.debug_struct("StringInterner")
            .field(
                "strings_count",
                &self
                    .strings
                    .read()
                    .unwrap_or_else(|poisoned| poisoned.into_inner())
                    .len(),
            )
            .field(
                "id_mappings_count",
                &self
                    .string_to_id
                    .read()
                    .unwrap_or_else(|poisoned| poisoned.into_inner())
                    .len(),
            )
            .field(
                "next_id",
                &self.next_id.load(std::sync::atomic::Ordering::Relaxed),
            )
            .field(
                "stats",
                &self
                    .stats
                    .read()
                    .unwrap_or_else(|poisoned| poisoned.into_inner()),
            )
            .finish()
    }
}

// Global interner instances for common string types
/// Global interner for IRI strings
pub static IRI_INTERNER: once_cell::sync::Lazy<StringInterner> =
    once_cell::sync::Lazy::new(StringInterner::new);

/// Global interner for datatype IRIs
pub static DATATYPE_INTERNER: once_cell::sync::Lazy<StringInterner> =
    once_cell::sync::Lazy::new(StringInterner::new);

/// Global interner for language tags
pub static LANGUAGE_INTERNER: once_cell::sync::Lazy<StringInterner> =
    once_cell::sync::Lazy::new(StringInterner::new);

/// Global interner for general strings (JSON-LD processing)
pub static STRING_INTERNER: once_cell::sync::Lazy<StringInterner> =
    once_cell::sync::Lazy::new(StringInterner::new);

/// An interned string that supports efficient comparison and hashing
#[derive(Debug, Clone)]
pub struct InternedString {
    inner: Arc<str>,
}

impl InternedString {
    /// Create a new interned string using the default IRI interner
    pub fn new(s: &str) -> Self {
        InternedString {
            inner: IRI_INTERNER.intern(s),
        }
    }

    /// Create a new interned string using a specific interner
    pub fn new_with_interner(s: &str, interner: &StringInterner) -> Self {
        InternedString {
            inner: interner.intern(s),
        }
    }

    /// Create an interned datatype string
    pub fn new_datatype(s: &str) -> Self {
        InternedString {
            inner: DATATYPE_INTERNER.intern(s),
        }
    }

    /// Create an interned language tag string
    pub fn new_language(s: &str) -> Self {
        InternedString {
            inner: LANGUAGE_INTERNER.intern(s),
        }
    }

    /// Get the string content
    pub fn as_str(&self) -> &str {
        &self.inner
    }

    /// Get the inner `Arc<str>` for zero-copy operations
    pub fn as_arc_str(&self) -> &Arc<str> {
        &self.inner
    }

    /// Convert into the inner `Arc<str>`
    pub fn into_arc_str(self) -> Arc<str> {
        self.inner
    }
}

impl std::fmt::Display for InternedString {
    fn fmt(&self, f: &mut std::fmt::Formatter<'_>) -> std::fmt::Result {
        write!(f, "{}", self.inner)
    }
}

impl std::ops::Deref for InternedString {
    type Target = str;

    fn deref(&self) -> &Self::Target {
        &self.inner
    }
}

impl AsRef<str> for InternedString {
    fn as_ref(&self) -> &str {
        &self.inner
    }
}

impl PartialEq for InternedString {
    fn eq(&self, other: &Self) -> bool {
        // Fast pointer comparison first
        Arc::ptr_eq(&self.inner, &other.inner) || self.inner == other.inner
    }
}

impl Eq for InternedString {}

impl Hash for InternedString {
    fn hash<H: Hasher>(&self, state: &mut H) {
        // Hash the string content, not the pointer
        self.inner.hash(state);
    }
}

impl PartialOrd for InternedString {
    fn partial_cmp(&self, other: &Self) -> Option<std::cmp::Ordering> {
        Some(self.cmp(other))
    }
}

impl Ord for InternedString {
    fn cmp(&self, other: &Self) -> std::cmp::Ordering {
        self.inner.cmp(&other.inner)
    }
}

impl From<&str> for InternedString {
    fn from(s: &str) -> Self {
        InternedString::new(s)
    }
}

impl From<String> for InternedString {
    fn from(s: String) -> Self {
        InternedString::new(&s)
    }
}

/// Extension trait for string interning common RDF vocabulary
pub trait RdfVocabulary {
    /// Common XSD namespace
    const XSD_NS: &'static str = "http://www.w3.org/2001/XMLSchema#";
    /// Common RDF namespace
    const RDF_NS: &'static str = "http://www.w3.org/1999/02/22-rdf-syntax-ns#";
    /// Common RDFS namespace
    const RDFS_NS: &'static str = "http://www.w3.org/2000/01/rdf-schema#";
    /// Common OWL namespace  
    const OWL_NS: &'static str = "http://www.w3.org/2002/07/owl#";

    fn xsd_string() -> InternedString {
        InternedString::new_datatype(&format!("{}string", Self::XSD_NS))
    }

    fn xsd_integer() -> InternedString {
        InternedString::new_datatype(&format!("{}integer", Self::XSD_NS))
    }

    fn xsd_decimal() -> InternedString {
        InternedString::new_datatype(&format!("{}decimal", Self::XSD_NS))
    }

    fn xsd_boolean() -> InternedString {
        InternedString::new_datatype(&format!("{}boolean", Self::XSD_NS))
    }

    fn xsd_double() -> InternedString {
        InternedString::new_datatype(&format!("{}double", Self::XSD_NS))
    }

    fn xsd_float() -> InternedString {
        InternedString::new_datatype(&format!("{}float", Self::XSD_NS))
    }

    fn xsd_date_time() -> InternedString {
        InternedString::new_datatype(&format!("{}dateTime", Self::XSD_NS))
    }

    fn rdf_type() -> InternedString {
        InternedString::new(&format!("{}type", Self::RDF_NS))
    }

    fn rdfs_label() -> InternedString {
        InternedString::new(&format!("{}label", Self::RDFS_NS))
    }

    fn rdfs_comment() -> InternedString {
        InternedString::new(&format!("{}comment", Self::RDFS_NS))
    }
}

/// Implement RdfVocabulary for InternedString to provide easy access to common terms
impl RdfVocabulary for InternedString {}

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

    #[test]
    fn test_string_interner_survives_lock_poisoning() {
        // Regression test: a panic while holding one of the interner's
        // internal locks from another thread must not permanently disable
        // it - intern/stats should recover via into_inner() rather than
        // propagating the poison via `.expect()`.
        let interner = Arc::new(StringInterner::new());

        let poisoning_interner = interner.clone();
        let handle = std::thread::spawn(move || {
            let _guard = poisoning_interner.strings.write().unwrap();
            panic!("intentionally poison the strings lock");
        });
        let _ = handle.join();

        let s = interner.intern("http://example.org/after-poison");
        assert_eq!(s.as_ref(), "http://example.org/after-poison");
        let stats = interner.stats();
        assert!(stats.total_requests >= 1);
    }

    #[test]
    fn test_string_interner_basic() {
        let interner = StringInterner::new();

        let s1 = interner.intern("http://example.org/test");
        let s2 = interner.intern("http://example.org/test");
        let s3 = interner.intern("http://example.org/different");

        // Same string should return same Arc (pointer equality)
        assert!(Arc::ptr_eq(&s1, &s2));
        assert!(!Arc::ptr_eq(&s1, &s3));

        // Content should be equal
        assert_eq!(s1.as_ref(), "http://example.org/test");
        assert_eq!(s2.as_ref(), "http://example.org/test");
        assert_eq!(s3.as_ref(), "http://example.org/different");
    }

    #[test]
    fn test_string_interner_stats() {
        let interner = StringInterner::new();

        // First request - cache miss
        let _s1 = interner.intern("test");
        let stats = interner.stats();
        assert_eq!(stats.total_requests, 1);
        assert_eq!(stats.cache_misses, 1);
        assert_eq!(stats.cache_hits, 0);

        // Second request for same string - cache hit
        let _s2 = interner.intern("test");
        let stats = interner.stats();
        assert_eq!(stats.total_requests, 2);
        assert_eq!(stats.cache_misses, 1);
        assert_eq!(stats.cache_hits, 1);
        assert_eq!(stats.hit_ratio(), 0.5);
    }

    #[test]
    fn test_string_interner_cleanup() {
        let interner = StringInterner::new();

        {
            let _s1 = interner.intern("temporary");
            assert_eq!(interner.len(), 1);
        } // s1 goes out of scope

        interner.cleanup();
        assert_eq!(interner.len(), 0);
    }

    #[test]
    fn test_interned_string_creation() {
        let s1 = InternedString::new("http://example.org/test");
        let s2 = InternedString::new("http://example.org/test");
        let s3 = InternedString::new("http://example.org/different");

        assert_eq!(s1, s2);
        assert_ne!(s1, s3);
        assert_eq!(s1.as_str(), "http://example.org/test");
    }

    #[test]
    fn test_interned_string_ordering() {
        let s1 = InternedString::new("apple");
        let s2 = InternedString::new("banana");
        let s3 = InternedString::new("apple");

        assert!(s1 < s2);
        assert!(s2 > s1);
        assert_eq!(s1, s3);

        // Test that ordering is consistent
        let mut strings = vec![s2.clone(), s1.clone(), s3.clone()];
        strings.sort();
        assert_eq!(strings, vec![s1, s3, s2]);
    }

    #[test]
    fn test_interned_string_hashing() {
        use std::collections::HashMap;

        let s1 = InternedString::new("test");
        let s2 = InternedString::new("test");
        let s3 = InternedString::new("different");

        let mut map = HashMap::new();
        map.insert(s1.clone(), "value1");
        map.insert(s3.clone(), "value2");

        // s2 should map to the same value as s1 since they're equal
        assert_eq!(map.get(&s2), Some(&"value1"));
        assert_eq!(map.get(&s3), Some(&"value2"));
        assert_eq!(map.len(), 2);
    }

    #[test]
    fn test_global_interners() {
        let iri1 = InternedString::new("http://example.org/test");
        let iri2 = InternedString::new("http://example.org/test");

        let datatype1 = InternedString::new_datatype("http://www.w3.org/2001/XMLSchema#string");
        let datatype2 = InternedString::new_datatype("http://www.w3.org/2001/XMLSchema#string");

        let lang1 = InternedString::new_language("en");
        let lang2 = InternedString::new_language("en");

        // Verify that equal strings are interned
        assert_eq!(iri1, iri2);
        assert_eq!(datatype1, datatype2);
        assert_eq!(lang1, lang2);
    }

    #[test]
    fn test_rdf_vocabulary() {
        let string_type = InternedString::xsd_string();
        let integer_type = InternedString::xsd_integer();
        let rdf_type = InternedString::rdf_type();

        assert_eq!(
            string_type.as_str(),
            "http://www.w3.org/2001/XMLSchema#string"
        );
        assert_eq!(
            integer_type.as_str(),
            "http://www.w3.org/2001/XMLSchema#integer"
        );
        assert_eq!(
            rdf_type.as_str(),
            "http://www.w3.org/1999/02/22-rdf-syntax-ns#type"
        );

        // Test that repeated calls return interned strings
        let string_type2 = InternedString::xsd_string();
        assert_eq!(string_type, string_type2);
    }

    #[test]
    fn test_interned_string_display() {
        let s = InternedString::new("http://example.org/test");
        assert_eq!(format!("{s}"), "http://example.org/test");
    }

    #[test]
    fn test_interned_string_deref() {
        let s = InternedString::new("test");
        assert_eq!(&*s, "test");
        assert_eq!(s.len(), 4);
        assert!(s.starts_with("te"));
    }

    #[test]
    fn test_interned_string_conversions() {
        let s1 = InternedString::from("test");
        let s2 = InternedString::from("test".to_string());

        assert_eq!(s1, s2);
        assert_eq!(s1.as_str(), "test");
    }

    #[test]
    fn test_concurrent_interning() {
        use std::sync::Arc;
        use std::thread;

        let interner = Arc::new(StringInterner::new());
        let handles: Vec<_> = (0..10)
            .map(|i| {
                let interner = Arc::clone(&interner);
                thread::spawn(move || {
                    let s = format!("http://example.org/test{}", i % 3);
                    (0..100).map(|_| interner.intern(&s)).collect::<Vec<_>>()
                })
            })
            .collect();

        let results: Vec<Vec<Arc<str>>> = handles
            .into_iter()
            .map(|h| h.join().expect("thread should not panic"))
            .collect();

        // Verify that all equal strings are the same Arc
        for result_set in &results {
            for (i, s1) in result_set.iter().enumerate() {
                for s2 in &result_set[i + 1..] {
                    if s1.as_ref() == s2.as_ref() {
                        assert!(Arc::ptr_eq(s1, s2));
                    }
                }
            }
        }

        // Should have at most 3 unique strings (test0, test1, test2)
        assert!(interner.len() <= 3);
    }

    #[test]
    fn test_term_id_mapping() {
        let interner = StringInterner::new();

        // Test interning with ID
        let (arc1, id1) = interner.intern_with_id("test_string");
        let (arc2, id2) = interner.intern_with_id("test_string");

        // Same string should get same ID
        assert_eq!(id1, id2);
        assert!(Arc::ptr_eq(&arc1, &arc2));

        // Different strings should get different IDs
        let (arc3, id3) = interner.intern_with_id("different_string");
        assert_ne!(id1, id3);
        assert!(!Arc::ptr_eq(&arc1, &arc3));

        // Test ID lookup
        assert_eq!(interner.get_id("test_string"), Some(id1));
        assert_eq!(interner.get_id("different_string"), Some(id3));
        assert_eq!(interner.get_id("nonexistent"), None);

        // Test string lookup
        assert_eq!(
            interner
                .get_string(id1)
                .expect("operation should succeed")
                .as_ref(),
            "test_string"
        );
        assert_eq!(
            interner
                .get_string(id3)
                .expect("operation should succeed")
                .as_ref(),
            "different_string"
        );
        assert_eq!(interner.get_string(999), None);
    }

    #[test]
    fn test_id_mapping_stats() {
        let interner = StringInterner::new();

        assert_eq!(interner.id_mapping_count(), 0);

        interner.intern_with_id("string1");
        assert_eq!(interner.id_mapping_count(), 1);

        interner.intern_with_id("string2");
        assert_eq!(interner.id_mapping_count(), 2);

        // Interning same string again shouldn't increase count
        interner.intern_with_id("string1");
        assert_eq!(interner.id_mapping_count(), 2);
    }

    #[test]
    fn test_get_all_mappings() {
        let interner = StringInterner::new();

        let (_, id1) = interner.intern_with_id("first");
        let (_, id2) = interner.intern_with_id("second");
        let (_, id3) = interner.intern_with_id("third");

        let mappings = interner.get_all_mappings();
        assert_eq!(mappings.len(), 3);

        // Verify all mappings are present
        let mut found_ids = [false; 3];
        for (id, string) in mappings {
            match string.as_ref() {
                "first" => {
                    assert_eq!(id, id1);
                    found_ids[0] = true;
                }
                "second" => {
                    assert_eq!(id, id2);
                    found_ids[1] = true;
                }
                "third" => {
                    assert_eq!(id, id3);
                    found_ids[2] = true;
                }
                _ => panic!("Unexpected string in mappings"),
            }
        }
        assert!(found_ids.iter().all(|&found| found));
    }

    #[test]
    fn test_mixed_interning_modes() {
        let interner = StringInterner::new();

        // Mix regular interning and ID interning
        let arc1 = interner.intern("regular");
        let (_arc2, id2) = interner.intern_with_id("with_id");
        let arc3 = interner.intern("regular"); // Same as first

        // Regular interning should still work
        assert!(Arc::ptr_eq(&arc1, &arc3));

        // ID interning should work independently
        assert_eq!(
            interner
                .get_string(id2)
                .expect("operation should succeed")
                .as_ref(),
            "with_id"
        );

        // Mixed mode length reporting should work
        assert!(interner.len() >= 2);
    }

    /// Regression test: concurrent `intern_with_id` calls for the *same*
    /// string must never assign more than one id to it. Before the
    /// double-checked-locking fix, two threads that both missed the
    /// fast-path read-lock check could each `fetch_add` a distinct id and
    /// both write it into the maps, breaking the same-string-implies-
    /// same-id invariant.
    #[test]
    fn regression_intern_with_id_concurrent_same_string_single_id() {
        use std::collections::HashSet;
        use std::sync::Arc;
        use std::thread;

        for _ in 0..20 {
            let interner = Arc::new(StringInterner::new());
            let num_threads = 16;

            let handles: Vec<_> = (0..num_threads)
                .map(|_| {
                    let interner = Arc::clone(&interner);
                    thread::spawn(move || interner.intern_with_id("http://example.org/dup"))
                })
                .collect();

            let results: Vec<(Arc<str>, u32)> = handles
                .into_iter()
                .map(|h| h.join().expect("thread should not panic"))
                .collect();

            let unique_ids: HashSet<u32> = results.iter().map(|(_, id)| *id).collect();
            assert_eq!(
                unique_ids.len(),
                1,
                "all concurrent intern_with_id calls for the same string must return the same id"
            );

            let id = *unique_ids.iter().next().expect("one id was collected");
            assert_eq!(interner.get_id("http://example.org/dup"), Some(id));
            assert_eq!(
                interner
                    .get_string(id)
                    .expect("id should resolve back to the string")
                    .as_ref(),
                "http://example.org/dup"
            );
        }
    }
}