rapidsai/cudf

[FEA] Document and apply the host-side span convention: prefer `std::span` unless device accessibility is needed

Open

#22560 opened on May 18, 2026

View on GitHub
 (4 comments) (2 reactions) (0 assignees)C++ (6,000 stars) (735 forks)batch import
good first issueimprovementlibcudf

Description

Is your feature request related to a problem? Please describe. There is no written guideline in https://github.com/rapidsai/cudf/blob/main/cpp/doxygen/developer_guide/DEVELOPER_GUIDE.md that says when to use cudf::host_span vs std::span. The story issue #20539 implies that cudf::host_span should be reserved for cases where is_device_accessible is needed (also brought up by @bdice at https://github.com/rapidsai/cudf/pull/22465#discussion_r3261981911): https://github.com/rapidsai/cudf/blob/f239649f8db9effa14bdf8dde589a515afc9444b/cpp/include/cudf/utilities/span.hpp#L284 In practice this is not consistently applied and new contributors have no way to know which to pick.

Describe the solution you'd like

  1. Add a short "When to use host_span vs std::span" subsection to the spans section of the developer guide: - Use std::span host-side data that does not need device-accessible tracking. - Use cudf::host_span only when you need its is_device_accessible flag (pinned memory, copy-engine optimizations) or implicit conversion from libcudf-specific containers that the standard span cannot accept.
  2. Migrate existing public APIs that take cudf::host_span purely as a host buffer view to std::span.

Describe alternatives you've considered

  • Status quo: keep relying on PR-review case-by-case correction. This is what is happening today and has produced the inconsistency above.
  • Make cudf::host_span itself a thin alias of std::span when is_device_accessible is not requested. Considered in #20539 and rejected because the device-accessible flag is a real piece of state that does not fit into a plain alias.

Contributor guide