[FEA] Remove `rmm::mr::pinned_memory_resource` in favor of `rmm::mr::pinned_host_memory_resource`.

[bdice]

Refactoring pinned host memory resources in RMM

RMM started with a pinned_memory_resource in mr/host/. Later, a pinned_host_memory_resource was added in mr/ in #1392 / #618. The new pinned_host_memory_resource is designed around the CCCL MR concepts that we want to adopt throughout RMM (xref: #2011). I propose we adopt pinned_host_memory_resource and drop rmm::mr::pinned_memory_resource (which will also allow us to drop rmm::mr::host_memory_resource).

Below, we compare rmm::mr::pinned_memory_resource and rmm::mr::pinned_host_memory_resource and provide guidance for migrating to the newer API.

Summary

• pinned_memory_resource is a polymorphic RMM host MR deriving from rmm::mr::host_memory_resource and uses cudaMallocHost/cudaFreeHost.
• pinned_host_memory_resource is a stateless CCCL-style resource that exposes static allocate/deallocate functions and uses cudaHostAlloc/cudaFreeHost (default flags). It explicitly models cuda::mr::{memory_resource, device_memory_resource} concepts and declares both host/device accessibility properties.
• Both allocate pinned/page-locked host memory; there are subtle (but likely inconsequential) differences in API surface, inheritance/equality semantics, and backend API choice.

Detailed comparison

• API paradigm:

  • pinned_memory_resource (PMR): object-oriented, polymorphic base host_memory_resource with virtual do_allocate/do_deallocate. Integrates with existing RMM host MR design and any code expecting a host_memory_resource*.
  • pinned_host_memory_resource (PHMR): stateless, concept-based CCCL MR with static methods. No base-class polymorphism; equality is type-based (all instances equivalent).

• Inheritance and equality

  • PMR inherits host_memory_resource; equality is identity-based (two different instances are not equal) via host_memory_resource default.
  • PHMR is standalone; compares all instances equal (stateless type equality).

• Backend CUDA API: slightly better for PHMR

  • PMR: cudaMallocHost/cudaFreeHost.
  • PHMR: cudaHostAlloc(cudaHostAllocDefault)/cudaFreeHost.
  • Practical difference is negligible when using default flags; cudaHostAlloc supports flags if we later extend. PHMR design with cudaHostAlloc is more desirable because of its flexibility.

• Stream/async semantics: slightly better for PHMR

  • Both expose overloads that accept a stream but ignore it; pinned host alloc/free are synchronous. Names may be allocate_async/deallocate_async for interface compatibility but behavior is synchronous.
  • We will be refactoring everything in RMM towards new names for all these methods anyway as we progress on CCCL MR adoption ([FEA] Support memory resources from CCCL 3.1.0+ #2011).

• Accessibility properties: the same for both

  • PMR: device_accessible via get_property(pinned_memory_resource, cuda::mr::device_accessible) and host accessible via host_memory_resource.
  • PHMR: explicitly declares both device_accessible and host_accessible.

• Header locations

  • PMR: rmm/mr/host/pinned_memory_resource.hpp (host MR group).
  • PHMR: rmm/mr/pinned_host_memory_resource.hpp (general MR group).

Migration plan

I looked at usage of pinned_memory_resource across RAPIDS and I did not see significant usage of host_memory_resource polymorphism. That means we can do the following:

1. Update RMM docs, examples, benchmarks to use PHMR (eliminate internal usage of PMR)
2. Directly replace PMR with PHMR in downstream RAPIDS repositories
3. Deprecate PMR and host_memory_resource (25.12)
4. Remove PMR and host_memory_resource (26.02)
5. Simplify the structure of RMM MRs -- we no longer need to distinguish "host" and "device" MRs when everything adheres to the CCCL MR design. That means we can move all the headers to rmm/mr/* instead of rmm/mr/device/* (with a deprecation period)

[bdice]

See also:

• PHMR lacks Python bindings. [FEA] Python bindings for rmm::mr::pinned_host_memory_resource #1429
  • Especially [FEA] Python bindings for rmm::mr::pinned_host_memory_resource #1429 (comment)
  • We should probably make PHMR inherit from device_memory_resource. That was attempted with a new MR in Add cuda_host_memory_resource #1982 but this should just be the PHMR rather than having yet-another pinned resource.
• [FEA] Expose CUDA 13 async pools for managed and pinned memory #2054 -- we want to eventually use CCCL's implementations of a pinned memory resource, which may replace PHMR

[bdice]

We will need the following downstream PRs to transition RAPIDS to pinned_host_memory_resource so that we can deprecate pinned_memory_resource (as well as host_memory_resource and new_delete_resource). I will update this comment as the status changes.

• Use pinned_host_memory_resource instead of pinned_memory_resource. cugraph#5312
• Use pinned_host_memory_resource for device-accessible memory in renumbering.cu cugraph#5317
• Use pinned_host_memory_resource instead of pinned_memory_resource. cuml#7340
• Remove extraneous host_memory_resource include cudf#20284
• Use pinned_host_memory_resource instead of pinned_memory_resource. cuvs#1434
  • Follow-up after Derive pinned_host_memory_resource from device_memory_resource #2102 goes in: Replace custom cuda_pinned_resource with RMM's pinned_host_memory_resource cuvs#1466
• [MINOR] Remove rmm/host/pinned_memory_resource rapidsmpf#605