GPUDeviceManager

Namespace: parallel.gpu

Manager for GPU Devices

Description

parallel.gpu.GPUDeviceManager broadcasts events that indicate when a GPU device is selected, deselected, or reset. Use parallel.gpu.GPUDeviceManager to set up notifications that inform you when your GPU device is selected, deselected, or reset without having to call gpuDevice or monitor data stored on the GPU. You can also use parallel.gpu.GPUDeviceManager to automatically change your GPU settings when a GPU is selected.

Creation

Description

gdm = parallel.gpu.GPUDeviceManager.instance accesses the GPU device manager gdm that broadcasts events that indicate when a GPU device is selected, deselected, or reset.

Note

You can only use one instance of parallel.gpu.GPUDeviceManager available in a given MATLAB session.

Properties

SelectedDevice — Selected GPU device

GPUDevice object

The selected GPU device, specified as a GPUDevice object. If no GPU device is selected, then the property is an empty GPUDevice array.

Attributes:

GetAccess

public

Methods

Public Methods

selectDevice

device = selectDevice(gdm,index) Select the GPU device with the specified index, update the SelectedDevice property of the parallel.gpu.GPUDeviceManager object gdm, and return a GPUDevice object. Input Arguments: gdm - parallel.gpu.GPUDeviceManager object. index - Index of desired GPU device, specified as an integer in the range [1, gpuDeviceCount]. Return Value: device - Selected GPUDevice object. Note Alternatively, use device = gpuDevice(index).

getDeviceCount

count = getDeviceCount(gdm) Return the number of available GPU devices. Input Arguments: gdm - parallel.gpu.GPUDeviceManager object. Output Arguments: count - Number of available GPU devices. Note Alternatively, use count = gpuDeviceCount.

Events

Event Name	Trigger	Event Data	Event Attributes
DeviceSelected	Triggered after a GPU device is selected.	parallel.gpu.GPUDeviceEventData Properties: DeviceIndex - Index of the selected GPU device.	NotifyAccess: private ListenAccess: public
DeviceDeselecting	Triggered just before a GPU device is deselected.	parallel.gpu.GPUDeviceEventData Properties: DeviceIndex - Index of the GPU device being deselected.	NotifyAccess: private ListenAccess: public

Note

When you reset a GPU device, the software triggers DeviceDeselecting and then DeviceSelected.

For more information about using events, see the examples on this page and Overview Events and Listeners.

Examples

Create GPU Device Manager Object

Create a parallel.gpu.DeviceManager object.

gdm = parallel.gpu.GPUDeviceManager.instance

gdm = 
  GPUDeviceManager with properties:

    SelectedDevice: [0×0 parallel.gpu.CUDADevice]

Select a GPU device and use the GPU device manager to inspect the selected GPU device.

gpu = gpuDevice;
gdm.SelectedDevice

ans = 
  CUDADevice with properties:

                 Name: 'NVIDIA RTX A5000'
                Index: 1 (of 2)
    ComputeCapability: '8.6'
          DriverModel: 'TCC'
          TotalMemory: 25544294400 (25.54 GB)
      AvailableMemory: 25120866304 (25.12 GB)
      DeviceAvailable: true
       DeviceSelected: true

  Show all properties.

Use GPU Device Manager to Report GPU Changes

Create a parallel.gpu.DeviceManager object.

gdm = parallel.gpu.GPUDeviceManager.instance;

Create callback functions that the software calls when a GPU device is selected or about to be deselected. These functions display the device index of the GPU and whether it has been selected or deselected. Even if they are not used, callback functions must define at least two input arguments: the event source and the event data. For more information, see Overview Events and Listeners.

selectedMessage = @(source,event) disp("GPU device " + event.DeviceIndex + " selected.");
deselectedMessage = @(source,event) disp("GPU device " + event.DeviceIndex + " deselected.");

Create event listeners, bound to the DeviceSelected and DeviceDeselecting events of the GPU device manager gdm, that call the callback functions.

selectedListener = listener(gdm,"DeviceSelected",selectedMessage);
deselectedListener = listener(gdm,"DeviceDeselecting",deselectedMessage);

To check that the callback functions and listeners are configured correctly, select and deselect your GPU.

gpuDevice;

GPU device 1 selected.

gpuDevice([]);

GPU device 1 deselected.

To remove the listeners, delete the listener objects.

delete(selectedListener)
delete(deselectedListener)

Use GPU Device Manager to Change GPU Settings

Create a parallel.gpu.DeviceManager object.

gdm = parallel.gpu.GPUDeviceManager.instance;

Create a function handle to the setCachePolicy function. The setCachePolicy function, defined at the end of this example, changes the caching policy of the selected GPU to 'maximum'.

selectedFcn = @(source,event) setCachePolicy(source);

Create an event listener, bound to the DeviceSelected event of the GPU device manager gdm, that calls the callback function selectedFcn. The software sets the caching policy to 'maximum' when a new GPU device is selected. The cachePolicy property of a gpuDevice object determines how much GPU memory can be cached to accelerate computation.

selectedListener = listener(gdm,"DeviceSelected",selectedFcn);

To check that the callback function and listener are configured correctly, deselect any already selected GPUs, then select your GPU and inspect its CachePolicy property.

gpuDevice([]);
gpu = gpuDevice;

NVIDIA RTX A5000 GPU selected.
Current caching policy: balanced
Setting caching policy to maximum.

gpu.CachePolicy

ans = 
'maximum'

To remove the listener, delete the listener object.

delete(selectedListener)

Set Cache Policy Function

The setCachePolicy function receives a GPU device manager object source and changes the caching policy of the currently selected GPU device.

function setCachePolicy(gdm)

% Display selected GPU name and caching policy.
disp(gdm.SelectedDevice.Name + " GPU selected.")
disp("Current caching policy: " + gdm.SelectedDevice.CachePolicy)

% Set the caching policy to maximum.
disp("Setting caching policy to maximum.")
gdm.SelectedDevice.CachePolicy = "maximum";

end

Extended Capabilities

Thread-Based Environment

Run code in the background using MATLAB® backgroundPool or accelerate code with Parallel Computing Toolbox™ ThreadPool.

This function fully supports thread-based environments. For more information, see Run MATLAB Functions in Thread-Based Environment.

Version History

Introduced in R2016a