cuda.core.pack_host_copy_args#

cuda.core.pack_host_copy_args(
dst: int | Buffer | BufferProtocol,
src: int | Buffer | BufferProtocol,
nbytes: int,
) → bytes#

Pack the arguments of HOST_COPY_FN into user_data bytes.

The result is a record of three native-width fields in this order: uintptr_t dst, uintptr_t src, size_t nbytes, with no padding. struct.pack("@PPN", dst, src, nbytes) builds the same record, and struct.unpack("@PPN", data) reads one back. A caller that keeps such a record in memory of its own can pass its address as an int user_data instead.

dst and src are not retained. The caller must keep both alive, and must not resize them (a bytearray, for example), until the copy has run.

Parameters:

  • dst (int | Buffer | collections.abc.Buffer) – The destination. Only an int is a host address. A buffer-protocol object must be contiguous and writable.

  • src (int | Buffer | collections.abc.Buffer) – The source. Only an int is a host address. A buffer-protocol object must be contiguous.

  • nbytes (int) – The number of bytes to copy. Zero packs a copy that does nothing.

Returns:

The packed record, to pass as user_data.

Return type:

bytes

Raises:

  • TypeError – If dst or src is not an int, a Buffer, or a buffer-protocol object, or is a bool, a NumPy integer scalar, or a ctypes scalar such as ctypes.c_void_p. A buffer-protocol object that cannot export a contiguous view, or a writable one for dst, raises its own error.

  • ValueError – If nbytes exceeds the size of dst or src, if a Buffer comes from a memory resource that is not host-accessible, if an address is null, or if the ranges overlap.

  • OverflowError – If nbytes or an int address is negative or does not fit in a native-width field.

  • RuntimeError – If dst or src is a closed Buffer.

Notes

This function makes no CUDA calls, so a Python host callback can call it, for example to fill a record that a later HOST_COPY_FN reads through an int user_data. It checks host accessibility only for a Buffer with a memory resource. For an int or a Buffer without one, the caller must ensure that the memory is host-accessible.

On this page