TornadoDevice Interface and GPU Device Management API

TornadoVM abstracts every compute accelerator—NVIDIA GPUs, AMD GPUs, Intel iGPUs, FPGA devices, and the JVM itself—behind a single TornadoDevice interface. At startup the runtime discovers all available backends and enumerates their devices into an ordered list, sorted by compute capability and available memory. You interact with devices through a three-layer hierarchy: the TornadoRuntimeProvider singleton exposes the top-level TornadoRuntime; each TornadoRuntime holds one or more TornadoBackend objects (one per compiled backend); and each TornadoBackend exposes one or more TornadoDevice objects. Most applications need only the default device, but scientific workloads running on nodes with multiple GPUs will use the enumeration API to select a specific card by index, backend type, or memory capacity.

`TornadoRuntimeProvider` — the entry point

Package: uk.ac.manchester.tornado.api.runtime TornadoRuntimeProvider is a static utility class. It is initialized on first access via a ServiceLoader that loads the concrete runtime implementation.

TornadoRuntimeProvider.getTornadoRuntime()

static TornadoRuntime

Returns the singleton TornadoRuntime. This is the primary entry point for all device enumeration and selection.

TornadoRuntimeProvider.isProfilerEnabled()

static boolean

Returns true when TornadoVM profiling is active (-Dtornado.profiler=true).

TornadoRuntimeProvider.isPowerMonitoringEnabled()

static boolean

Returns true when NVIDIA NVML power monitoring is enabled.

TornadoRuntimeProvider.setProperty(String key, String value)

static void

Sets a TornadoVM runtime property programmatically (equivalent to a -D JVM flag).

`TornadoRuntime` interface

Package: uk.ac.manchester.tornado.api

getNumBackends()

int

Returns the number of installed and available backends (e.g. 2 if both OpenCL and CUDA are compiled in and find hardware).

getBackend(int index)

TornadoBackend

Returns the backend at the given index. Indices are stable within a process and match the order in which backends were loaded.

getBackend(Class<D> type)

<D extends TornadoBackend> D

Returns the backend of the given class type; useful for retrieving a CUDA-specific backend instance without knowing its index.

getBackendType(int index)

TornadoVMBackendType

Returns the TornadoVMBackendType enum value for the backend at index, without retrieving the full backend object.

getBackendIndex(Class<D> driverClass)

int

Returns the integer index of the backend whose class matches the argument, or −1 if not found.

getDefaultDevice()

TornadoDevice

Returns the highest-priority device across all backends. Priority is based on compute capability and memory; on a system with one CUDA GPU and one integrated OpenCL GPU, this will return the CUDA device.

setDefaultBackend(int index)

void

Changes which backend index is considered primary, affecting getDefaultDevice().

isProfilerEnabled()

boolean

Returns true when the TornadoVM profiler is active.

`TornadoBackend` interface

Package: uk.ac.manchester.tornado.api One TornadoBackend instance exists per loaded backend (OpenCL, CUDA, SPIR-V, Metal, Java). It enumerates the devices available through that backend.

getNumDevices()

int

Total number of accelerator devices visible to this backend (e.g. 2 for a dual-GPU node using the CUDA backend).

getDevice(int index)

TornadoDevice

Returns the TornadoDevice at the given index within this backend.

getAllDevices()

List<TornadoDevice>

Returns an unmodifiable list of all devices in this backend.

getDefaultDevice()

TornadoDevice

Returns the first (highest-priority) device within this backend.

setDefaultDevice(int index)

void

Promotes the device at index to the head of this backend’s internal device list, making it the default for this backend.

getName()

String

Returns a human-readable backend name (e.g. "OpenCL", "CUDADriver", "Metal").

getBackendType()

TornadoVMBackendType

Returns the TornadoVMBackendType enum value for this backend.

getNumPlatforms()

int

Returns the number of underlying platform instances (relevant for OpenCL, which may expose multiple platform drivers).

getTypeDefaultDevice()

TornadoDeviceType

Returns the hardware category (CPU, GPU, ACCELERATOR, CUSTOM) of the default device in this backend.

`TornadoDevice` interface

Package: uk.ac.manchester.tornado.api.common TornadoDevice is the principal handle for a single compute accelerator. Pass it to TornadoExecutionPlan.withDevice(TornadoDevice) to pin execution to a specific card.

Identification

getDeviceName()

String

Human-readable device name as reported by the driver (e.g. "NVIDIA GeForce RTX 4090", "AMD Radeon RX 7900 XTX").

getDescription()

String

Extended device description including driver and platform information.

getPlatformName()

String

Name of the underlying platform (e.g. the OpenCL platform or the CUDA toolkit version string).

getTornadoVMBackend()

TornadoVMBackendType

Returns the TornadoVMBackendType enum value for this device. Use this to branch on CUDA vs OpenCL at runtime.

getDeviceType()

TornadoDeviceType

Returns the hardware category: GPU, CPU, ACCELERATOR, CUSTOM, etc.

getBackendIndex()

int

Returns the index of the backend that owns this device (matches TornadoRuntime.getBackend(int)).

Memory

getMaxAllocMemory()

long

Maximum number of bytes that can be allocated in a single buffer on this device.

getMaxGlobalMemory()

long

Total global (device) memory in bytes.

getDeviceLocalMemorySize()

long

Size of local (shared) memory per compute unit in bytes.

Compute

getDeviceMaxWorkgroupDimensions()

long[]

Maximum work-group (thread block) dimensions as a long[3] array: [maxX, maxY, maxZ].

getDeviceOpenCLCVersion()

String

The OpenCL C language version supported by the device. Returns a backend-specific string for non-OpenCL devices.

getAvailableProcessors()

default int

Returns the number of processors available to the JVM. For physical GPU devices this delegates to Runtime.getRuntime().availableProcessors(); virtual devices override it to return the value from the descriptor file.

`TornadoVMBackendType` enum

Package: uk.ac.manchester.tornado.api.enums

Value	Description
`OPENCL`	OpenCL C backend — supports AMD, Intel, NVIDIA, and CPU OpenCL platforms.
`CUDA`	NVIDIA PTX / CUDA backend — required for library tasks (cuBLAS, cuDNN, etc.).
`METAL`	Apple Metal backend — macOS/iOS GPU acceleration via MSL.
`JAVA`	JVM fallback — runs code on the CPU without any GPU dispatch.
`VIRTUAL`	Virtual device — reads configuration from a descriptor file; used in testing and CI.

Enumerating all devices

The following example walks every backend and every device, printing their names, types, and memory budgets.

import uk.ac.manchester.tornado.api.TornadoBackend;
import uk.ac.manchester.tornado.api.TornadoRuntime;
import uk.ac.manchester.tornado.api.common.TornadoDevice;
import uk.ac.manchester.tornado.api.enums.TornadoVMBackendType;
import uk.ac.manchester.tornado.api.runtime.TornadoRuntimeProvider;

public class DeviceEnumeration {

    public static void main(String[] args) {
        TornadoRuntime runtime = TornadoRuntimeProvider.getTornadoRuntime();

        System.out.printf("TornadoVM found %d backend(s)%n", runtime.getNumBackends());

        for (int b = 0; b < runtime.getNumBackends(); b++) {
            TornadoBackend backend = runtime.getBackend(b);
            TornadoVMBackendType backendType = runtime.getBackendType(b);

            System.out.printf("%n  Backend [%d]: %s (%s), %d device(s)%n",
                b, backend.getName(), backendType, backend.getNumDevices());

            for (int d = 0; d < backend.getNumDevices(); d++) {
                TornadoDevice device = backend.getDevice(d);
                System.out.printf("    Device [%d:%d] %s%n", b, d, device.getDeviceName());
                System.out.printf("      Type:        %s%n", device.getDeviceType());
                System.out.printf("      Backend:     %s%n", device.getTornadoVMBackend());
                System.out.printf("      Global mem:  %,d MB%n",
                    device.getMaxGlobalMemory() / (1024 * 1024));
                System.out.printf("      Max alloc:   %,d MB%n",
                    device.getMaxAllocMemory() / (1024 * 1024));
                System.out.printf("      Local mem:   %,d KB%n",
                    device.getDeviceLocalMemorySize() / 1024);
            }
        }

        System.out.printf("%nDefault device: %s%n",
            runtime.getDefaultDevice().getDeviceName());
    }
}

Selecting a device for an execution plan

Pass a TornadoDevice to TornadoExecutionPlan.withDevice(TornadoDevice) to override the default selection.

By backend + index
By device index
Default device
Largest GPU by memory

import uk.ac.manchester.tornado.api.*;
import uk.ac.manchester.tornado.api.common.TornadoDevice;
import uk.ac.manchester.tornado.api.enums.TornadoVMBackendType;
import uk.ac.manchester.tornado.api.runtime.TornadoRuntimeProvider;

TornadoRuntime runtime = TornadoRuntimeProvider.getTornadoRuntime();

// Pick the first CUDA device by iterating backends
TornadoDevice cudaDevice = null;
for (int b = 0; b < runtime.getNumBackends(); b++) {
    if (runtime.getBackendType(b) == TornadoVMBackendType.CUDA) {
        cudaDevice = runtime.getBackend(b).getDevice(0);
        break;
    }
}

if (cudaDevice == null) {
    throw new RuntimeException("No CUDA device found");
}

ImmutableTaskGraph snapshot = myTaskGraph.snapshot();
try (TornadoExecutionPlan plan = new TornadoExecutionPlan(snapshot)) {
    plan.withDevice(cudaDevice).execute();
}

import uk.ac.manchester.tornado.api.*;
import uk.ac.manchester.tornado.api.common.TornadoDevice;
import uk.ac.manchester.tornado.api.runtime.TornadoRuntimeProvider;

// Backend 0, device 1 — second GPU on the first backend
TornadoDevice device =
    TornadoRuntimeProvider.getTornadoRuntime()
                          .getBackend(0)
                          .getDevice(1);

try (TornadoExecutionPlan plan = new TornadoExecutionPlan(myTaskGraph.snapshot())) {
    plan.withDevice(device).execute();
}

import uk.ac.manchester.tornado.api.*;
import uk.ac.manchester.tornado.api.common.TornadoDevice;
import uk.ac.manchester.tornado.api.runtime.TornadoRuntimeProvider;

// Uses the highest-priority device across all backends
TornadoDevice defaultDevice =
    TornadoRuntimeProvider.getTornadoRuntime().getDefaultDevice();

System.out.println("Running on: " + defaultDevice.getDeviceName());

try (TornadoExecutionPlan plan = new TornadoExecutionPlan(myTaskGraph.snapshot())) {
    plan.execute(); // implicitly uses the default device
}

import uk.ac.manchester.tornado.api.*;
import uk.ac.manchester.tornado.api.common.TornadoDevice;
import uk.ac.manchester.tornado.api.enums.TornadoDeviceType;
import uk.ac.manchester.tornado.api.runtime.TornadoRuntimeProvider;

TornadoRuntime runtime = TornadoRuntimeProvider.getTornadoRuntime();

TornadoDevice largest = null;
long maxMemory = 0;

for (int b = 0; b < runtime.getNumBackends(); b++) {
    var backend = runtime.getBackend(b);
    for (int d = 0; d < backend.getNumDevices(); d++) {
        TornadoDevice dev = backend.getDevice(d);
        if (dev.getDeviceType() == TornadoDeviceType.GPU
                && dev.getMaxGlobalMemory() > maxMemory) {
            largest = dev;
            maxMemory = dev.getMaxGlobalMemory();
        }
    }
}

System.out.printf("Largest GPU: %s (%.0f GB)%n",
    largest.getDeviceName(), maxMemory / 1e9);

Backend type quick-reference

OPENCL

Broadest hardware compatibility. Supports AMD, Intel, NVIDIA, and multi-core CPU targets via a single compilation path.

CUDA

Required for library tasks (cuBLAS, cuDNN, cuFFT, cuSPARSE, CUTLASS). Compiles Java kernels to PTX. Best raw throughput on NVIDIA hardware.

METAL

Apple GPU acceleration on macOS and iOS via Metal Shading Language. Requires an Apple Silicon or recent Intel Mac with a Metal-capable GPU.

JAVA

JVM fallback that runs TornadoVM kernels as plain Java on the CPU. Useful for debugging correctness before deploying to a GPU.

Check device.getTornadoVMBackend() == TornadoVMBackendType.CUDA before calling libraryTask in a TaskGraph. On non-CUDA backends the library task is silently skipped, which can cause result buffers to contain uninitialized data if you do not provide a CPU fallback.

Core API

Data Types

Library Tasks

TornadoDevice Interface and GPU Device Management API

`TornadoRuntimeProvider` — the entry point

`TornadoRuntime` interface

`TornadoBackend` interface

`TornadoDevice` interface

Identification

Memory

Compute

`TornadoVMBackendType` enum

Enumerating all devices

Selecting a device for an execution plan

Backend type quick-reference

OPENCL

CUDA

METAL

JAVA

Build docs developers (and LLMs) love

Core API

Data Types

Library Tasks

Documentation Index

​TornadoRuntimeProvider — the entry point

​TornadoRuntime interface

​TornadoBackend interface

​TornadoDevice interface

​Identification

​Memory

​Compute

​TornadoVMBackendType enum

​Enumerating all devices

​Selecting a device for an execution plan

​Backend type quick-reference

OPENCL

CUDA

METAL

JAVA

Build docs developers (and LLMs) love

`TornadoRuntimeProvider` — the entry point

`TornadoRuntime` interface

`TornadoBackend` interface

`TornadoDevice` interface

Identification

Memory

Compute

`TornadoVMBackendType` enum

Enumerating all devices

Selecting a device for an execution plan

Backend type quick-reference