DOCS: Document UCX backend initialization options (#2050)
## What? Documents the UCX plugin's initialization options and the generic mechanism for overriding backend init parameters. - `docs/BackendGuide.md`: new `#### UCX backend initialization options` under "Create transfer backends", where parameter passing is already described. Adds the option table for `ucx_error_handling_mode` (default `peer`, alternative `none`), then explains the lane-selection consequence and the tradeoff of each value. - `docs/python_api.md`: new `## Backend initialization parameters` section with the `get_plugin_params` -> override -> `create_backend` snippet, cross-linked to the backend guide. Documentation only. No functional change. ## Why? `ucx_error_handling_mode` is exposed through `getPluginParams`/`get_plugin_params` but was undocumented, and its effect is easy to misread as "error reporting only". It also affects UCP transport lane selection: NIXL sets `ep_params.err_mode` from this option, and UCP only selects lanes whose transport advertises peer failure support. A transport that does not advertise it is excluded from `peer` endpoints even when it is available and faster. ROCm IPC is the concrete case. `rocm_ipc` in UCX 1.22 reports `error handling: none`, so it is not selected for NIXL's default `peer` endpoints. This is a contributing factor to the transport-selection behavior reported in #2039, where large ROCm VRAM RMA falls back to `software emulation | tcp/bond0` instead of `rocm_ipc`. The docs deliberately do not present `none` as the fix. It restores lane eligibility but disables the peer failure detection NIXL relies on to move an endpoint to its failed state and report `NIXL_ERR_REMOTE_DISCONNECT`, so it trades remote failure visibility for transport availability. The guidance is to fix lane eligibility in the transport where remote failure reporting is needed. Related: #2039 <!-- This is an auto-generated comment: release notes by coderabbit.ai --> ## Summary by CodeRabbit * **Documentation** * Added guidance for configuring UCX backend initialization parameters through C++ and Python APIs. * Documented how to retrieve defaults, override settings, and create the backend. * Explained `ucx_error_handling_mode` options, including their effects on transport selection and remote failure reporting. * Added references to supported UCX configuration options and clarified behavior for peer and disabled error-handling modes. * Clarified how error-handling settings influence available transport lanes and failure notifications. <!-- end of auto-generated comment: release notes by coderabbit.ai --> Signed-off-by: Yaser Afshar <yaser.afshar@intel.com>
Y
Yaser Afshar committed
b8bbfdb62a22dc4d1aab61d2b8db8ead17730fb7
Parent: eb26be2
Committed by GitHub <noreply@github.com>
on 8/13/2026, 2:52:34 PM