Add a strict Buffer Resource back-reference to Host and Pinned memory resources

[nirandaperera]

HostMemoryResource and PinnedMemoryResource are now BufferResource-only resources that carry a strict BackRefMixin<BufferResource> back-reference. When a copy of one of these resources is made (e.g. when CCCL promotes host_mr() / pinned_mr() into an owning cuda::mr::any_resource inside a HostBuffer), the copy promotes the stored weak_ptr to a shared_ptr, keeping the owning BufferResource alive for as long as any derived buffer lives. This closes a lifetime gap where a Buffer could outlive the BufferResource that produced its memory resource.

The mixin is strict: copying an instance without an installed back-reference throws std::bad_weak_ptr. To make that safe, these resources can no longer be constructed as standalone objects — they are created only by BufferResource, which installs the back-reference immediately after construction. This mirrors how RmmResourceAdaptor already works on this branch.

C++ changes

• HostMemoryResource: inherits BackRefMixin<BufferResource>; constructor is private with friend class BufferResource. Equality remains stateless (always true) since instances are interchangeable and the back-reference is installed exactly once.
• PinnedMemoryResource: inherits BackRefMixin<BufferResource> as a second base; constructor is private (friend class BufferResource). The make_if_available / from_options factories were removed so no back-reference-less instance can ever escape. Equality compares the shared pool state only.
• PinnedPoolProperties: gained a numa_id field (defaults to the calling thread's NUMA node) so all pinned configuration flows as one struct. Added a free helper pinned_pool_properties_from_options(...).
• PinnedMemoryDisabled: new constexpr std::nullopt_t sentinel used to disable pinned host memory (replaces the old PinnedMemoryResource::Disabled).
• BufferResource::create() / from_options(): now take std::optional<PinnedPoolProperties> pinned_pool_properties (default PinnedMemoryDisabled) instead of a pre-built resource. The pinned resource is constructed internally and the back-reference is installed on owning_mr_, host_mr_, and pinned_mr_ before create() returns.
• try_pinned_mr(): now returns std::optional<PinnedMemoryResource> (a back-referenced handle) so Python/Statistics get a concrete, lifetime-safe handle.

Python changes

• PinnedMemoryResource: now an opaque, non-constructible handle (__init__ raises TypeError); obtained via BufferResource.pinned_mr.
• PinnedPoolProperties: new @dataclass (initial_pool_size, max_pool_size, numa_id) used to configure pinned memory.
• BufferResource(...): replaces the old pinned_mr= argument with pinned_pool_properties: PinnedPoolProperties | None = None (None disables pinned host memory). from_options derives this from the config options.
• Statistics.report(pinned_mr=...): unchanged signature; the handle is now sourced from BufferResource.pinned_mr.

Tests

• Added HostMrKeepsBufferResourceAlive and PinnedMrKeepsBufferResourceAlive regression tests mirroring DeviceMrKeepsBufferResourceAlive.
• Routed all C++ tests/benchmarks through a BufferResource (no standalone Host/Pinned MR construction); reworked test_host_buffer, test_config, test_memory_resources, and bench_memory_resources.
• Updated Python test_config.py to configure pinned memory via BufferResource and assert on BufferResource.pinned_mr.

Breaking changes

• C++: HostMemoryResource / PinnedMemoryResource can no longer be constructed directly; PinnedMemoryResource::make_if_available / from_options and the Disabled sentinel are removed. BufferResource::create() takes PinnedPoolProperties instead of a PinnedMemoryResource.
• Python: PinnedMemoryResource(...) is no longer constructible; the BufferResource(pinned_mr=...) argument is replaced by pinned_pool_properties=.

Depends on #1078

Closes #1070

[copy-pr-bot]

Auto-sync is disabled for draft pull requests in this repository. Workflows must be run manually.

Contributors can view more details about this message here.