"""Periodic collection of p4 monitor, lsof, and lslocks snapshots.

Runs on a configurable interval and writes MonitorSnapshot records
to the rolling SQLite database.
"""
from __future__ import annotations

import logging
from pathlib import Path

from .models import MonitorSnapshot

logger = logging.getLogger(__name__)


class MonitorCollector:
    """Collects point-in-time snapshots from p4d process instrumentation.

    Runs `p4 monitor show -ale`, `lsof -p <p4d_pid>`, and `lslocks`
    on a configurable interval. Permission errors are logged and skipped —
    they do not crash the collector.
    """

    def __init__(self, db_path: Path, interval_s: float = 30.0) -> None:
        """
        Args:
            db_path: SQLite database path for storing snapshots.
            interval_s: Collection interval in seconds.
        """
        raise NotImplementedError

    def collect_once(self) -> MonitorSnapshot:
        """Run a single collection cycle and return the snapshot."""
        raise NotImplementedError

    def run_forever(self) -> None:
        """Collect in a loop until stopped."""
        raise NotImplementedError

    def stop(self) -> None:
        """Signal the collection loop to exit."""
        raise NotImplementedError