Skip to content

[docs] Add docs for cudax::coop::group_as - #12256

Open
davebayer wants to merge 1 commit into
NVIDIA:mainfrom
davebayer:groups_group_as_docs
Open

davebayer wants to merge 1 commit into
NVIDIA:mainfrom
davebayer:groups_group_as_docs

Conversation

@davebayer

Copy link
Copy Markdown
Contributor

No description provided.

@davebayer
davebayer requested a review from a team as a code owner October 26, 2026 12:43
@davebayer
davebayer requested a review from miscco October 26, 2026 12:43
@github-project-automation github-project-automation Bot moved this to Todo in CCCL Oct 26, 2026
@cccl-authenticator-app cccl-authenticator-app Bot moved this from Todo to In Review in CCCL Oct 26, 2026
@coderabbitai

coderabbitai Bot commented Oct 26, 2026 •

Copy link
Copy Markdown
Contributor

Review in Change Stack →

📝 Summary

Summary by CodeRabbit

  • Documentation
    • Added a class-template synopsis and deduction guide for group_as, with guidance on supported range types.
    • Clarified how unit counts map groups, the requirements for valid counts and totals, and how non-exhaustive mappings can leave trailing units ungrouped.
    • Added an example using subgroup sizes of 4, 12, and 16.
  • API Changes
    • Made range-based group_as construction explicit, preventing implicit conversions.

The group_as range constructor is now explicit. Its reference page documents the template interface and deduction guide, mapping rules and requirements, and a CUDA example using unit counts {4, 12, 16}.

Changes: group_as interface and documentation

Layer / File(s) Summary
Interface, mapping rules, and example
cudax/include/cuda/experimental/coop/__group/mapping/group_as.cuh, docs/cudax/coop/group/mapping/group_as.rst
The range constructor is explicit. The reference page documents the constrained range interface and deduction guide, subgroup assignment and mapping requirements, and an example using unit counts {4, 12, 16}.

Possibly related PRs

  • NVIDIA/cccl#12223: This PR changes the group_as range interface and mapping behavior described by this documentation.

Suggested reviewers: pciolkosz

Priority: Low

Change: Other

Merge Risk: Low · up to 4e4e3

The documentation example needs a small correction before merging; no supported caller compatibility break was found.

- [ ] Autofix · Keep fixing CodeRabbit findings and required CI, and resolving merge conflicts

Comment @coderabbitai help to get the list of available commands.

@coderabbitai coderabbitai Bot left a comment

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

🧹 Nitpick comments: 1
docs/cudax/coop/group/mapping/group_as.rst: 1

58-58: Trivial · Maintainability & Code Quality · Quick win

suggestion: Initialize group_as with an explicit RangeView.

Use cuda::std::views::all_t<decltype((unit_counts))> as the template argument:

cudax::coop::group_as<cuda::std::views::all_t<decltype((unit_counts))>> m{unit_counts};

Keep the deduction guide in the synopsis. The repository guidance applies to this documentation path and prohibits deduction-guide initialization. The comparable APIs explicitly document their deduction behavior, but group_as has no such exception.


Review info
Run configuration
  • Source mode: Auto
  • Repository: NVIDIA/cccl
  • Branch: main
  • File: .coderabbit.yaml
  • Commit: 03c8d69
  • Layers: Repository YAML
  • Review profile: CHILL
  • Plan: Enterprise
  • Run ID: 46da92a8-1245-4c31-a02e-b751208d9af2
Commits

Reviewing files that changed from the base of the PR and between 03c8d69 and c558c86.

Files selected for processing: 1
  • docs/cudax/coop/group/mapping/group_as.rst

Included review availability: This review used your included allowance. Your plan provides up to 12 included reviews per hour; 11 remain after this review.

@davebayer
davebayer force-pushed the groups_group_as_docs branch from c558c86 to 4e4e31f Compare October 26, 2026 12:51
@davebayer
davebayer requested a review from a team as a code owner October 26, 2026 12:51

@coderabbitai coderabbitai Bot left a comment

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

🧹 Nitpick comments: 1
docs/cudax/coop/group/mapping/group_as.rst: 1

55-58: Trivial · Maintainability & Code Quality · Quick win

suggestion: Use explicit template arguments in the example.

The example relies on deduction guides for cuda::std::array and group_as. Use explicit template arguments so the example follows the repository requirement and remains clear across supported toolchains.

As per coding guidelines: do not rely on deduction guides for initialization.

Source: Coding guidelines


Review info
Run configuration
  • Source mode: Auto
  • Repository: NVIDIA/cccl
  • Branch: main
  • File: .coderabbit.yaml
  • Commit: 03c8d69
  • Layers: Repository YAML
  • Review profile: CHILL
  • Plan: Enterprise
  • Run ID: cb16bc05-dcf2-4f2e-8551-fa4b92692a2d
Commits

Reviewing files that changed from the base of the PR and between c558c86 and 4e4e31f.

Files selected for processing: 2
  • cudax/include/cuda/experimental/coop/__group/mapping/group_as.cuh
  • docs/cudax/coop/group/mapping/group_as.rst

Included review availability: This review used your included allowance. Your plan provides up to 12 included reviews per hour; 10 remain after this review.

@github-actions

Copy link
Copy Markdown
Contributor

🥳 CI Workflow Results

🟩 Finished in 2h 00m: Pass: 100%/73 | Total: 1d 03h | Max: 1h 14m | Hits: 32%/139368

See results here.


The ``unit_counts`` range contains one size per subgroup. Units are assigned in order of their rank in the previous mapping result: the first subgroup gets the first ``unit_counts[0]`` units, the second gets the next ``unit_counts[1]`` units, and so on. If the previous mapping result describes multiple groups, the same sizes are applied independently to each group, and the resulting subgroup ranks are ordered first by the previous group rank, then by the index in ``unit_counts``.

``RangeView`` must be a viewable sized range whose value type is convertible to ``cuda::std::uint32_t``. The stored view must support indexing and iteration through a const view. Counts must be nonnegative and representable as ``cuda::std::uint32_t``, and their sum and the resulting group count must also be representable in that type. All units in the same input group must agree on the sizes.

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

I might avoid listing the restrictions on the range in the documentation until you are very very certain what they are. It's easy for this to grow out of sync with the implementation.

const cuda::std::array unit_counts{4, 12, 16};

// Mapping that splits every group from the previous mapping result into 3 subgroups of 4, 12 and 16 units.
cudax::coop::group_as m{unit_counts};

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

The example should show how this is used later on with some other code. Otherwise the reader is left thinking "so what?", because it's not clear where this fits in elsewhere.

This branch has not been deployed

No deployments
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

Status: In Review

Development

Successfully merging this pull request may close these issues.

2 participants