[Dynamic Selection] Customization of Backends and Policies

[danhoeflinger]

Dynamic Selection API: Backend and Policy Customization & Removal of Selection API

This PR refactors the Dynamic Selection API to introduce a flexible backend architecture and simplify the user-facing API by removing the select() function. It provides better tools for customization of backend and policies to allow for easier customization and more flexibility for users.

Implements RFCs #2220 and #2489 (without token policy, that will be a separate PR).

Key Changes

Backend Architecture

• Added policy_base.h and default_backend.h to provide common base classes for policies and backends respectively
• Backends now accept ResourceAdapter function to support different flavors of resource with the same backend (e.g. sycl::queue vs sycl::queue*)

API Simplification

• Removed select() function - selections are now internal implementation details
• Addition of try_submit- always returns a std::optional quickly, returns empty if unable to obtain a resource
• Users now exclusively use try_submit, submit() and submit_and_wait() functions
• Policies expose try_select_impl() (returns std::optional) instead of public select()

Execution Info & Reporting

• Backends validate reporting requirements at construction and filter incompatible resources
• Clear runtime errors when no compatible resources remain after filtering

---

Summary of changes to look out for from individual components:

• Documentation:
  • Removal of public select API
• Examples:
  • Policy template argument adjustment (by resource first rather than backend)
• Policies:
  • Adjustment to use policy_base, remove repetative code
  • Implement try_select_impl instead of select
  • Implement initialize_impl instead of initialize
• Sycl Backend:
  • Conversion to partial specialization of default backend, use of backend_base
  • Addition of ResourceAdapter to support different flavors from a single base resource / backend
  • Improve system of reporting requirements for better filtering and error messages
  • Adjust support for profiling to require sycl extension for profiling (only reliable way to time)
    • Filter devices accordingly
• Tests:
  • Removal of testing of select before submit
  • Addition of default universe initialization testing
  • Addition of testing of use of resource adapter to support sycl::queue* in addition to sycl::queue

[Copilot]

Pull Request Overview

This PR refactors the Dynamic Selection API to enhance customizability and simplify the user interface by removing the public select() function and introducing a flexible backend architecture with ResourceAdapter support.

Key changes:

• Introduced policy_base.h and default_backend.h providing common base classes for policies and backends
• Removed public select() API - selections are now internal, with users exclusively using try_submit(), submit(), and submit_and_wait()
• Added ResourceAdapter support to backends, enabling different resource flavors (e.g., sycl::queue vs sycl::queue*)

Reviewed Changes

Copilot reviewed 38 out of 38 changed files in this pull request and generated 3 comments.

Show a summary per file

File	Description
test/support/utils_invoke.h	Added include for execution header
test/support/utils_dynamic_selection.h	New utility header with DummyResource and wait_type helper
test/support/test_offset_utils.h	Removed select-before-submit tests, updated to use get_wait_type helper
test/support/test_dynamic_selection_utils.h	Removed select tests, added default universe initialization test, updated wait_type access
test/support/test_dynamic_selection_one_policy.h	Updated test policies to use try_select_impl and removed selection-based submit variants
test/support/test_dynamic_load_utils.h	Removed select tests, added CustomName template param, updated adapter usage
test/support/iterator_utils.h	Moved is_const_iterator from internal namespace to local scope
test/support/inline_backend.h	Added ResourceAdapter support, enhanced comparison operators, added reporting validation
test/parallel_api/dynamic_selection/*.pass.cpp	Updated policy template arguments and removed select-before-submit test variants
include/oneapi/dpl/internal/dynamic_selection_traits.h	Removed select() API, added try_submit() support, updated submit interfaces
include/oneapi/dpl/internal/dynamic_selection_impl/sycl_backend.h	Converted to partial specialization of default_backend with profiling tag support
include/oneapi/dpl/internal/dynamic_selection_impl/round_robin_policy.h	Refactored to use policy_base, implements try_select_impl
include/oneapi/dpl/internal/dynamic_selection_impl/policy_traits.h	Removed selection_type and wait_type from policy traits
include/oneapi/dpl/internal/dynamic_selection_impl/policy_base.h	New base class providing common policy functionality
include/oneapi/dpl/internal/dynamic_selection_impl/fixed_resource_policy.h	Refactored to use policy_base
include/oneapi/dpl/internal/dynamic_selection_impl/dynamic_load_policy.h	Refactored to use policy_base with required reporting
include/oneapi/dpl/internal/dynamic_selection_impl/default_backend.h	New default backend implementation with resource adapter support
include/oneapi/dpl/internal/dynamic_selection_impl/backend_traits.h	Added scratch space traits and detection
include/oneapi/dpl/internal/dynamic_selection_impl/auto_tune_policy.h	Refactored to use policy_base, implements try_select_impl
include/oneapi/dpl/dynamic_selection	Added default_backend.h include
examples/dynamic_selection//src/.cpp	Updated policy template arguments from Backend to ResourceType
documentation/library_guide/dynamic_selection_api/*.rst	Removed select() and report() documentation

Comments suppressed due to low confidence (1)

include/oneapi/dpl/internal/dynamic_selection_impl/policy_base.h:1

• Using static_assert(false, ...) unconditionally will cause a compilation error. This should use a dependent false type trait like static_assert(sizeof(Policy) == 0, ...).

// -*- C++ -*-

---

💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.