NVIDIA / NVIDIA/cccl

[DOC] Improve CUB environment documentation

Open
#7,276 2 comments 0 reactions 2 assignees Claimed by @bernhardmgruber View on GitHub
Dominant language
C++
Stars
2.5k
Forks
486
Avg merge
2d 6h
Merged PRs (30d)
295

Description

The CUB device-wide algorithm documentation explains how to use the environment overloads by some examples: https://nvidia.github.io/cccl/cub/api_docs/device_wide.html#. However, this is too little information to properly understand and work with environments.

We should expand the documentation with:
- [ ] how to make user-defined types act like environments. We do this for example for `stream_ref` which is an environment that answers to the `get_stream` CPO, but how do other libraries achieve that?
- [ ] how to build and environment with and without the supporting functions like `require`, `tune`, etc. [partially handled #10043]
- [ ] when to use `prop`
- [ ] expected nesting of environments by CUB (e.g. the tuning environment is nested within the outer environment containing e.g. the memory resource)
- [ ] Document nvcc restrictions on function-scope policy-selector structs per this [comment](https://github.com/NVIDIA/cccl/issues/7712#issuecomment-3945347242)

We should also document what operations are supported on environments. This may go to the developer documentation:
- [ ] what functions can I call? Like `query_or` or `call_or`, etc.
- [ ] how do I extract a stream, memory resource, tuning, determinism, etc?
- [ ] what are the default values we should use of an environment query fails? [partially handled by https://github.com/NVIDIA/cccl/pull/10043]
- [ ] are environments copyable, movable, ..? How do we pass them around?
- [ ] what's a CPO?

Contributor guide

Open the contributing guide

Assessment

This issue has not been assessed yet.

Get new issues in your inbox

A short digest of beginner-friendly GitHub issues.