Replace OwningResourceAdaptor with a BackRef mixin

[nirandaperera]

Replaces the OwningResourceAdaptor<Resource, BackRef> wrapper with a slim BackRefMixin<BackRef> that RmmResourceAdaptor inherits directly. OwningResourceAdaptor wrapped RmmResourceAdaptor only to carry a weak_ptr/shared_ptr<BackRef> pair and promote weak→strong on copy. Its allocate/deallocate/property forwarding was redundant since RmmResourceAdaptor already satisfies the CCCL resource concept.

Back-reference contract

BackRefMixin enforces a strict lifetime contract: a back-reference must be installed via set_backref() before an instance is copied. Copying an uninstalled (or installed-but-expired) instance throws std::bad_weak_ptr. This makes accidental lifetime mistakes loud instead of silently producing a copy that no longer keeps its owner alive.

To make the contract impossible to violate by mistake, RmmResourceAdaptor's primary-resource constructor is now private. Only BufferResource (a friend) can construct one, and it installs the back-reference before the adaptor becomes observable. External callers obtain an adaptor exclusively via BufferResource::device_mr_adaptor(), so every adaptor a caller can reach is guaranteed to be back-referenced and safely copyable.

Changes

C++

• New cpp/include/rapidsmpf/memory/back_ref_mixin.hpp: templated BackRefMixin<BackRef> with default-empty weak_/strong_, set_backref(), copy ctor/assignment that promote weak→strong (throwing std::bad_weak_ptr when uninstalled or expired), and owner-based operator==. The promote logic is inlined into the copy ctor/assignment (no helper).
• Deleted cpp/include/rapidsmpf/memory/owning_resource_adaptor.hpp.
• RmmResourceAdaptor now publicly inherits BackRefMixin<BufferResource>. Its primary-resource constructor is private; BufferResource is a friend and is the sole producer of new instances. operator== checks both shared state and back-reference identity.
• HostMemoryResource and PinnedMemoryResource do not inherit the mixin (deferred); they remain freely copyable. Their operator== is pool-identity based (pinned) / always-equal (stateless host).
• BufferResource's owning_mr_ is a plain RmmResourceAdaptor member (no std::optional). device_mr is threaded through the private constructor so owning_mr_ is initialized in the member-initializer list; BufferResource::create() installs the back-ref afterward via owning_mr_.set_backref(weak_from_this()) (device only).
• New BufferResource::device_mr_adaptor(): exposes the internal device RmmResourceAdaptor directly (e.g. to query get_main_record() / current_allocated()), so callers no longer construct an RmmResourceAdaptor externally.
• streaming::Context::from_options(...) first parameter changed from RmmResourceAdaptor mr to any_device_resource mr (a plain device MR), since external callers can no longer construct an RmmResourceAdaptor. The Context hands the device MR to its internal BufferResource, which wraps it for tracking.
• Call sites (tests + benchmarks) updated to pass a vanilla memory resource to BufferResource::create() / Context::from_options() and to read stats through device_mr_adaptor() instead of creating and wrapping an adaptor themselves.

Python bindings

• RmmResourceAdaptor (Cython) now extends DeviceMemoryResource instead of UpstreamResourceAdaptor. Its __init__ raises TypeError to mirror the C++ private-constructor policy; instances are produced internally via a new cdef _from_cpp(const cpp_RmmResourceAdaptor&) factory that copies a back-ref'd C++ adaptor. The get_upstream accessor is removed.
• New BufferResource.device_mr_adaptor() (cpdef): returns a back-ref'd RmmResourceAdaptor whose copies keep the BufferResource alive. This is the only way to obtain an adaptor from Python.
• streaming.core.context.Context.from_options(...) now expects mr: DeviceMemoryResource instead of RmmResourceAdaptor (wrapped internally), matching the C++ change.
• Statistics.memory_profiling docs/examples updated to obtain the adaptor via BufferResource(...).device_mr_adaptor().
• Tests/conftests updated: stop pre-wrapping device MRs in RmmResourceAdaptor; pass plain rmm.mr.* resources to BufferResource/Context.from_options and read stats via br.device_mr_adaptor().

Latent side effect

Statistics::create_memory_recorder calls cuda::mr::resource_cast<RmmResourceAdaptor>(&mr) on the resource passed in. Previously this cast failed for resources obtained from BufferResource::device_mr() (the contained type was OwningResourceAdaptor<…>), silently returning a no-op MemoryRecorder. After this PR the contained type is RmmResourceAdaptor, so the cast succeeds and memory profiling becomes active for BR-allocated memory. No tests were relying on the previous no-op behavior.

[madsbk]

Thanks @nirandaperera, I think this is a good idea. My main motivation for a generic wrapper like OwningResourceAdaptor was that we could potentially upstream it to RMM. I suspect other libraries built on top of RMM will need something similar now that we have the owning any_resource type. But a fully generic wrapper does not compose well with resource_cast, which is a real issue.

Before we go deeper into this PR, could you also implement, or at least sketch, the same pattern for host_mr and pinned_mr (#1070)? It would be useful to see the full picture before we settle on the final design.

[nirandaperera]

I already added the Pinned MR and Host MR changes in this PR. Is that what you asked @madsbk ? Or did you want to sketch the owning wrapper impl for them?

[madsbk]

Or did you want to sketch the owning wrapper impl for them?

Yes, but on second thought, I think the trade-off is already pretty clear. It really comes down to one thing:

• A templated wrapper like OwningResourceAdaptor is nice because it avoids modifying the existing resource types.
• A mixin is nice because it composes naturally with cuda::mr::resource_cast.

And I agree that the mixin approach is probably preferable overall.

[nirandaperera]

Or did you want to sketch the owning wrapper impl for them?

Yes, but on second thought, I think the trade-off is already pretty clear. It really comes down to one thing:

• A templated wrapper like OwningResourceAdaptor is nice because it avoids modifying the existing resource types.
• A mixin is nice because it composes naturally with cuda::mr::resource_cast.

And I agree that the mixin approach is probably preferable overall.

I agree. Even I didnt realize this resource_cast bug when I reviewed OwningResourceAdapter PR. Claude is nifty in that sense ;-) LOL

[wence-]

The core idea looks good, please apply some sanity to all of the docstrings and comments

[nirandaperera]

@madsbk @wence- I updated the PR with better docstrings

[madsbk]

Something like:

   /**
    * @brief Get the RMM pinned host memory resource.
    *
    * The returned reference does not by itself maintain the lifetime of this
    * BufferResource. See device_mr() for details.    
    *
    * @throws std::invalid_argument if no pinned memory resource is available.
    * @return Reference to the RMM resource used for pinned host allocations.
    */

[nirandaperera]

Same here

[jameslamb]

Seems like this PR is still under active development and discussion. Please @ me for a ci-codeowners approval once you're ready for that.

[wence-]

Please fix this description. How can an instance be bound to a specific owner and then the instance obtains via copy shared ownership of that owner?

How is the owner, who is the ownee?

[nirandaperera]

Ah my bad! semantics changed since I made it mandatory to set a backref before copying, So, uninstalled state is no longer valid.

[wence-]

Why do I care about equality at all?

[nirandaperera]

Two back_ref objects will be equal if their weak ptrs point to the same control block. We cant simply use this == addressof(other) here.

[wence-]

OK, but what do I need equality for? What goes wrong if (for example) we delete operator==

[nirandaperera]

I think for current usages, we dont need it, because rmm resource adapter defines its own equality operator. But I wanted to preserve the default equlity operator behavior.
Eg:

class Foo: BackRefMixin<int>{
int a; 
bool operator==(const Foo&) const = default;
}

I think for this to work, we need BackRefMixin to define an equality opertor.

[wence-]

Please also apply some work to fix the PR description.

[wence-]

Some minor documentation suggestions

[nirandaperera]

@jameslamb This is ready

[jameslamb]

Believe this no longer needs ci-codeowners / packaging-codeowners but approving for you anyway.

I skimmed the changes and don't see any issues, deferring to the much more thorough and better-informed reviews given by other reviewers.

[nirandaperera]

/merge