Interface GpuStats

All Superinterfaces:
AutoCloseable
All Known Implementing Classes:
NoOpGpuStats
@ThreadSafe public interface GpuStats extends AutoCloseable
A session handle for sampling dynamic GPU metrics. Obtain an instance via GraphicsCard.createStatsSession().

Session lifecycle

Each session may hold native resources (IOReport subscriptions, device handles, etc.) that are released when close() is called. Always close the session when done, preferably via try-with-resources: 

try (GpuStats stats = card.createStatsSession()) {
    double temp = stats.getTemperature();
    double power = stats.getPowerDraw();
}

One-shot vs. polling

Instantaneous metrics (temperature, VRAM used, clock speeds, fan speed) can be read from a freshly opened session with a single call. For delta-based metrics — getGpuUtilization() and getPowerDraw() — behaviour on the first call is implementation-dependent: some backends return an immediate reading, while others record an initial baseline and return -1 until a second sample is taken. Callers that need a guaranteed valid value on the first polling iteration should prime these methods once before the loop begins.

For repeated polling, hold a single session open for the entire polling window rather than opening and closing one per iteration. This preserves the internal baseline state across iterations and avoids the overhead of re-creating native subscriptions on every sample: 

try (GpuStats stats = card.createStatsSession()) {

    // Prime delta-based metrics so the first real iteration has a valid baseline.
    GpuTicks prev = stats.getGpuTicks();
    stats.getPowerDraw(); // establishes power baseline; returns -1
    stats.getGpuUtilization(); // establishes utilization baseline; returns -1

    for (int i = 0; i < ITERATIONS; i++) {
        Thread.sleep(1_000L);

        // Tick-derived utilization: dActive / (dActive + dIdle) * 100
        GpuTicks curr = stats.getGpuTicks();
        long dActive = curr.getActiveTicks() - prev.getActiveTicks();
        long dIdle = curr.getIdleTicks() - prev.getIdleTicks();
        long dTotal = dActive + dIdle;
        double tickUtil = dTotal > 0 ? dActive * 100.0 / dTotal : -1d;
        prev = curr;

        // API-reported utilization (delta computed internally by the session)
        double apiUtil = stats.getGpuUtilization();

        // Instantaneous metrics
        double temp = stats.getTemperature();
        double power = stats.getPowerDraw();
        long clock = stats.getCoreClockMhz();
    }
}

Sentinel values

All metric methods return -1 (or -1L for long results) when the metric is unavailable on the current platform, when the session has not yet accumulated enough samples to compute a delta, or when the underlying native query fails. Callers should treat any negative return value as "not available" and display it accordingly (e.g. "n/a") rather than as a meaningful measurement.

Thread safety

All methods are safe for concurrent use from multiple threads.

  • Method Summary

    Modifier and Type
    Method
    Description
    void
    close()
    Releases any native resources held by this session.
    long
    getCoreClockMhz()
    Returns the current GPU core clock speed.
    double
    getFanSpeedPercent()
    Returns the GPU fan speed as a percentage of maximum.
    GpuTicks
    getGpuTicks()
    Returns a snapshot of cumulative GPU active and idle ticks in opaque, platform-native units.
    double
    getGpuUtilization()
    Returns the instantaneous GPU core utilization as a percentage, computed internally as a delta between the current sample and the previous one recorded by this session.
    long
    getMemoryClockMhz()
    Returns the current GPU memory clock speed.
    double
    getPowerDraw()
    Returns the GPU power consumption.
    long
    getSharedMemoryUsed()
    Returns the amount of shared system memory currently used by this GPU.
    double
    getTemperature()
    Returns the GPU temperature.
    long
    getVramUsed()
    Returns the amount of dedicated VRAM currently in use.
    boolean
    isClosed()
    Returns true if close() has been called on this session.

  • Method Details

    • close

      void close()
      Releases any native resources held by this session. Safe to call multiple times; subsequent calls after the first are no-ops. Does not throw checked exceptions.
      Specified by:
      close in interface AutoCloseable

    • isClosed

      boolean isClosed()
      Returns true if close() has been called on this session. Does not throw.
      Returns:
      true if this session is closed

    • getGpuTicks

      GpuTicks getGpuTicks()
      Returns a snapshot of cumulative GPU active and idle ticks in opaque, platform-native units. The counters are monotonically increasing; diff two snapshots to compute utilization: 
      long dActive = curr.getActiveTicks() - prev.getActiveTicks();
long dIdle = curr.getIdleTicks() - prev.getIdleTicks();
long dTotal = dActive + dIdle;
double utilPct = dTotal > 0 ? dActive * 100.0 / dTotal : -1d;

      Both counters are 0 on platforms where tick-level GPU metrics are not available (see GpuTicks for the sentinel semantics). Use getGpuUtilization() as an alternative.

      Returns:
      a GpuTicks snapshot; never null
      Throws:
      IllegalStateException - if the session has been closed

    • getGpuUtilization

      double getGpuUtilization()
      Returns the instantaneous GPU core utilization as a percentage, computed internally as a delta between the current sample and the previous one recorded by this session.

      Behaviour on the first call is implementation-dependent. Backends that derive utilization from an energy or residency counter record an initial baseline on the first call and return -1; subsequent calls return the utilization computed over the elapsed interval. Backends that read an instantaneous hardware register may return a valid value immediately. To ensure the first polling iteration returns a valid value on delta-based backends, call this method once as a priming step before the polling loop begins: 

      stats.getGpuUtilization(); // prime — may return -1 on delta-based backends
Thread.sleep(intervalMs);
double util = stats.getGpuUtilization(); // valid on all backends
      Returns:
      utilization in the range 0.0 to 100.0, or -1 if not available or not yet primed
      Throws:
      IllegalStateException - if the session has been closed; obtain a new session via GraphicsCard.createStatsSession()

    • getVramUsed

      long getVramUsed()
      Returns the amount of dedicated VRAM currently in use.
      Returns:
      bytes of VRAM in use, or -1 if unavailable
      Throws:
      IllegalStateException - if the session has been closed; obtain a new session via GraphicsCard.createStatsSession()

    • getSharedMemoryUsed

      long getSharedMemoryUsed()
      Returns the amount of shared system memory currently used by this GPU.
      Returns:
      bytes of shared memory in use, or -1 if unavailable
      Throws:
      IllegalStateException - if the session has been closed; obtain a new session via GraphicsCard.createStatsSession()

    • getTemperature

      double getTemperature()
      Returns the GPU temperature.
      Returns:
      temperature in degrees Celsius, or -1 if unavailable
      Throws:
      IllegalStateException - if the session has been closed; obtain a new session via GraphicsCard.createStatsSession()

    • getPowerDraw

      double getPowerDraw()
      Returns the GPU power consumption. On backends that derive power from an energy counter (e.g. macOS Apple Silicon via IOReport), this is computed as a delta between the current sample and the previous one; the first call records the initial baseline and returns -1. On backends that read an instantaneous hardware sensor (e.g. Windows via NVML/ADL/LHM), a valid value may be returned immediately.

      To ensure the first polling iteration returns a valid value on delta-based backends, call this method once as a priming step before the polling loop begins: 

      stats.getPowerDraw(); // prime — may return -1 on delta-based backends
Thread.sleep(intervalMs);
double watts = stats.getPowerDraw(); // valid on all backends
      Returns:
      power draw in watts, or -1 if unavailable or not yet primed
      Throws:
      IllegalStateException - if the session has been closed; obtain a new session via GraphicsCard.createStatsSession()

    • getCoreClockMhz

      long getCoreClockMhz()
      Returns the current GPU core clock speed.
      Returns:
      core clock in MHz, or -1 if unavailable
      Throws:
      IllegalStateException - if the session has been closed; obtain a new session via GraphicsCard.createStatsSession()

    • getMemoryClockMhz

      long getMemoryClockMhz()
      Returns the current GPU memory clock speed.
      Returns:
      memory clock in MHz, or -1 if unavailable
      Throws:
      IllegalStateException - if the session has been closed; obtain a new session via GraphicsCard.createStatsSession()

    • getFanSpeedPercent

      double getFanSpeedPercent()
      Returns the GPU fan speed as a percentage of maximum.
      Returns:
      fan speed in the range 0.0 to 100.0, or -1 if unavailable
      Throws:
      IllegalStateException - if the session has been closed; obtain a new session via GraphicsCard.createStatsSession()