[DOC] Improve CUB environment documentation
- 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
Assessment
This issue has not been assessed yet.