"""
Bounded statistics implementation to prevent memory leaks in ProjectX SDK.

Author: @TexasCoding
Date: 2025-08-22

Overview:
    Provides bounded counters, circular buffers, and automatic cleanup mechanisms
    to prevent unlimited memory growth in statistics collection. This module addresses
    the P1 priority memory leak issue identified in the realtime modules.

Key Features:
    - Bounded counters with configurable limits and rotation
    - Circular buffers for time-series statistics with TTL
    - Automatic cleanup scheduler for expired metrics
    - Memory usage monitoring and limits enforcement
    - Aggregation of older data into hourly/daily summaries
    - Thread-safe operations with async locks
    - High-frequency update support without performance degradation

Components:
    - BoundedCounter: Individual counter with rotation and aging
    - CircularBuffer: Fixed-size buffer for time-series data
    - MetricAggregator: Aggregates older data into summaries
    - BoundedStatisticsMixin: Complete bounded statistics implementation
    - CleanupScheduler: Background cleanup of expired metrics

Memory Efficiency:
    - Recent metrics: Full resolution (last 1 hour)
    - Hourly summaries: 24 hours of aggregated data
    - Daily summaries: 30 days of aggregated data
    - Total memory bound: ~10MB for high-frequency components

Example Usage:
    ```python
    from project_x_py.statistics.bounded_statistics import BoundedStatisticsMixin


    class RealtimeDataManagerWithBounds(BoundedStatisticsMixin):
        def __init__(self):
            super().__init__(
                max_recent_metrics=3600,  # 1 hour at 1/sec
                hourly_retention_hours=24,
                daily_retention_days=30,
            )

        async def process_tick(self):
            await self.increment_bounded("ticks_processed")
            await self.record_timing_bounded("tick_processing", 5.2)
    ```

See Also:
    - `project_x_py.statistics.base`: Base statistics tracking
    - `project_x_py.realtime_data_manager.core`: Realtime data management
    - docs/code-review/v3.3.0/REALTIME_FIXES_PLAN.md: Implementation plan
"""

import asyncio
import contextlib
import math
import time
from collections import defaultdict, deque
from collections.abc import Callable
from dataclasses import dataclass
from datetime import datetime
from typing import Any, Protocol

from project_x_py.utils.logging_config import ProjectXLogger


@dataclass
class MetricSummary:
    """Summary of aggregated metric data for a time period."""

    period_start: datetime
    period_end: datetime
    count: int
    sum_value: float
    min_value: float
    max_value: float
    avg_value: float

    def to_dict(self) -> dict[str, Any]:
        """Convert to dictionary for serialization."""
        return {
            "period_start": self.period_start.isoformat(),
            "period_end": self.period_end.isoformat(),
            "count": self.count,
            "sum": self.sum_value,
            "min": self.min_value,
            "max": self.max_value,
            "avg": self.avg_value,
        }


@dataclass
class TimestampedValue:
    """A value with timestamp for time-series tracking."""

    timestamp: float
    value: float

    def __post_init__(self) -> None:
        """Ensure timestamp is valid."""
        if self.timestamp <= 0:
            self.timestamp = time.time()


class BoundedCounter:
    """
    A counter with bounded memory that automatically rotates old data.

    Features:
        - Configurable maximum size to prevent unlimited growth
        - Time-based expiration with TTL support
        - Automatic rotation when limits are exceeded
        - Summary statistics for rotated data
    """

    def __init__(
        self, max_size: int = 3600, ttl_seconds: float = 3600.0, name: str = "counter"
    ):
        """
        Initialize bounded counter.

        Args:
            max_size: Maximum number of individual values to store
            ttl_seconds: Time-to-live for individual values in seconds
            name: Counter name for logging and debugging
        """
        self.max_size = max_size
        self.ttl_seconds = ttl_seconds
        self.name = name

        # Use deque for O(1) append/popleft operations
        self._values: deque[TimestampedValue] = deque(maxlen=max_size)
        self._total_count = 0
        self._total_sum = 0.0
        self._lock = asyncio.Lock()

        # Aggregated summaries for rotated data
        self._hourly_summaries: deque[MetricSummary] = deque(maxlen=24)  # 24 hours
        self._daily_summaries: deque[MetricSummary] = deque(maxlen=30)  # 30 days

        self.logger = ProjectXLogger.get_logger(f"{__name__}.{name}")

    async def increment(self, value: float = 1.0) -> None:
        """
        Increment the counter by the specified value.

        Args:
            value: Value to add to the counter
        """
        async with self._lock:
            current_time = time.time()

            # Add new value
            timestamped_value = TimestampedValue(current_time, value)
            self._values.append(timestamped_value)

            self._total_count += 1
            self._total_sum += value

            # Clean expired values if needed
            await self._cleanup_expired_values(current_time)

    async def get_current_sum(self) -> float:
        """Get sum of all non-expired values."""
        async with self._lock:
            current_time = time.time()
            await self._cleanup_expired_values(current_time)

            return sum(v.value for v in self._values)

    async def get_current_count(self) -> int:
        """Get count of all non-expired values."""
        async with self._lock:
            current_time = time.time()
            await self._cleanup_expired_values(current_time)

            return len(self._values)

    async def get_statistics(self) -> dict[str, Any]:
        """Get comprehensive statistics including summaries."""
        async with self._lock:
            current_time = time.time()
            await self._cleanup_expired_values(current_time)

            # Current period stats
            current_values = [v.value for v in self._values]
            current_stats = {
                "current_count": len(current_values),
                "current_sum": sum(current_values),
                "current_avg": sum(current_values) / len(current_values)
                if current_values
                else 0.0,
                "current_min": min(current_values) if current_values else 0.0,
                "current_max": max(current_values) if current_values else 0.0,
            }

            # Historical summaries
            hourly_summaries = [s.to_dict() for s in self._hourly_summaries]
            daily_summaries = [s.to_dict() for s in self._daily_summaries]

            # Overall totals
            overall_stats = {
                "total_lifetime_count": self._total_count,
                "total_lifetime_sum": self._total_sum,
                "memory_usage_bytes": self._estimate_memory_usage(),
                "ttl_seconds": self.ttl_seconds,
                "max_size": self.max_size,
            }

            return {
                **current_stats,
                **overall_stats,
                "hourly_summaries": hourly_summaries,
                "daily_summaries": daily_summaries,
            }

    async def _cleanup_expired_values(self, current_time: float) -> None:
        """Remove expired values and create summaries if needed."""
        cutoff_time = current_time - self.ttl_seconds
        expired_values = []

        # Remove expired values from the left (oldest)
        while self._values and self._values[0].timestamp < cutoff_time:
            expired_values.append(self._values.popleft())

        # If we have expired values, check if we need to create summaries
        if expired_values:
            await self._maybe_create_summaries(expired_values, current_time)

    async def _maybe_create_summaries(
        self, expired_values: list[TimestampedValue], current_time: float
    ) -> None:
        """Create hourly/daily summaries from expired values if needed."""
        if not expired_values:
            return

        # Group expired values by hour
        hourly_groups = defaultdict(list)
        for value in expired_values:
            hour_key = int(value.timestamp // 3600)  # Hour since epoch
            hourly_groups[hour_key].append(value)

        # Create hourly summaries
        for hour_key, values in hourly_groups.items():
            if len(values) < 10:  # Skip if too few values
                continue

            summary = self._create_summary(
                values, hour_key * 3600, (hour_key + 1) * 3600
            )
            self._hourly_summaries.append(summary)

        # Create daily summaries from old hourly summaries
        await self._maybe_create_daily_summaries(current_time)

    async def _maybe_create_daily_summaries(self, current_time: float) -> None:
        """Create daily summaries from hourly summaries if needed."""
        if len(self._hourly_summaries) < 24:  # Need at least 24 hours
            return

        # Group hourly summaries by day
        daily_groups = defaultdict(list)
        current_day = int(current_time // 86400)  # Day since epoch

        # Only consider summaries older than 1 day
        cutoff_day = current_day - 1

        summaries_to_remove = []
        for i, summary in enumerate(self._hourly_summaries):
            summary_day = int(summary.period_start.timestamp() // 86400)
            if summary_day <= cutoff_day:
                daily_groups[summary_day].append(summary)
                summaries_to_remove.append(i)

        # Create daily summaries
        for day_key, summaries in daily_groups.items():
            if len(summaries) >= 12:  # At least half a day of data
                daily_summary = self._create_summary_from_summaries(
                    summaries, day_key * 86400, (day_key + 1) * 86400
                )
                self._daily_summaries.append(daily_summary)

        # Remove hourly summaries that were aggregated into daily
        for i in reversed(summaries_to_remove):
            del self._hourly_summaries[i]

    def _create_summary(
        self, values: list[TimestampedValue], period_start: float, period_end: float
    ) -> MetricSummary:
        """Create a summary from a list of timestamped values."""
        if not values:
            return MetricSummary(
                period_start=datetime.fromtimestamp(period_start),
                period_end=datetime.fromtimestamp(period_end),
                count=0,
                sum_value=0.0,
                min_value=0.0,
                max_value=0.0,
                avg_value=0.0,
            )

        value_list = [v.value for v in values]
        return MetricSummary(
            period_start=datetime.fromtimestamp(period_start),
            period_end=datetime.fromtimestamp(period_end),
            count=len(value_list),
            sum_value=sum(value_list),
            min_value=min(value_list),
            max_value=max(value_list),
            avg_value=sum(value_list) / len(value_list),
        )

    def _create_summary_from_summaries(
        self, summaries: list[MetricSummary], period_start: float, period_end: float
    ) -> MetricSummary:
        """Create a summary by aggregating other summaries."""
        if not summaries:
            return MetricSummary(
                period_start=datetime.fromtimestamp(period_start),
                period_end=datetime.fromtimestamp(period_end),
                count=0,
                sum_value=0.0,
                min_value=0.0,
                max_value=0.0,
                avg_value=0.0,
            )

        total_count = sum(s.count for s in summaries)
        total_sum = sum(s.sum_value for s in summaries)
        min_value = min(s.min_value for s in summaries)
        max_value = max(s.max_value for s in summaries)
        avg_value = total_sum / total_count if total_count > 0 else 0.0

        return MetricSummary(
            period_start=datetime.fromtimestamp(period_start),
            period_end=datetime.fromtimestamp(period_end),
            count=total_count,
            sum_value=total_sum,
            min_value=min_value,
            max_value=max_value,
            avg_value=avg_value,
        )

    def _estimate_memory_usage(self) -> int:
        """Estimate memory usage in bytes."""
        # Rough estimation
        values_size = len(self._values) * 24  # TimestampedValue ~24 bytes
        summaries_size = (
            len(self._hourly_summaries) + len(self._daily_summaries)
        ) * 100  # Summary ~100 bytes
        overhead_size = 200  # Other attributes

        return values_size + summaries_size + overhead_size


class CircularBuffer:
    """
    Fixed-size circular buffer for time-series data with automatic cleanup.

    Features:
        - Fixed maximum size prevents unlimited growth
        - Automatic overwriting of oldest values when full
        - Time-based queries for recent data
        - Statistical aggregations over time windows
    """

    def __init__(self, max_size: int = 1000, name: str = "buffer"):
        """
        Initialize circular buffer.

        Args:
            max_size: Maximum number of values to store
            name: Buffer name for logging
        """
        self.max_size = max_size
        self.name = name

        # Use deque for O(1) operations
        self._buffer: deque[TimestampedValue] = deque(maxlen=max_size)
        self._lock = asyncio.Lock()

        self.logger = ProjectXLogger.get_logger(f"{__name__}.{name}")

    async def append(self, value: float, timestamp: float | None = None) -> None:
        """
        Append a new value to the buffer.

        Args:
            value: Value to append
            timestamp: Optional timestamp (uses current time if None)
        """
        async with self._lock:
            if timestamp is None:
                timestamp = time.time()

            timestamped_value = TimestampedValue(timestamp, value)
            self._buffer.append(timestamped_value)

    async def get_recent(self, seconds: float) -> list[float]:
        """
        Get values from the last N seconds.

        Args:
            seconds: Number of seconds to look back

        Returns:
            List of values from the specified time window
        """
        async with self._lock:
            current_time = time.time()
            cutoff_time = current_time - seconds

            return [v.value for v in self._buffer if v.timestamp >= cutoff_time]

    async def get_statistics(self, seconds: float | None = None) -> dict[str, Any]:
        """
        Get statistical summary of buffer contents.

        Args:
            seconds: Time window in seconds (None for entire buffer)

        Returns:
            Dictionary with statistical measures
        """
        async with self._lock:
            if seconds is not None:
                current_time = time.time()
                cutoff_time = current_time - seconds
                values = [v.value for v in self._buffer if v.timestamp >= cutoff_time]
            else:
                values = [v.value for v in self._buffer]

            if not values:
                return {
                    "count": 0,
                    "sum": 0.0,
                    "avg": 0.0,
                    "min": 0.0,
                    "max": 0.0,
                    "std_dev": 0.0,
                }

            count = len(values)
            sum_val = sum(values)
            avg_val = sum_val / count
            min_val = min(values)
            max_val = max(values)

            # Calculate standard deviation
            variance = sum((x - avg_val) ** 2 for x in values) / count
            std_dev = math.sqrt(variance)

            return {
                "count": count,
                "sum": sum_val,
                "avg": avg_val,
                "min": min_val,
                "max": max_val,
                "std_dev": std_dev,
                "memory_usage_bytes": len(self._buffer) * 24,  # Rough estimate
            }

    async def get_size(self) -> int:
        """Get current buffer size."""
        async with self._lock:
            return len(self._buffer)

    async def clear(self) -> None:
        """Clear all values from the buffer."""
        async with self._lock:
            self._buffer.clear()


class CleanupScheduler:
    """
    Background scheduler for periodic cleanup of bounded statistics.

    Features:
        - Configurable cleanup intervals
        - Memory pressure monitoring
        - Graceful shutdown with task cancellation
        - Error handling and logging
    """

    def __init__(
        self,
        cleanup_interval_seconds: float = 300.0,  # 5 minutes
        memory_check_interval_seconds: float = 60.0,  # 1 minute
    ):
        """
        Initialize cleanup scheduler.

        Args:
            cleanup_interval_seconds: How often to run cleanup
            memory_check_interval_seconds: How often to check memory usage
        """
        self.cleanup_interval = cleanup_interval_seconds
        self.memory_check_interval = memory_check_interval_seconds

        self._cleanup_task: asyncio.Task[None] | None = None
        self._memory_task: asyncio.Task[None] | None = None
        self._running = False

        # Registered cleanup functions
        self._cleanup_functions: list[tuple[str, Callable[[], Any]]] = []

        self.logger = ProjectXLogger.get_logger(__name__)

    def register_cleanup_function(
        self, name: str, cleanup_func: Callable[[], Any]
    ) -> None:
        """
        Register a cleanup function to be called periodically.

        Args:
            name: Name of the cleanup function for logging
            cleanup_func: Async function to call during cleanup
        """
        self._cleanup_functions.append((name, cleanup_func))
        self.logger.debug(f"Registered cleanup function: {name}")

    async def start(self) -> None:
        """Start the cleanup scheduler."""
        if self._running:
            self.logger.warning("Cleanup scheduler already running")
            return

        self._running = True

        # Start cleanup task
        self._cleanup_task = asyncio.create_task(self._cleanup_loop())

        # Start memory monitoring task
        self._memory_task = asyncio.create_task(self._memory_monitoring_loop())

        self.logger.info("Cleanup scheduler started")

    async def stop(self) -> None:
        """Stop the cleanup scheduler and cancel tasks."""
        self._running = False

        # Cancel tasks
        if self._cleanup_task and not self._cleanup_task.done():
            self._cleanup_task.cancel()
            with contextlib.suppress(asyncio.CancelledError):
                await self._cleanup_task

        if self._memory_task and not self._memory_task.done():
            self._memory_task.cancel()
            with contextlib.suppress(asyncio.CancelledError):
                await self._memory_task

        self.logger.info("Cleanup scheduler stopped")

    async def _cleanup_loop(self) -> None:
        """Main cleanup loop."""
        while self._running:
            try:
                await asyncio.sleep(self.cleanup_interval)

                if not self._running:
                    break  # pragma: no cover

                # Run all registered cleanup functions
                for name, cleanup_func in self._cleanup_functions:
                    try:
                        start_time = time.time()
                        if asyncio.iscoroutinefunction(cleanup_func):
                            await cleanup_func()
                        else:
                            cleanup_func()
                        duration_ms = (time.time() - start_time) * 1000

                        self.logger.debug(
                            f"Cleanup function '{name}' completed in {duration_ms:.1f}ms"
                        )
                    except Exception as e:
                        self.logger.error(f"Error in cleanup function '{name}': {e}")

            except asyncio.CancelledError:
                break
            except Exception as e:
                self.logger.error(f"Error in cleanup loop: {e}")
                # Continue running even if there's an error

    async def _memory_monitoring_loop(self) -> None:
        """Memory monitoring loop."""
        while self._running:
            try:
                await asyncio.sleep(self.memory_check_interval)

                if not self._running:
                    break  # pragma: no cover

                # Check memory usage (simplified implementation)
                # In a real implementation, you might check system memory,
                # process memory, or specific component memory usage

                # For now, just log that monitoring is active
                self.logger.debug("Memory monitoring check completed")

            except asyncio.CancelledError:
                break
            except Exception as e:
                self.logger.error(f"Error in memory monitoring: {e}")


class BoundedStatisticsMixin:
    """
    Mixin providing bounded statistics capabilities to prevent memory leaks.

    This mixin replaces unbounded counters with bounded alternatives that:
    - Limit recent data to configurable time windows
    - Automatically aggregate older data into summaries
    - Provide cleanup mechanisms for expired metrics
    - Monitor memory usage and enforce limits

    Features:
        - Bounded counters with automatic rotation
        - Circular buffers for time-series data
        - Automatic cleanup scheduling
        - Memory usage monitoring
        - High-frequency update support
        - Thread-safe async operations

    Memory Efficiency:
        - Recent metrics: Full resolution (default: 1 hour)
        - Hourly summaries: 24 hours of aggregated data
        - Daily summaries: 30 days of aggregated data
        - Automatic cleanup every 5 minutes

    Example Usage:
        ```python
        class MyComponent(BoundedStatisticsMixin):
            def __init__(self):
                super().__init__(
                    max_recent_metrics=3600,  # 1 hour at 1/sec
                    hourly_retention_hours=24,
                    daily_retention_days=30,
                )

            async def process_data(self):
                await self.increment_bounded("data_processed")
                await self.record_timing_bounded("processing_time", 5.2)
        ```
    """

    def __init__(
        self,
        max_recent_metrics: int = 3600,
        hourly_retention_hours: int = 24,
        daily_retention_days: int = 30,
        timing_buffer_size: int = 1000,
        cleanup_interval_minutes: float = 5.0,
        **kwargs: Any,
    ) -> None:
        """
        Initialize bounded statistics mixin.

        Args:
            max_recent_metrics: Maximum recent values per counter
            hourly_retention_hours: Hours of hourly summaries to keep
            daily_retention_days: Days of daily summaries to keep
            timing_buffer_size: Size of timing circular buffers
            cleanup_interval_minutes: Minutes between cleanup cycles
            **kwargs: Additional arguments passed to parent
        """
        # Don't call super().__init__ to avoid conflicts with multiple inheritance
        # This mixin should be mixed in with other classes that handle their own initialization

        self.max_recent_metrics = max_recent_metrics
        self.hourly_retention_hours = hourly_retention_hours
        self.daily_retention_days = daily_retention_days
        self.timing_buffer_size = timing_buffer_size

        # Bounded counters for metrics
        self._bounded_counters: dict[str, BoundedCounter] = {}
        self._counter_lock = asyncio.Lock()

        # Circular buffers for timing data
        self._timing_buffers: dict[str, CircularBuffer] = {}
        self._timing_lock = asyncio.Lock()

        # Bounded gauges (keep only recent values)
        self._bounded_gauges: dict[str, CircularBuffer] = {}
        self._gauge_lock = asyncio.Lock()

        # Cleanup scheduler
        self._cleanup_scheduler = CleanupScheduler(
            cleanup_interval_seconds=cleanup_interval_minutes * 60.0
        )

        # Register our cleanup functions
        self._cleanup_scheduler.register_cleanup_function(
            "bounded_counters", self._cleanup_counters
        )
        self._cleanup_scheduler.register_cleanup_function(
            "timing_buffers", self._cleanup_timing_buffers
        )
        self._cleanup_scheduler.register_cleanup_function(
            "bounded_gauges", self._cleanup_gauges
        )

        self.logger = ProjectXLogger.get_logger(f"{__name__}.bounded_stats")

        # Schedule cleanup scheduler to start when event loop is available
        self._cleanup_scheduler_started = False

    async def _start_cleanup_scheduler(self) -> None:
        """Start the cleanup scheduler in the background."""
        if self._cleanup_scheduler_started:
            return

        try:
            await self._cleanup_scheduler.start()
            self._cleanup_scheduler_started = True
        except Exception as e:
            self.logger.error(f"Failed to start cleanup scheduler: {e}")

    async def _ensure_cleanup_scheduler_started(self) -> None:
        """Ensure cleanup scheduler is started when event loop is available."""
        if not self._cleanup_scheduler_started:
            await self._start_cleanup_scheduler()

    async def increment_bounded(self, metric: str, value: float = 1.0) -> None:
        """
        Increment a bounded counter metric.

        Args:
            metric: Name of the metric to increment
            value: Value to increment by (default: 1.0)
        """
        async with self._counter_lock:
            if metric not in self._bounded_counters:
                self._bounded_counters[metric] = BoundedCounter(
                    max_size=self.max_recent_metrics,
                    ttl_seconds=3600.0,  # 1 hour TTL
                    name=metric,
                )

            await self._bounded_counters[metric].increment(value)

    async def set_gauge_bounded(self, metric: str, value: float) -> None:
        """
        Set a bounded gauge metric.

        Args:
            metric: Name of the gauge metric
            value: Value to set
        """
        async with self._gauge_lock:
            if metric not in self._bounded_gauges:
                self._bounded_gauges[metric] = CircularBuffer(
                    max_size=self.max_recent_metrics, name=f"gauge_{metric}"
                )

            await self._bounded_gauges[metric].append(value)

    async def record_timing_bounded(self, operation: str, duration_ms: float) -> None:
        """
        Record timing information in a bounded buffer.

        Args:
            operation: Name of the operation being timed
            duration_ms: Duration in milliseconds
        """
        async with self._timing_lock:
            if operation not in self._timing_buffers:
                self._timing_buffers[operation] = CircularBuffer(
                    max_size=self.timing_buffer_size, name=f"timing_{operation}"
                )

            await self._timing_buffers[operation].append(duration_ms)

    async def get_bounded_counter_stats(self, metric: str) -> dict[str, Any] | None:
        """
        Get statistics for a specific bounded counter.

        Args:
            metric: Name of the metric

        Returns:
            Dictionary with counter statistics or None if not found
        """
        async with self._counter_lock:
            if metric in self._bounded_counters:
                return await self._bounded_counters[metric].get_statistics()
            return None

    async def get_bounded_timing_stats(self, operation: str) -> dict[str, Any] | None:
        """
        Get statistics for a specific timing operation.

        Args:
            operation: Name of the operation

        Returns:
            Dictionary with timing statistics or None if not found
        """
        async with self._timing_lock:
            if operation in self._timing_buffers:
                return await self._timing_buffers[operation].get_statistics()
            return None

    async def get_bounded_gauge_stats(self, metric: str) -> dict[str, Any] | None:
        """
        Get statistics for a specific bounded gauge.

        Args:
            metric: Name of the gauge

        Returns:
            Dictionary with gauge statistics or None if not found
        """
        async with self._gauge_lock:
            if metric in self._bounded_gauges:
                return await self._bounded_gauges[metric].get_statistics()
            return None

    async def get_all_bounded_stats(self) -> dict[str, Any]:
        """
        Get comprehensive statistics from all bounded metrics.

        Returns:
            Dictionary with all bounded statistics
        """
        stats: dict[str, Any] = {
            "counters": {},
            "timing": {},
            "gauges": {},
            "memory_usage": await self._get_bounded_memory_usage(),
        }

        # Get counter stats
        async with self._counter_lock:
            for name, counter in self._bounded_counters.items():
                stats["counters"][name] = await counter.get_statistics()

        # Get timing stats
        async with self._timing_lock:
            for name, buffer in self._timing_buffers.items():
                stats["timing"][name] = await buffer.get_statistics()

        # Get gauge stats
        async with self._gauge_lock:
            for name, buffer in self._bounded_gauges.items():
                stats["gauges"][name] = await buffer.get_statistics()

        return stats

    async def _get_bounded_memory_usage(self) -> dict[str, Any]:
        """Calculate total memory usage of bounded statistics."""
        total_bytes = 0
        component_usage = {}

        # Counter memory usage
        async with self._counter_lock:
            counter_bytes = 0
            for _name, counter in self._bounded_counters.items():
                counter_stats = await counter.get_statistics()
                counter_bytes += counter_stats.get("memory_usage_bytes", 0)
            component_usage["counters"] = counter_bytes
            total_bytes += counter_bytes

        # Timing buffer memory usage
        async with self._timing_lock:
            timing_bytes = 0
            for _name, buffer in self._timing_buffers.items():
                timing_stats = await buffer.get_statistics()
                timing_bytes += timing_stats.get("memory_usage_bytes", 0)
            component_usage["timing"] = timing_bytes
            total_bytes += timing_bytes

        # Gauge memory usage
        async with self._gauge_lock:
            gauge_bytes = 0
            for _name, buffer in self._bounded_gauges.items():
                gauge_stats = await buffer.get_statistics()
                gauge_bytes += gauge_stats.get("memory_usage_bytes", 0)
            component_usage["gauges"] = gauge_bytes
            total_bytes += gauge_bytes

        return {
            "total_bytes": total_bytes,
            "total_mb": total_bytes / (1024 * 1024),
            "component_breakdown": component_usage,
            "num_counters": len(self._bounded_counters),
            "num_timing_operations": len(self._timing_buffers),
            "num_gauges": len(self._bounded_gauges),
        }

    async def _cleanup_counters(self) -> None:
        """Cleanup expired counter data."""
        async with self._counter_lock:
            for counter in self._bounded_counters.values():
                # Trigger cleanup by accessing statistics
                await counter.get_statistics()

    async def _cleanup_timing_buffers(self) -> None:
        """Cleanup timing buffers (no action needed, circular buffers auto-cleanup)."""
        # Circular buffers automatically handle cleanup through maxlen

    async def _cleanup_gauges(self) -> None:
        """Cleanup gauge buffers (no action needed, circular buffers auto-cleanup)."""
        # Circular buffers automatically handle cleanup through maxlen

    async def cleanup_bounded_statistics(self) -> None:
        """
        Manually trigger cleanup of all bounded statistics.

        This method can be called to force immediate cleanup, typically
        during component shutdown or when memory pressure is detected.
        """
        try:
            await self._cleanup_counters()
            await self._cleanup_timing_buffers()
            await self._cleanup_gauges()

            # Stop the cleanup scheduler
            await self._cleanup_scheduler.stop()

            self.logger.info("Bounded statistics cleanup completed")

        except Exception as e:
            self.logger.error(f"Error during bounded statistics cleanup: {e}")


# Protocol for components that support bounded statistics
class BoundedStatisticsProvider(Protocol):
    """Protocol for components that provide bounded statistics."""

    async def increment_bounded(self, metric: str, value: float = 1.0) -> None:
        """Increment a bounded counter metric."""
        ...

    async def set_gauge_bounded(self, metric: str, value: float) -> None:
        """Set a bounded gauge metric."""
        ...

    async def record_timing_bounded(self, operation: str, duration_ms: float) -> None:
        """Record timing in a bounded buffer."""
        ...

    async def get_all_bounded_stats(self) -> dict[str, Any]:
        """Get all bounded statistics."""
        ...


__all__ = [
    "BoundedCounter",
    "CircularBuffer",
    "CleanupScheduler",
    "BoundedStatisticsMixin",
    "BoundedStatisticsProvider",
    "MetricSummary",
    "TimestampedValue",
]