Memory Registration Methods

Methods on Communicator for registering buffers and windows for zero-copy and RMA operations. The returned handle classes are documented under Communicator Resources.

register_buffer

Communicator.register_buffer(buffer: Buffer | SupportsDLPack | SupportsCAI) → RegisteredBufferHandle

Registers a buffer with this communicator for zero-copy communication.

Registered buffers can enable performance optimizations in NCCL operations. Buffer size is automatically derived from buffer count and dtype. The returned RegisteredBufferHandle is tracked by the communicator and may be released explicitly via its close() method, or automatically when the communicator is destroyed or aborted.

Parameters:: buffer – Buffer to register (array, Buffer, or buffer-like object).
Returns:: RegisteredBufferHandle for the registered buffer.
Raises:: NcclInvalid – If the buffer is on the wrong device or the communicator is not initialized.

register_window

Communicator.register_window(buffer: Buffer | SupportsDLPack | SupportsCAI, flags: WindowFlag | None = None) → RegisteredWindowHandle

Collectively registers a local buffer into an NCCL window.

This is a collective call: every rank in the communicator must participate. Buffer size is automatically derived from buffer count and dtype.

If called within a group, the handle value may not be filled until ncclGroupEnd completes. For non-blocking communicators, the handle may remain 0 until get_async_error() reports success.

The returned RegisteredWindowHandle is tracked by the communicator and may be released explicitly via its close() method, or automatically when the communicator is destroyed or aborted.

Parameters:

buffer – Local buffer to register as a window.
flags – Window registration flags. Defaults to None (DEFAULT).

Returns:

RegisteredWindowHandle for the registered window. Its handle remains 0 while registration is pending, or when windows are unsupported on the platform.

Raises:

NcclInvalid – If the buffer is on the wrong device or the communicator is not initialized.

WindowFlag

class nccl.core.WindowFlag(value, names=<not given>, *values, module=None, qualname=None, type=None, start=1, boundary=None)

Bases: IntFlag

Window registration behavior flags for Communicator.register_window().

DEFAULT = 0: Default window registration.

COLL_SYMMETRIC = 1: Collective symmetric window registration.

STRICT_ORDERING = 2: Strict ordering for window operations.

GIN_ONLY = 4: Register the window for GIN access only (NCCL 2.32+).

CFT_COUNTED = 8: Register the window against counted CFT logical endpoints instead of the default non-counted ones (NCCL 2.32+).