[SYCL] Deprecate SYCL 1.2.1 device selectors (#6599)

Now that we have added the SYCL 2020 callable device selectors, we need
to prepare for the removal of the older SYCL 1.2.1 `device_selector`
class. The first step is to add the deprecation message to the 1.2.1
style device selectors, which this PR does. It also removes the usage of
those from our own codebase so as to not trip on our own messages in the
future.

Signed-off-by: Chris Perkins <chris.perkins@intel.com>
Signed-off-by: Larsen, Steffen <steffen.larsen@intel.com>
Co-authored-by: Larsen, Steffen <steffen.larsen@intel.com>

Author: cperkinsintel

sycl/doc/GetStartedGuide.md

@@ -705,7 +705,7 @@ SYCL_BE=PI_CUDA ./simple-sycl-app-cuda.exe
 ```
 
 **NOTE**: DPC++/SYCL developers can specify SYCL device for execution using
-device selectors (e.g. `sycl::cpu_selector`, `sycl::gpu_selector`,
+device selectors (e.g. `sycl::cpu_selector_v`, `sycl::gpu_selector_v`,
 [Intel FPGA selector(s)](extensions/supported/sycl_ext_intel_fpga_device_selector.md)) as
 explained in following section [Code the program for a specific
 GPU](#code-the-program-for-a-specific-gpu).
@@ -740,42 +740,38 @@ the CMake.
 
 ### Code the program for a specific GPU
 
-To specify OpenCL device SYCL provides the abstract `sycl::device_selector`
-class which the can be used to define how the runtime should select the best
-device.
-
-The method `sycl::device_selector::operator()` of the SYCL
-`sycl::device_selector` is an abstract member function which takes a
-reference to a SYCL device and returns an integer score. This abstract member
-function can be implemented in a derived class to provide a logic for selecting
-a SYCL device. SYCL runtime uses the device for with the highest score is
-returned. Such object can be passed to `sycl::queue` and `sycl::device`
-constructors.
-
-The example below illustrates how to use `sycl::device_selector` to create
-device and queue objects bound to Intel GPU device:
+To assist in finding a specific SYCL compatible device out of all that may be
+available, a "device selector" may be used. A "device selector" is a ranking
+function (C++ Callable) that will give an integer ranking value to all the
+devices on the system. It can be passed to `sycl::queue`, `sycl::device` and
+`sycl::platform` constructors. The highest ranking device is then selected. SYCL
+has built-in device selectors for selecting a generic GPU, CPU, or accelerator
+device, as well as one for a default device. Additionally, a user can define
+their own as function, lambda, or functor class. Device selectors returning
+negative values will "reject" a device ensuring it is not selected, but values 0
+or higher will be selected by the highest score with ties resolved by an
+internal algorithm (see Section 4.6.1 of the SYCL 2020 specification)
+
+The example below illustrates how to use a device selector to create device and
+queue objects bound to Intel GPU device:
 
 ```c++
 #include <sycl/sycl.hpp>
 
 int main() {
-  class NEOGPUDeviceSelector : public sycl::device_selector {
-  public:
-    int operator()(const sycl::device &Device) const override {
-      using namespace sycl::info;
 
-      const std::string DeviceName = Device.get_info<device::name>();
-      const std::string DeviceVendor = Device.get_info<device::vendor>();
+  auto NEOGPUDeviceSelector = [](const sycl::device &Device){
+    using namespace sycl::info;
 
-      return Device.is_gpu() && (DeviceName.find("HD Graphics NEO") != std::string::npos);
-    }
+    const std::string DeviceName = Device.get_info<device::name>();
+    bool match = Device.is_gpu() && (DeviceName.find("HD Graphics NEO") != std::string::npos);
+    return match ? 1 : -1;
   };
 
-  NEOGPUDeviceSelector Selector;
   try {
-    sycl::queue Queue(Selector);
-    sycl::device Device(Selector);
-  } catch (sycl::invalid_parameter_error &E) {
+    sycl::queue Queue(NEOGPUDeviceSelector);
+    sycl::device Device(NEOGPUDeviceSelector);
+  } catch (sycl::exception &E) {
     std::cout << E.what() << std::endl;
   }
 }
@@ -786,19 +782,18 @@ The device selector below selects an NVIDIA device only, and won't execute if
 there is none.
 
 ```c++
-class CUDASelector : public sycl::device_selector {
-  public:
-    int operator()(const sycl::device &Device) const override {
-      using namespace sycl::info;
-      const std::string DriverVersion = Device.get_info<device::driver_version>();
-
-      if (Device.is_gpu() && (DriverVersion.find("CUDA") != std::string::npos)) {
-        std::cout << " CUDA device found " << std::endl;
-        return 1;
-      };
-      return -1;
-    }
-};
+
+int CUDASelector(const sycl::device &Device) {
+  using namespace sycl::info;
+  const std::string DriverVersion = Device.get_info<device::driver_version>();
+
+  if (Device.is_gpu() && (DriverVersion.find("CUDA") != std::string::npos)) {
+    std::cout << " CUDA device found " << std::endl;
+    return 1;
+  };
+  return -1;
+}
+
 ```
 
 ### Using the DPC++ toolchain on CUDA platforms

sycl/doc/MultiTileCardWithLevelZero.md

@@ -143,8 +143,7 @@ try {
 ``` C++	
 try {
   // The queue is attached to the root-device, driver distributes to sub-devices, if any.
-  auto D = device(gpu_selector{});
-  auto Q = queue(D);
+  auto Q = queue(gpu_selector_v);
   Q.submit([&](handler& cgh) {...});
 }
 ```
@@ -155,7 +154,7 @@ try {
 - Example:
 ``` C++	
 try {
-  auto P = platform(gpu_selector{});
+  auto P = platform(gpu_selector_v);
   auto RootDevices = P.get_devices();
   auto C = context(RootDevices);
   for (auto &D : RootDevices) {

sycl/doc/design/GlobalObjectsInRuntime.md

@@ -22,7 +22,7 @@ like in example below:
 sycl::queue Queue;
 
 int main() {
-  Queue = sycl::queue{sycl::default_selector{}.select_device()};
+  Queue = sycl::queue{sycl::default_selector_v};
 
   return 0;
 }

sycl/doc/extensions/experimental/sycl_ext_intel_esimd/sycl_ext_intel_esimd.md

@@ -660,7 +660,7 @@ int main(void) {
   int err_cnt = 0;
 
   try {
-    queue q(gpu_selector{}, createExceptionHandler());
+    queue q(gpu_selector_v, createExceptionHandler());
     auto dev = q.get_device();
     std::cout << "Running on " << dev.get_info<info::device::name>() << "\n";
 

sycl/doc/extensions/experimental/sycl_ext_oneapi_max_work_group_query.md

@@ -34,7 +34,7 @@ As encouraged by the SYCL specification, a feature-test macro, `SYCL_EXT_ONEAPI_
 ## Examples
 
 ```c++
-sycl::device gpu = sycl::device{sycl::gpu_selector{}};
+sycl::device gpu = sycl::device{sycl::gpu_selector_v};
 std::cout << gpu.get_info<sycl::info::device::name>() << '\n';
 
 #ifdef SYCL_EXT_ONEAPI_MAX_WORK_GROUP_QUERY

sycl/include/sycl/device.hpp

@@ -61,6 +61,8 @@ class __SYCL_EXPORT device {
   /// by the DeviceSelector provided.
   ///
   /// \param DeviceSelector SYCL 1.2.1 device_selector to be used (see 4.6.1.1).
+  __SYCL2020_DEPRECATED("Use Callable device selectors instead of deprecated "
+                        "device_selector subclasses.")
   explicit device(const device_selector &DeviceSelector);
 
 #if __cplusplus >= 201703L

sycl/include/sycl/device_selector.hpp

@@ -31,7 +31,8 @@ class filter_selector;
 /// \sa device
 ///
 /// \ingroup sycl_api_dev_sel
-class __SYCL_EXPORT device_selector {
+class __SYCL_EXPORT __SYCL2020_DEPRECATED(
+    "Use Callable instead to select device.") device_selector {
 
 public:
   virtual ~device_selector() = default;
@@ -46,7 +47,9 @@ class __SYCL_EXPORT device_selector {
 /// \sa device
 ///
 /// \ingroup sycl_api_dev_sel
-class __SYCL_EXPORT default_selector : public device_selector {
+class __SYCL_EXPORT __SYCL2020_DEPRECATED(
+    "Use the callable sycl::default_selector_v instead.") default_selector
+    : public device_selector {
 public:
   int operator()(const device &dev) const override;
 };
@@ -56,7 +59,9 @@ class __SYCL_EXPORT default_selector : public device_selector {
 /// \sa device
 ///
 /// \ingroup sycl_api_dev_sel
-class __SYCL_EXPORT gpu_selector : public device_selector {
+class __SYCL_EXPORT __SYCL2020_DEPRECATED(
+    "Use the callable sycl::gpu_selector_v instead.") gpu_selector
+    : public device_selector {
 public:
   int operator()(const device &dev) const override;
 };
@@ -66,7 +71,9 @@ class __SYCL_EXPORT gpu_selector : public device_selector {
 /// \sa device
 ///
 /// \ingroup sycl_api_dev_sel
-class __SYCL_EXPORT cpu_selector : public device_selector {
+class __SYCL_EXPORT __SYCL2020_DEPRECATED(
+    "Use the callable sycl::cpu_selector_v instead.") cpu_selector
+    : public device_selector {
 public:
   int operator()(const device &dev) const override;
 };
@@ -76,7 +83,9 @@ class __SYCL_EXPORT cpu_selector : public device_selector {
 /// \sa device
 ///
 /// \ingroup sycl_api_dev_sel
-class __SYCL_EXPORT accelerator_selector : public device_selector {
+class __SYCL_EXPORT
+__SYCL2020_DEPRECATED("Use the callable sycl::accelerator_selector_v instead.")
+    accelerator_selector : public device_selector {
 public:
   int operator()(const device &dev) const override;
 };
@@ -86,7 +95,9 @@ class __SYCL_EXPORT accelerator_selector : public device_selector {
 /// \sa device
 ///
 /// \ingroup sycl_api_dev_sel
-class __SYCL_EXPORT host_selector : public device_selector {
+class __SYCL_EXPORT
+__SYCL2020_DEPRECATED("Use a callable function instead.") host_selector
+    : public device_selector {
 public:
   int operator()(const device &dev) const override;
 };

sycl/include/sycl/platform.hpp

@@ -64,6 +64,8 @@ class __SYCL_EXPORT platform {
   /// provided device selector.
   ///
   /// \param DeviceSelector is an instance of a SYCL 1.2.1 device_selector
+  __SYCL2020_DEPRECATED("Use Callable device selectors instead of deprecated "
+                        "device_selector subclasses.")
   explicit platform(const device_selector &DeviceSelector);
 
 #if __cplusplus >= 201703L

sycl/include/sycl/queue.hpp

@@ -163,6 +163,8 @@ class __SYCL_EXPORT queue {
   ///
   /// \param DeviceSelector is an instance of a SYCL 1.2.1 device_selector.
   /// \param PropList is a list of properties for queue construction.
+  __SYCL2020_DEPRECATED("Use Callable device selectors instead of deprecated "
+                        "device_selector subclasses.")
   queue(const device_selector &DeviceSelector,
         const property_list &PropList = {})
       : queue(DeviceSelector.select_device(), async_handler{}, PropList) {}
@@ -173,6 +175,8 @@ class __SYCL_EXPORT queue {
   /// \param DeviceSelector is an instance of SYCL 1.2.1 device_selector.
   /// \param AsyncHandler is a SYCL asynchronous exception handler.
   /// \param PropList is a list of properties for queue construction.
+  __SYCL2020_DEPRECATED("Use Callable device selectors instead of deprecated "
+                        "device_selector subclasses.")
   queue(const device_selector &DeviceSelector,
         const async_handler &AsyncHandler, const property_list &PropList = {})
       : queue(DeviceSelector.select_device(), AsyncHandler, PropList) {}
@@ -199,6 +203,8 @@ class __SYCL_EXPORT queue {
   /// \param SyclContext is an instance of SYCL context.
   /// \param DeviceSelector is an instance of SYCL device selector.
   /// \param PropList is a list of properties for queue construction.
+  __SYCL2020_DEPRECATED("Use Callable device selectors instead of deprecated "
+                        "device_selector subclasses.")
   queue(const context &SyclContext, const device_selector &DeviceSelector,
         const property_list &PropList = {});
 
@@ -210,6 +216,8 @@ class __SYCL_EXPORT queue {
   /// \param DeviceSelector is an instance of SYCL device selector.
   /// \param AsyncHandler is a SYCL asynchronous exception handler.
   /// \param PropList is a list of properties for queue construction.
+  __SYCL2020_DEPRECATED("Use Callable device selectors instead of deprecated "
+                        "device_selector subclasses.")
   queue(const context &SyclContext, const device_selector &DeviceSelector,
         const async_handler &AsyncHandler, const property_list &PropList = {});
 

sycl/test/basic_tests/accessor/atomic_zero_dimension_accessor.cpp

@@ -19,7 +19,7 @@ void store(atomic_t foo, int value) { foo.store(value); }
 
 int main(int argc, char *argv[]) {
 
-  queue q(default_selector{});
+  queue q(default_selector_v);
 
   // Accessor with dimensionality 0.
   {