Communicator Resources

Resources owned by a Communicator. The CommResource subclasses below are tracked by their owning communicator and released either explicitly via close() or automatically when the communicator is destroyed or aborted.

CommResource

Abstract base class of communicator-owned resources; it defines their close() and is_valid contract.

class nccl.core.resources.CommResource(comm: nccl.bindings.nccl.Comm)

Bases: ABC

Abstract base class for NCCL communicator-owned resources.

Resources are tied to a specific communicator. They can be released explicitly via close(). Resources created through a communicator are also released when that communicator is destroyed or aborted.

close() → None

Explicitly deallocates the resource.

Idempotent: safe to call multiple times.

property is_valid: bool: Whether the resource has been initialized and is still valid (not closed).

RegisteredBufferHandle

class nccl.core.RegisteredBufferHandle(comm: nccl.bindings.nccl.Comm, buffer_ptr: int, size: int)

Bases: CommResource

NCCL registered buffer handle for zero-copy optimized communication.

Registers a user buffer with the communicator to enable performance optimizations in NCCL operations. Created by Communicator.register_buffer(). The registration handle can be released explicitly via close(), or automatically when the owning communicator is destroyed or aborted.

property handle: int

Registration handle for NCCL operations.

Raises:: RuntimeError – If the buffer has been deregistered or the handle is invalid.

property size: int: Size of the registered buffer in bytes.

close() → None

Explicitly deallocates the resource.

Idempotent: safe to call multiple times.

property is_valid: bool: Whether the resource has been initialized and is still valid (not closed).

RegisteredWindowHandle

class nccl.core.RegisteredWindowHandle(comm: nccl.bindings.nccl.Comm, buffer_ptr: int, size: int, flags: WindowFlag | None = None)

Bases: CommResource

NCCL registered window handle for Remote Memory Access (RMA) operations.

Registers a memory window with the communicator for one-sided communication patterns. Created by Communicator.register_window(). Registration is collective: all ranks must call Communicator.register_window(). Deregistration is local. The window handle can be released explicitly via close(), or automatically when the owning communicator is destroyed or aborted.

property is_valid: bool: Whether the window is still registered (not closed, handle non-null).

property handle: int: Window handle value, or 0 while unavailable or after deregistration.

property size: int: Size of the registered window in bytes.

property user_ptr: int

Original user buffer pointer registered with this window.

Raises:: RuntimeError – If the window has been deregistered.

get_lsa_multimem_device_pointer(offset: int = 0) → int | None

Returns the LSA multicast device pointer for this window.

Returns a device pointer suitable for multicast operations over the LSA (Load/Store Accessible) team. The pointer is valid as long as the window and communicator remain alive.

Parameters:: offset – Byte offset within the window buffer. Defaults to 0.
Returns:: Device pointer as int, or None if multimem is not supported.
Raises:: RuntimeError – If the window has been closed.

get_multimem_device_pointer(multimem: MultimemHandle, offset: int = 0) → int | None

Returns the multicast device pointer for this window and multimem.

Unlike get_lsa_multimem_device_pointer() (which uses the LSA team’s multimem), this resolves the pointer for an explicit multimem handle produced during device communicator creation.

Parameters:

multimem – A MultimemHandle returned by DevCommResource.multimem_handle().
offset – Byte offset within the window buffer. Defaults to 0.

Returns:

Device pointer as int, or None if multimem is not supported.

Raises:

RuntimeError – If the window has been closed.

get_lsa_device_pointer(lsa_rank: int, offset: int = 0) → int

Returns the LSA device pointer for a peer within the LSA team.

Returns a device pointer to the peer’s window buffer addressable from the local GPU via LSA (Load/Store Accessible) mapping.

Parameters:

lsa_rank – Rank within the LSA team (0 to lsa_size - 1).
offset – Byte offset within the window buffer. Defaults to 0.

Returns:

Device pointer as int.

Raises:

RuntimeError – If the window has been closed.

get_peer_device_pointer(peer: int, offset: int = 0) → int | None

Returns a device pointer to a peer’s window buffer by world rank.

If the peer is not reachable via LSA, returns None.

Parameters:

peer – World rank of the peer (0 to nranks - 1).
offset – Byte offset within the window buffer. Defaults to 0.

Returns:

Device pointer as int, or None if the peer is not reachable via LSA.

Raises:

RuntimeError – If the window has been closed.

get_multimem_le_info(offset: int = 0) → CftLeInfo

Returns the multicast logical endpoint address for this window and offset.

Parameters:: offset – Byte offset within the window buffer. Defaults to 0.
Returns:: The logical endpoint address, as a CftLeInfo.
Raises:: RuntimeError – If the window has been closed.

CftLeInfo

Returned by the RegisteredWindowHandle logical-endpoint queries. CFT operations address memory by this pair rather than by pointer.

class nccl.core.CftLeInfo(le_id: int, le_offset: int)

Bases: object

CFT logical endpoint address returned by window LE-info queries.

le_id: int: Logical endpoint identifier.

le_offset: int: Byte offset within the logical endpoint.

CustomRedOp

class nccl.core.CustomRedOp(comm: nccl.bindings.nccl.Comm, scalar_ptr: int, datatype: NcclDataType, residence: nccl.bindings.nccl.ScalarResidence)

Bases: CommResource

NCCL user-defined custom reduction operator.

Created by Communicator.create_pre_mul_sum(). The PreMulSum operator performs output = scalar * sum(inputs), useful for averaging or weighted reductions. The operator can be released explicitly via close(), or automatically when the owning communicator is destroyed or aborted.

property op: int

Operator handle for use in reduction operations.

Raises:: RuntimeError – If the operator has been destroyed or is invalid.

close() → None

Explicitly deallocates the resource.

Idempotent: safe to call multiple times.

property is_valid: bool: Whether the resource has been initialized and is still valid (not closed).

DevCommResource

class nccl.core.DevCommResource(comm: _nccl_bindings.Comm, reqs_lowpp: _nccl_bindings.DevCommRequirements, team_multimem_lowpp: dict[NCCLTeam, _nccl_bindings.MultimemHandle] | None = None, resource_handle_lowpps: tuple[_nccl_bindings.LsaBarrierHandle | _nccl_bindings.GinBarrierHandle | _nccl_bindings.LLA2AHandle, ...] | None = None)

Bases: CommResource

NCCL device communicator resource for device-side operations.

Owns and manages an ncclDevComm_t created by Communicator.create_dev_comm(). The device communicator is automatically destroyed when the parent communicator is destroyed or aborted.

close() → None

Explicitly deallocates the resource.

Idempotent: safe to call multiple times.

property is_valid: bool: Whether the resource has been initialized and is still valid (not closed).

property ptr: int

Address of the underlying ncclDevComm_t object, represented as a Python integer.

Raises:: RuntimeError – If the device communicator has been destroyed.

multimem_handle(team: NCCLTeam) → MultimemHandle

Returns the multimem handle requested for team.

The returned handle references storage owned by this resource and remains valid until the device communicator is closed.

Parameters:

team – The team the handle was requested for, as an entry of the teams requirement used to create this device communicator.

Returns:

The MultimemHandle NCCL filled in for team.

Raises:

RuntimeError – If the device communicator has been closed.
KeyError – If team was not requested with multimem=True in the requirements used to create this device communicator.

property resource_handles: tuple[LsaBarrierHandle | GinBarrierHandle | LLA2AHandle, ...]

Finalized resource handles, in the order of resources.

resource_handles[i] corresponds to requirements.resources[i] and is an LsaBarrierHandle, GinBarrierHandle, or LLA2AHandle depending on the requirement. Each remains backed by this resource until the device communicator is closed.

Device resource handles

Handles returned by DevCommResource.resource_handles and DevCommResource.multimem_handle(). These are views backed by their owning DevCommResource, not independently closable resources. They remain valid only while that resource remains open. Pass one to the device-side APIs.

MultimemHandle

class nccl.core.MultimemHandle(*args: Any, **kwargs: Any): Multimem handle, returned by multimem_handle() for a team requested with multimem=True. Pass it to device-side multimem operations.

LsaBarrierHandle

class nccl.core.LsaBarrierHandle(*args: Any, **kwargs: Any): Load/Store Accessible (LSA) barrier handle, returned by resource_handles for each LsaBarrierRequirement. Pass it to device-side barrier sessions.

GinBarrierHandle

class nccl.core.GinBarrierHandle(*args: Any, **kwargs: Any): GPU-Initiated Networking (GIN) barrier handle, returned by resource_handles for each GinBarrierRequirement. Pass it to device-side barrier sessions.

LLA2AHandle

class nccl.core.LLA2AHandle(*args: Any, **kwargs: Any): Low-latency all-to-all (LLA2A) handle, returned by resource_handles for each LLA2ARequirement. Pass it to device-side all-to-all sessions.