Class NvmlUtil

java.lang.Object
oshi.util.gpu.NvmlUtil
@ThreadSafe public final class NvmlUtil extends Object
Optional runtime binding to the NVIDIA Management Library (NVML). All methods return sentinel values (-1 or -1L) when NVML is unavailable or a specific query fails.

The native library is loaded once at class initialization. Each metric call pairs nvmlInit_v2 with nvmlShutdown to correctly manage NVML's internal reference count, ensuring OSHI does not interfere with other code in the same process that may also be managing the NVML lifecycle.

Device handles are enumerated once on first successful init and cached by PCI bus ID string for correlation with OSHI GraphicsCard instances.

  • Method Details

    • isAvailable

      public static boolean isAvailable()
      Returns whether the NVML native library was successfully loaded. Does not indicate whether any NVIDIA GPU is present or whether nvmlInit_v2 will succeed.
      Returns:
      true if the NVML library is available

    • findDevice

      public static String findDevice(String pciBusId)
      Finds the stable PCI bus ID string for the NVML device whose bus ID contains the given fragment. The match is case-insensitive and uses substring matching to accommodate domain-qualified vs. non-qualified forms.

      Returns a stable string identifier rather than a device handle. Handles are only valid within a single nvmlInit/nvmlShutdown scope; returning one across that boundary would leave the caller with a stale pointer. Callers should pass the returned string to the metric methods, which re-acquire a fresh handle internally.

      Parameters:
      pciBusId - PCI bus ID fragment (e.g. "0000:01:00.0" or "01:00.0")
      Returns:
      matched PCI bus ID string, or null if not found or NVML unavailable

    • findDeviceByName

      public static String findDeviceByName(String gpuName)
      Finds the stable PCI bus ID string for the NVML device whose name matches the given GPU name. Used as a fallback when PCI bus ID is unavailable.

      Returns a stable string identifier rather than a device handle for the same reason as findDevice(String).

      Parameters:
      gpuName - GPU name string (case-insensitive substring match)
      Returns:
      PCI bus ID string of the matched device, or null if not found or NVML unavailable

    • getGpuUtilization

      public static double getGpuUtilization(String deviceId)
      Returns GPU core utilization percentage (0–100), or -1 if unavailable.
      Parameters:
      deviceId - stable device identifier returned by findDevice(String) or findDeviceByName(String)
      Returns:
      utilization percentage or -1

    • getVramUsed

      public static long getVramUsed(String deviceId)
      Returns VRAM used in bytes, or -1 if unavailable.
      Parameters:
      deviceId - stable device identifier returned by findDevice(String) or findDeviceByName(String)
      Returns:
      bytes used or -1

    • getTemperature

      public static double getTemperature(String deviceId)
      Returns GPU temperature in degrees Celsius, or -1 if unavailable.
      Parameters:
      deviceId - stable device identifier returned by findDevice(String) or findDeviceByName(String)
      Returns:
      temperature in °C or -1

    • getPowerDraw

      public static double getPowerDraw(String deviceId)
      Returns GPU power draw in watts, or -1 if unavailable.
      Parameters:
      deviceId - stable device identifier returned by findDevice(String) or findDeviceByName(String)
      Returns:
      power in watts or -1

    • getCoreClockMhz

      public static long getCoreClockMhz(String deviceId)
      Returns GPU core clock speed in MHz, or -1 if unavailable.
      Parameters:
      deviceId - stable device identifier returned by findDevice(String) or findDeviceByName(String)
      Returns:
      core clock in MHz or -1

    • getMemoryClockMhz

      public static long getMemoryClockMhz(String deviceId)
      Returns GPU memory clock speed in MHz, or -1 if unavailable.
      Parameters:
      deviceId - stable device identifier returned by findDevice(String) or findDeviceByName(String)
      Returns:
      memory clock in MHz or -1

    • getFanSpeedPercent

      public static double getFanSpeedPercent(String deviceId)
      Returns GPU fan speed as a percentage (0–100), or -1 if unavailable.
      Parameters:
      deviceId - stable device identifier returned by findDevice(String) or findDeviceByName(String)
      Returns:
      fan speed percentage or -1