Ctrl+K

Device selectors

Device selectors#

Device selectors allow the SYCL runtime to choose the device.

A device selector can be passed to sycl::queue, sycl::platform, and other constructors to control the selection of a device. A program may use Built-in Device Selectors or define its own device selector for full control.

The interface for a device selector is any object that meets the C++ named requirement Callable taking a const sycl::device reference and returning a value implicitly convertible to a int.

At any point where the SYCL runtime needs to select a SYCL device using a device selector, the system queries all root devices from all SYCL backends in the system, calls the device selector on each device and selects the one which returns the highest score. If the highest value is strictly negative no device is selected.

In places where only one device has to be picked and the high score is obtained by more than one device, then one of the tied devices will be returned, but which one is not defined and may depend on enumeration order, for example, outside the control of the SYCL runtime.

Built-in Device Selectors#

Standard device selectors included with all SYCL implementations:

sycl::default_selector_v

Select a SYCL device from any supported SYCL backend based on an implementation-defined heuristic. Since all implementations must support at least one device, this selector must always return a device.

sycl::gpu_selector_v

Select a SYCL device from any supported SYCL backend for which the device type is info::device_type::gpu.

sycl::accelerator_selector_v

Select a SYCL device from any supported SYCL backend for which the device type is info::device_type::accelerator.

sycl::cpu_selector_v

Select a SYCL device from any supported SYCL backend for which the device type is info::device_type::cpu.

 
__unspecified_callable__
sycl::aspect_selector(const std::vector<aspect>& aspectList,
                      const std::vector<aspect>& denyList = {});

template <typename... AspectList>
__unspecified_callable__
sycl::aspect_selector(AspectList... aspectList);

template <aspect... AspectList>
__unspecified_callable__ sycl::aspect_selector();

The free function sycl::aspect_selector has several overloads, each of which returns a selector object that selects a SYCL device from any supported SYCL backend which contains all the requested aspects. If no aspects are passed in, the generated selector behaves like sycl::default_selector.

Required aspects can be passed in as a vector, as function arguments, or as template parameters, depending on the function overload. The function overload that takes aspectList as a vector takes another vector argument denyList where the user can specify all the aspects that have to be avoided.

The SYCL class constructor using sycl::gpu_selector_v, sycl::accelerator_selector_v, sycl::cpu_selector_v, or sycl::aspect_selector must throw an exception with the sycl::errc::runtime error code if no device matching the requirement can be found.

Device Selectors in SYCL 1.2.1#

In SYCL 1.2.1 the predefined device selectors were types that had to be instantiated to be used.

To simplify porting code using the old type instantiations, a backward-compatible API is still provided, such as sycl::default_selector.

The new predefined device selectors have their new names appended with "_v" to avoid conflicts, thus following the naming style used by traits in the C++ standard library.

See also

SYCL Specification Section 4.6.1.1

Example 1#

 1#include <sycl/sycl.hpp>
 2
 3int main() {
 4  sycl::device d;
 5
 6  try {
 7    d = sycl::device(sycl::gpu_selector_v);
 8  } catch (sycl::exception const &e) {
 9    std::cout << "Cannot select a GPU\n" << e.what() << "\n";
10    std::cout << "Using a CPU device\n";
11    d = sycl::device(sycl::cpu_selector_v);
12  }
13
14  std::cout << "Using " << d.get_info<sycl::info::device::name>();
15}

Output on a system without a GPU:

Cannot select a GPU
No device of requested type 'info::device_type::gpu' available. -1 (PI_ERROR_DEVICE_NOT_FOUND)
Using a CPU device
Using Intel(R) Core(TM) i7-7700K CPU @ 4.20GHz
Contents