gpu_telemetry 0.2.1

High-level GPU telemetry background logger
Documentation
//! High-level monitoring and telemetry abstracting over loggers and queries.

use std::{
    marker::PhantomData,
    sync::{
        atomic::{AtomicBool, Ordering},
        Arc,
    },
    thread::{spawn, JoinHandle},
    time::Duration,
};

use crate::{
    errors::{Error, ErrorKind},
    monitor::telemetry::GpuLogger,
    sys::GpuTelemetry,
};

pub mod telemetry;

/// The highest level of monitoring.
///
/// Completely safe API and runs telemetry in a background thread.
pub struct GpuMonitor<L: GpuLogger + Send + 'static, B: GpuTelemetry = crate::DefaultQuery> {
    stop: Arc<AtomicBool>,
    handle: JoinHandle<Result<L, Error>>,
    _backend: PhantomData<B>,
}

impl<L: GpuLogger + Send + 'static, B: GpuTelemetry> GpuMonitor<L, B> {
    /// Starts the monitor and initializes this object on adapter 0.
    ///
    /// The interval passed to this function is used to sleep for at most
    /// that duration between each query (or when a GPU event occurs).
    #[deprecated = "use GpuMonitor::on_adapter instead"]
    pub fn start(interval: Duration) -> Result<Self, Error> {
        if interval.is_zero() {
            return Err(Error {
                msg: "cannot track telemetry at interval of zero",
                kind: ErrorKind::InvalidInterval,
            });
        }

        let stop = Arc::new(AtomicBool::new(false));
        let stop_thread = Arc::clone(&stop);

        let handle = spawn(move || {
            let backend = B::new(0)?;

            let mut logger = L::new();

            while !stop_thread.load(Ordering::Relaxed) {
                let sample = backend.query()?;

                logger.log(sample);

                backend.wait_at_most(interval)?;
            }

            Ok(logger)
        });

        Ok(Self {
            stop,
            handle,
            _backend: PhantomData,
        })
    }

    /// Starts the monitor and initializes this object.
    ///
    /// The interval passed to this function is used to sleep for at most
    /// that duration between each query (or when a GPU event occurs).
    pub fn on_adapter(adapter: usize, interval: Duration) -> Result<Self, Error> {
        if interval.is_zero() {
            return Err(Error {
                msg: "cannot track telemetry at interval of zero",
                kind: ErrorKind::InvalidInterval,
            });
        }

        let stop = Arc::new(AtomicBool::new(false));
        let stop_thread = Arc::clone(&stop);

        let handle = spawn(move || {
            let backend = B::new(adapter)?;

            let mut logger = L::new();

            while !stop_thread.load(Ordering::Relaxed) {
                let sample = backend.query()?;

                logger.log(sample);

                backend.wait_at_most(interval)?;
            }

            Ok(logger)
        });

        Ok(Self {
            stop,
            handle,
            _backend: PhantomData,
        })
    }

    /// Stops the monitor and returns the logger.
    pub fn stop(self) -> Result<L, Error> {
        self.stop.store(true, Ordering::Relaxed);
        self.handle.join().map_err(|_| Error {
            msg: "could not join telemetry background process",
            kind: ErrorKind::SyncError,
        })?
    }
}

#[cfg(test)]
mod tests {
    use std::time::Duration;
    use crate::monitor::{GpuMonitor, telemetry::Telemetry};

    #[test]
    #[cfg(any(target_os = "windows", target_os = "linux"))]
    fn gpu_monitor_default() {
        let monitor: GpuMonitor<Telemetry> = GpuMonitor::on_adapter(0, Duration::from_millis(50)).unwrap();
        std::thread::sleep(Duration::from_secs(3));
        let _ = monitor.stop().unwrap();
    }

    #[test]
    #[cfg(target_os = "windows")]
    fn gpu_monitor_dx() {
        let monitor =
            GpuMonitor::<Telemetry, crate::sys::DxGpuQuery>::on_adapter(0, Duration::from_millis(50))
                .unwrap();
        std::thread::sleep(Duration::from_secs(3));
        let _ = monitor.stop().unwrap();
    }

    #[test]
    #[cfg(any(target_os = "windows", target_os = "linux"))]
    fn gpu_monitor_vulkan() {
        let monitor =
            GpuMonitor::<Telemetry, crate::sys::VulkanGpuQuery>::on_adapter(0, Duration::from_millis(50))
                .unwrap();
        std::thread::sleep(Duration::from_secs(3));
        let _ = monitor.stop().unwrap();
    }
}