[STF] Use out parameter for partition mappers

[caugonnet]

Summary

• Change partition_fn_t / stf_get_executor_fn to write mapper results through an out parameter instead of returning pos4 by value.
• Update built-in places partitioners, localized array mapper calls, C STF tests, and places documentation to match the new contract.
• Keep this extraction independent of Python STF bindings and other stf_c_api branch work.

Test plan

• pre-commit run --files c/experimental/stf/include/cccl/c/experimental/stf/stf.h c/experimental/stf/src/stf.cu c/experimental/stf/test/test_places.cpp cudax/include/cuda/experimental/__places/data_place_interface.cuh cudax/include/cuda/experimental/__places/localized_array.cuh cudax/include/cuda/experimental/__places/partitions/blocked_partition.cuh cudax/include/cuda/experimental/__places/partitions/cyclic_shape.cuh cudax/include/cuda/experimental/__places/partitions/tiled_partition.cuh docs/cudax/places.rst
• git diff --check

[copy-pr-bot]

This pull request requires additional validation before any workflows can run on NVIDIA's runners.

Pull request vetters can view their responsibilities here.

Contributors can view more details about this message here.

[caugonnet]

/ok to test 5f33c27

[coderabbitai]

📝 Walkthrough

Summary by CodeRabbit

Release Notes

• Refactor

  • Updated partition and mapper function signatures in the places API.

• Documentation

  • Updated partitioning-policy interface documentation to reflect revised function signatures.

Walkthrough

Partitioner and executor function signatures are refactored from return-by-value to out-parameter convention. Type definitions are updated in CudaX and C wrapper headers, partition implementations are converted, call sites are adapted, test mappers are adjusted, and documentation is synchronized across the refactoring.

Changes

Partitioner ABI migration

Layer / File(s)	Summary
Interface contracts cudax/include/cuda/experimental/__places/data_place_interface.cuh, c/experimental/stf/include/cccl/c/experimental/stf/stf.h	partition_fn_t and stf_get_executor_fn are redefined from returning pos4/stf_pos4 by value to writing into pos4*/stf_pos4* output parameters, establishing the new out-parameter ABI.
Partition implementations cudax/include/cuda/experimental/__places/partitions/blocked_partition.cuh, cudax/include/cuda/experimental/__places/partitions/cyclic_shape.cuh, cudax/include/cuda/experimental/__places/partitions/tiled_partition.cuh	get_executor methods in blocked, cyclic, and tiled partitions are updated to accept a result pointer and return void, with corresponding test calls refactored to pass temporaries by address instead of capturing return values.
Function call sites cudax/include/cuda/experimental/__places/localized_array.cuh, c/experimental/stf/src/stf.cu	Mapper function invocations are switched to out-parameter style: mapper(&eplace_coords, ...) instead of assignment from return values, and the C wrapper's cpp_mapper cast is updated.
Test mapper c/experimental/stf/test/test_places.cpp	blocked_mapper_1d test fixture signature changes to void with stf_pos4* result parameter, and field assignments use pointer dereference (result->x/y/z/t) instead of struct return.
User documentation docs/cudax/places.rst	Documented get_executor method signature and description updated to reflect the out-parameter convention and clarify that coordinates are written to *result.

---

_{Comment @coderabbitai help to get the list of available commands and usage tips.}

[coderabbitai]

Caution

Some comments are outside the diff and can’t be posted inline due to platform limitations.

⚠️ Outside diff range comments (1)

cudax/include/cuda/experimental/__places/partitions/blocked_partition.cuh (1)

105-123: ⚠️ Potential issue | 🔴 Critical | ⚡ Quick win

critical: blocked_partition_custom::get_executor can divide by zero on Line 123 when the selected dimension extent is zero (part_size becomes 0). Add an early guard for grid_dims.x == 0/part_size == 0 before computing c / part_size.

🧹 Nitpick comments (2)

cudax/include/cuda/experimental/__places/localized_array.cuh (1)

362-364: ⚡ Quick win

suggestion: initialize eplace_coords before passing it to mapper (e.g., pos4 eplace_coords(0);) so partially-written mapper outputs cannot leak uninitialized coordinates into placement decisions.

cudax/include/cuda/experimental/__places/data_place_interface.cuh (1)

55-58: ⚡ Quick win

suggestion: Add explicit unstable API warning to the documentation comment. While the cuda::experimental namespace indicates experimental status, the coding guidelines require that "All CUDA Experimental APIs must be documented as unstable and subject to change without notice." Consider adding a Doxygen @warning or note tag.

 //! Function type for computing executor placement from data coordinates.
 //! Uses an out-pointer convention so the signature is trivially representable
 //! in FFI frameworks (ctypes, cffi, Rust) that cannot return C structs.
+//! `@warning` This API is experimental and subject to change without notice.
 using partition_fn_t = void (*)(pos4* result, pos4 data_coords, dim4 data_dims, dim4 grid_dims);

As per coding guidelines: "All CUDA Experimental APIs must be documented as unstable and subject to change without notice".

---

ℹ️ Review info

⚙️ Run configuration

Configuration used: Path: .coderabbit.yaml

Review profile: CHILL

Plan: Enterprise

Run ID: 59d940a9-5232-4609-8a45-9d12e8f769af

📥 Commits

Reviewing files that changed from the base of the PR and between c47f140 and 5f33c27.

📒 Files selected for processing (9)

• c/experimental/stf/include/cccl/c/experimental/stf/stf.h
• c/experimental/stf/src/stf.cu
• c/experimental/stf/test/test_places.cpp
• cudax/include/cuda/experimental/__places/data_place_interface.cuh
• cudax/include/cuda/experimental/__places/localized_array.cuh
• cudax/include/cuda/experimental/__places/partitions/blocked_partition.cuh
• cudax/include/cuda/experimental/__places/partitions/cyclic_shape.cuh
• cudax/include/cuda/experimental/__places/partitions/tiled_partition.cuh
• docs/cudax/places.rst

[github-actions]

😬 CI Workflow Results

🟥 Finished in 1h 31m: Pass: 98%/59 | Total: 1d 15h | Max: 1h 31m | Hits: 5%/318213

See results here.