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_ptr: int)

Bases: ABC

Abstract base class for NCCL communicator-owned resources.

Resources are tied to a specific communicator. They can be released explicitly via close(), and are released automatically when the owning 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_ptr: int, 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_ptr: int, 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() with equal buffer sizes by default. 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 for NCCL operations, or 0 once deregistered.

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.

close() → None

Explicitly deallocates the resource.

Idempotent: safe to call multiple times.

CustomRedOp

class nccl.core.CustomRedOp(comm_ptr: int, 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_ptr: int, 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.

Wraps ncclDevComm_t and manages its lifecycle. Created by Communicator.create_dev_comm(). The device communicator is automatically destroyed when the parent communicator is destroyed or aborted.

property ptr: int

Raw pointer to the underlying ncclDevComm_t structure.

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

multimem_handle(team: NCCLTeam) → MultimemHandle

Returns the multimem handle requested for team.

The returned facade wraps this dev comm’s per-create output storage; each lookup creates a new facade over the same storage. It remains backed by the resource 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.

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).

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): 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): 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 handle, returned by resource_handles for each LLA2ARequirement. Pass it to device-side all-to-all sessions.