TheRock/rocm-libraries/projects/hipthreads/CONTRIBUTING.md

<head> </head>

Contributing to hipThreads

We welcome contributions to hipThreads. Please follow these details to help ensure your contributions will be successfully accepted.

Issue Discussion

Please use the GitHub Issues tab to notify us of issues.

• Use your best judgement for issue creation. If your issue is already listed, upvote the issue and comment or post to provide additional details, such as how you reproduced this issue.
• If you're not sure if your issue is the same, err on the side of caution and file your issue. You can add a comment to include the issue number (and link) for the similar issue. If we evaluate your issue as being the same as the existing issue, we'll close the duplicate.
• If your issue doesn't exist, use the issue template to file a new issue.
  • When filing an issue, be sure to provide as much information as possible, including the GPU architecture, ROCm version, and any build or run output, so we can collect information about your configuration. This helps reduce the time required to reproduce your issue.
  • Check your issue regularly, as we may require additional information to successfully reproduce the issue.
• You may also open an issue to ask questions to the maintainers about whether a proposed change meets the acceptance criteria, or to discuss an idea or feature request pertaining to the library.

Acceptance Criteria

hipThreads is a C++-style concurrency library for AMD GPUs. It implements std::thread-like primitives (hip::wthread, hip::mutex, hip::lock_guard, hip::condition_variable, ...) that run inside GPU kernels, so existing std::thread CPU code can be ported to the GPU with minimal changes. It is built on HIP and libhipcxx.

Code in hipThreads should keep the public interface compatible with the C++ Standard Library threading facilities wherever practical, so that familiar std::-style concurrency code ports to the GPU with minimal changes. New primitives should mirror their standard-library counterparts in naming and semantics.

Contributions should be in scope for hipThreads — that is, threading and concurrency primitives and their direct supporting code. Functionality that is not specific to threading/concurrency (general-purpose device utilities, containers, std::-style types, or parallel algorithms) is usually better suited to libhipcxx or rocThrust. If you're unsure whether a change fits, open an issue to discuss it before raising a pull request.

In order for a change to be accepted, it must build cleanly, pass the test suite, and undergo a code review.

The GitHub "Issues" tab may also be used to discuss ideas surrounding particular features or changes before raising pull requests.

Code Structure

The deliverable is a static library libhipthreads.a plus public headers under inc/hip/. Only src/hip/thread.cxx is compiled into the library, everything else is header-only.

• Public umbrella headers (extensionless, libc++ style) live directly in inc/hip/: thread, mutex, condition_variable, pseudo_mutex, pseudo_condition_variable, thread_config.
• Implementation headers live under inc/hip/__thread/, inc/hip/__mutex/, and inc/hip/__condition_variable/, with low-level helpers in inc/hip/__clib/ and inc/hip/__support/.
• The persistent scheduler kernel and host-side plumbing live in src/hip/thread.cxx.
• Tests live in test/ (a libc++-style lit suite plus standalone unit executables).
• Examples are standalone CMake projects under examples/, each laid out as a series of stepN-* directories showing an incremental CPU to GPU port. The examples are also used as integration tests.

See README.md for a deeper description of the architecture and build/test workflow, and the full documentation at https://rocm.docs.amd.com/projects/hipThreads/en/latest/.

Coding Style

C and C++ code should be formatted using clang-format. The repository ships a .clang-format (LLVM base, 4-space indent, 120 column limit, access modifiers indented). Please format the code you change before opening a pull request.

Prefer formatting only the lines you changed, rather than reformatting whole files (which creates noisy diffs and can reformat unrelated code). git clang-format makes this easy — it formats just the lines in your staged changes:

# Stage your changes first, then format only the changed lines:
git add <files>
git clang-format

# Or format the changed lines relative to a base branch (e.g. before pushing):
git clang-format develop

The reformatting is left unstaged so you can review it before committing. To format a specific file in full (for example, a brand-new file you are adding), use:

clang-format -style=file -i <path-to-source-file>

Documentation files (Markdown and reStructuredText) are not subject to a column limit. Instead, write one sentence per line, following the LLVM coding standards. This keeps diffs small and readable, since editing a sentence changes only its line rather than rewrapping a whole paragraph.

Branching and Release Model

hipThreads follows the branching and release model used across the ROCm libraries.

• develop is the integration branch. All pull requests target develop. It always reflects the latest accepted work and is the branch that is integrated against.
• Release branches are cut as release/rocm-X.Y at the ROCm code-freeze date, where X and Y are the ROCm release major and minor numbers. Once a release branch is cut it receives only bug fixes and release-critical changes (cherry-picked from develop), not new features.
• Releases are tagged rocm-X.Y.Z, following the tag convention used across rocm-libraries, where Z is the patch number.

Pull Request Guidelines

When opening a pull request, please follow these guidelines:

• Target the develop branch. Open your pull request against develop, our integration branch (see Branching and Release Model).
• Keep PRs small and focused. Smaller PRs are easier and faster to review, and tend to surface fewer bugs. It is perfectly fine, and encouraged, to break a larger feature into a series of smaller PRs, even if some of them do not add user-visible functionality on their own (for example, a PR that only restructures or prepares the code ahead of the change that builds on it).
• One concern per PR. Keep each PR scoped to a single feature or fix. If you spot an unrelated issue while working, open a separate PR (or issue) for it rather than bundling it in.
• Write a descriptive title and body. Explain what the change does and why, link any related issues, and call out anything reviewers should pay special attention to or any decisions you'd like feedback on.
• Review your own PR first. Read through the diff as if you were the reviewer before requesting review — this catches typos, leftover debugging code, and unintended changes.
• Say how you verified it. Note the tests you added or ran (and on which GPU architecture), so reviewers know the change has been exercised.
• Keep it green. Make sure the code builds cleanly and the test suite passes before requesting review, and respond to review feedback by pushing follow-up commits to the same branch.

Branch Naming

Name your topic branches users/<username>/<short-description>, for example users/jdoe/fix-detach-race. This namespaces work by author and keeps the branch list readable.

Deliverables

Tests and benchmarks

New changes should include test coverage. Tests live in the test/ directory; each test/*.cxx file is auto-discovered and compiled as a HIP executable, and the suite is also runnable through lit. Tests should cover the functionality added to the public API. If you modify existing behavior, update the affected tests to match.

Changes record

All noticeable changes are recorded in the CHANGELOG.md file. For every release we annotate the additions, fixes, changes, deprecations, and/or optimizations introduced in that release. When opening a PR, add the meaningful changes it introduces to the appropriate sections under the latest unreleased entry.

Process

After you create a PR, you can take a look at a diff of the changes you made using the PR's "Files" tab.

PRs must pass through the code review described in the Acceptance Criteria section before they can be merged.

During code reviews, another developer will take a look through your proposed change. If any modifications are requested (or further discussion about anything is needed), they may leave a comment. You can follow up and respond to the comment, and/or create comments of your own if you have questions or ideas. When a modification request has been completed, the conversation thread about it will be marked as resolved.

To update the code in your PR (e.g. in response to a code review discussion), you can simply push another commit to the branch used in your pull request.