SIGN IN SIGN UP

BINDINGS/PYTHON: Expose prepMemView (local + remote overloads) and re… (#1715)

# PYTHON: Expose `prepMemView` and `releaseMemView`

## Why

Downstream kernels need to drive `nixlAgent::prepMemView`
from Python to obtain the `nixlMemViewH` handles that the device-side
`nixlPut<WARP>` API in `examples/device/ep` expects. Today the C++ API
exists but the Python bindings only expose `prepXferDlist` (which
returns a `nixlDlistH`, not a memory-view handle), forcing every Python
caller to drop into C++ to set up a device-initiated transfer.

This PR adds the minimum needed to drive a
`prepMemView` based flow from Python, and leaves the existing.


## What

1. **`nixlAgent.prepMemView` - two pybind11 overloads under one Python
   name**. pybind11 dispatches by argument shape since the two C++
   overloads of `nixlAgent::prepMemView` have disjoint signatures:
   - `prepMemView(dlist: nixlXferDList, backends=[]) -> int` -
     wraps `nixlAgent::prepMemView(const nixl_local_dlist_t&, ...)`.
   - `prepMemView(mem_type, descs, backends=[]) -> int` -
     wraps the remote-dlist overload; `descs` is a list of 4-tuples
     `(addr, len, dev_id, remote_agent_name)`.

   Both overloads return the `nixlMemViewH` as a `uintptr_t` Python
   `int` so the handle can be passed straight into any kernel pybind
   shim that takes `uintptr_t` for the memory-view argument.

2. **`nixlAgent.releaseMemView(mvh: int)`** - thin wrapper around
   `nixlAgent::releaseMemView`. Caller is responsible for pairing it
   with the `int` returned from `prepMemView`.

3. **`_api.py` thin wrappers** on the user-facing `nixl_agent` class:
   - `prepMemView(*args, backends=[]) -> int` - variadic forwarder
     that translates the `backends` string-name list into the handle
     vector the underlying binding expects, then delegates to
     `self.agent.prepMemView(*args, handle_list)`. Same calling shapes
     as the bindings.
   - `releaseMemView(mvh: int)` - direct forwarder.

   No `__del__`-based handle wrapper class is introduced.


--- 
Built & verified on aarch64 GB200 



<!-- This is an auto-generated comment: release notes by coderabbit.ai
-->
## Summary by CodeRabbit

* **New Features**
* Memory-view lifecycle: prepare memory views from either local
descriptors or remote descriptions, select target backends, receive
opaque numeric view handles, and release handles to free resources.
* **Tests**
* Added automated test validating local and remote memory-view
preparation, non-zero handle returns, and proper handle release.
<!-- end of auto-generated comment: release notes by coderabbit.ai -->

---------

Co-authored-by: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
Co-authored-by: Raul Akhmetshin <74596089+rakhmets@users.noreply.github.com>
X
x41lakazam committed
9824e1cb9ee8349510d2123d40fd250214fd7d1a
Parent: a3ad19e
Committed by GitHub <noreply@github.com> on 8/17/2026, 12:46:15 PM