Add support for running on Intel DPC++ SYCL devices

.github/workflows/ci.yml

@@ -105,6 +105,68 @@ jobs:
             cd $GITHUB_WORKSPACE
           done
 
+  sycl-cmake-test:
+    strategy:
+      fail-fast: false
+
+    runs-on: ubuntu-latest
+
+    steps:
+      - name: Intel Apt repository
+        timeout-minutes: 1
+        run: |
+          wget https://apt.repos.intel.com/intel-gpg-keys/GPG-PUB-KEY-INTEL-SW-PRODUCTS-2023.PUB
+          sudo apt-key add GPG-PUB-KEY-INTEL-SW-PRODUCTS-2023.PUB
+          rm GPG-PUB-KEY-INTEL-SW-PRODUCTS-2023.PUB
+          echo "deb https://apt.repos.intel.com/oneapi all main" | sudo tee /etc/apt/sources.list.d/oneAPI.list
+          sudo apt-get update
+      - name: Install Intel oneAPI compilers
+        timeout-minutes: 5
+        run: sudo apt-get install -y intel-oneapi-compiler-fortran intel-oneapi-compiler-dpcpp-cpp
+
+      - name: Setup Intel oneAPI environment
+        run: |
+          source /opt/intel/oneapi/setvars.sh
+          printenv >> $GITHUB_ENV
+
+      - uses: actions/checkout@v5
+
+      - name: Install Packages
+        run: |
+          sudo apt-get install -y cmake make
+      - name: Setup Boost
+        run: |
+          echo GITHUB_REPOSITORY: $GITHUB_REPOSITORY
+          LIBRARY=${GITHUB_REPOSITORY#*/}
+          echo LIBRARY: $LIBRARY
+          echo "LIBRARY=$LIBRARY" >> $GITHUB_ENV
+          echo GITHUB_BASE_REF: $GITHUB_BASE_REF
+          echo GITHUB_REF: $GITHUB_REF
+          REF=${GITHUB_BASE_REF:-$GITHUB_REF}
+          REF=${REF#refs/heads/}
+          echo REF: $REF
+          BOOST_BRANCH=develop && [ "$REF" == "master" ] && BOOST_BRANCH=master || true
+          echo BOOST_BRANCH: $BOOST_BRANCH
+          cd ..
+          git clone -b $BOOST_BRANCH --depth 1 https://github.com/boostorg/boost.git boost-root
+          cd boost-root
+          mkdir -p libs/$LIBRARY
+          cp -r $GITHUB_WORKSPACE/* libs/$LIBRARY
+          git submodule update --init tools/boostdep
+          python3 tools/boostdep/depinst/depinst.py --git_args "--jobs 3" $LIBRARY
+      - name: Test C++20
+        run: |
+          for std in 20; do
+            echo "======== Testing C++${std} ========"
+            cd ../boost-root
+            rm -rf __build__
+            mkdir __build__ && cd __build__
+            cmake -DBOOST_INCLUDE_LIBRARIES=$LIBRARY -DBUILD_TESTING=ON -DBOOST_SAFE_NUMBERS_ENABLE_SYCL=ON -DCMAKE_CXX_COMPILER=icpx -DCMAKE_C_COMPILER=icx -DCMAKE_CXX_STANDARD=${std} ..
+            cmake --build . --target tests -j $(nproc)
+            ctest --output-on-failure --no-tests=error
+            cd $GITHUB_WORKSPACE
+          done
+
   compile-time-checks:
     name: Compile-time checks (GCC)
     runs-on: ubuntu-latest

doc/modules/ROOT/nav.adoc

@@ -27,6 +27,8 @@
 ** xref:examples.adoc#examples_cuda_error_handling[CUDA Error Handling]
 *** xref:examples.adoc#examples_cuda_error_handling_with_error_context[With Safe_Numbers Error Context]
 *** xref:examples.adoc#examples_cuda_error_handling_without_error_context[Without Safe_Numbers Error Context]
+** xref:examples.adoc#examples_sycl[SYCL Device Support]
+** xref:examples.adoc#examples_sycl_error_handling[SYCL Error Handling]
 * xref:pretty_printers.adoc[]
 * xref:api_reference.adoc[]
 ** xref:api_reference.adoc#api_namespaces[Namespaces]
@@ -41,6 +43,7 @@
 * xref:bounded_int.adoc[]
 * xref:bounded_float.adoc[]
 * xref:cuda.adoc[]
+* xref:sycl.adoc[]
 * xref:literals.adoc[]
 * Standard Library Support
 ** xref:limits.adoc[]

doc/modules/ROOT/pages/api_reference.adoc

@@ -136,6 +136,35 @@ https://www.boost.org/LICENSE_1_0.txt
 | Synchronizes the device, checks for captured errors, and throws the corresponding host exception
 |===
 
+=== SYCL Support
+
+[cols="1,2", options="header"]
+|===
+| Type | Description
+
+| xref:sycl.adoc#sycl_device_error_context[`device_error_context`]
+| SYCL error context bound to a queue; the device records errors implicitly and `synchronize()` rethrows them on the host
+
+| xref:sycl.adoc#sycl_device_exception_mode[`device_exception_mode`]
+| Shared with the CUDA backend; always deferred under SYCL
+|===
+
+==== `device_error_context` Member Functions (SYCL)
+
+[cols="1,2", options="header"]
+|===
+| Function | Description
+
+| xref:sycl.adoc#sycl_device_error_context_reset[`reset`]
+| Zeroes the device error buffer so the context can be reused across launches
+
+| xref:sycl.adoc#sycl_device_error_context_set_mode[`set_device_exception_method`]
+| Records the exception mode after construction (advisory under SYCL)
+
+| xref:sycl.adoc#sycl_device_error_context_synchronize[`synchronize`]
+| Waits for the queue, reads the device buffer, and throws the matching host exception
+|===
+
 [#api_functions]
 == Functions
 
@@ -465,6 +494,6 @@ This header is not included in the convenience header since it requires external
 | `<boost/safe_numbers/byte_conversions.hpp>`
 | Byte order conversion functions (`to_be`, `from_be`, `to_le`, `from_le`, `to_be_bytes`, `from_be_bytes`, `to_le_bytes`, `from_le_bytes`, `to_ne_bytes`, `from_ne_bytes`)
 
-| `<boost/safe_numbers/cuda_error_reporting.hpp>`
-| CUDA device error handling (`device_exception_mode`, `device_error_context`)
+| `<boost/safe_numbers/device_error_reporting.hpp>`
+| CUDA and SYCL device error handling (`device_exception_mode`, `device_error_context`)
 |===

doc/modules/ROOT/pages/cuda.adoc

@@ -145,7 +145,7 @@ See xref:examples.adoc#examples_cuda_bounded[the bounded-types CUDA example].
 
 [source,c++]
 ----
-#include <boost/safe_numbers/cuda_error_reporting.hpp>
+#include <boost/safe_numbers/device_error_reporting.hpp>
 
 namespace boost::safe_numbers {
 
@@ -191,7 +191,7 @@ boost::safe_numbers::device_error_context ctx{boost::safe_numbers::untrapped};
 
 [source,c++]
 ----
-#include <boost/safe_numbers/cuda_error_reporting.hpp>
+#include <boost/safe_numbers/device_error_reporting.hpp>
 
 namespace boost::safe_numbers {
 

doc/modules/ROOT/pages/examples.adoc

@@ -848,3 +848,45 @@ Kernel has been reset via CUDA API
 Kernel failed with error: CUDA-capable device(s) is/are busy or unavailable
 ----
 ====
+
+[#examples_sycl]
+== SYCL Device Support
+
+With `BOOST_SAFE_NUMBERS_ENABLE_SYCL` defined and `<sycl/sycl.hpp>` included first, the safe_numbers types run inside SYCL device kernels compiled with `icpx -fsycl`.
+This example runs `u128` arithmetic element-wise on a SYCL device over shared memory and verifies the device results against a host recomputation.
+
+.This https://github.com/boostorg/safe_numbers/blob/develop/examples/sycl.cpp[example] demonstrates safe_numbers arithmetic running on a SYCL device.
+====
+[source, c++]
+----
+include::example$sycl.cpp[]
+----
+
+Output:
+----
+Running on: Intel(R) Data Center GPU
+All CPU and GPU computed elements match!
+----
+====
+
+[#examples_sycl_error_handling]
+== SYCL Error Handling
+
+A SYCL device kernel cannot throw, so a safe_numbers error is recorded on the device and rethrown on the host by `device_error_context::synchronize()`.
+This example forces a `bounded_uint` result out of its declared range on the device and catches the resulting `std::domain_error` on the host.
+
+.This https://github.com/boostorg/safe_numbers/blob/develop/examples/sycl_error_handling.cpp[example] demonstrates catching a device-side error on the host using `device_error_context`.
+====
+[source, c++]
+----
+include::example$sycl_error_handling.cpp[]
+----
+
+Output:
+----
+Running on: Intel(R) Data Center GPU
+Caught expected device error on the host: Device error on thread 0 at .../boost/safe_numbers/include/boost/safe_numbers/bounded_integers.hpp:215: bounded_uint addition result out of range
+----
+====
+
+The reported thread is the failing work-item's global linear id (here `0`, since every element fails and the first work-item wins the recording race); with a single bad input element the id pinpoints it exactly, as on CUDA.