Python API reference

Module vkgdr

Parts of vkgdr that are independent of the CUDA bindings used.

class vkgdr.OpenFlags(value)

Valid flags to pass to Vkgdr.

CURRENT_CONTEXT_BIT

Ignore the given device and use the current CUDA context instead.

FORCE_NON_COHERENT_BIT

Treat the memory as non-coherent even if it is coherent (for debugging only).

REQUIRE_COHERENT_BIT

Fail unless memory is guaranteed to be coherent.

exception vkgdr.VkgdrError

Exception raised on errors.

class vkgdr.Vkgdr(device: int, flags: int = 0)

Handle to the library.

Parameters:

  • device – CUDA device from which to allocate the memory (ignored if flags contains VKGDR_OPEN_CURRENT_CONTEXT_BIT)

  • flags – A bitwise combination of zero or more flags from OpenFlags.

Raises:

VkgdrError – if there was an error from the underlying C library

classmethod open_current_context(flags: int = 0) → _V

Construct an instance using the current CUDA context.

This is a shortcut to pass OpenFlags.CURRENT_CONTEXT_BIT in flags.

Parameters:

flags – A bitwise combination of zero or more flags from OpenFlags.

class vkgdr.RawMemory(owner: Vkgdr, size: int, flags: int = 0)

Low-level memory allocation.

This should generally not be used directly, as it requires the memory to be explicitly freed (otherwise it will leak). Use an API-specific wrapper like vkgdr.pycuda.Memory for safe garbage collection.

Parameters:

  • owner – A Vkgdr created with the same device as the current CUDA context.

  • size – Number of bytes to allocate

  • flags – Flags for future expansion; must be 0

Raises:

VkgdrError – if there was an error from the underlying C library

free() → None

Free the memory.

This must be called with the same CUDA context current as when the object was constructed. It is safe to call it multiple times.

property device_ptr: int

Retrieve the CUDA device pointer for a memory allocation.

property is_coherent: bool

Determine whether the memory allocation is coherent from the host’s point of view.

property non_coherent_atom_size: int

Get the alignment requirement for flush and invalidate operations.

If the memory is coherent, returns 1.

flush(offset: int, size: int) → None

Flush host writes so that they are visible to the device.

Warning

offset and size must be multiples of non_coherent_atom_size (except where offset + size corresponds to the end of the memory allocation). Failing to observe this has undefined behaviour.

Parameters:

  • offset – Offset in bytes to the first byte to flush.

  • size – Size in bytes of the region to flush.

invalidate(offset: int, size: int) → None

Invalidate host view of device memory so that previous device writes are visible to the host.

Warning

offset and size must be multiples of non_coherent_atom_size (except where offset + size corresponds to the end of the memory allocation). Failing to observe this has undefined behaviour.

Parameters:

  • offset – Offset in bytes to the first byte to invalidate.

  • size – Size in bytes of the region to invalidate.

Module vkgdr.pycuda

Integration of vkgdr with pycuda.

class vkgdr.pycuda.Memory(*args: Any, **kwargs: Any)

Bases: PointerHolderBase, RawMemory

Memory allocation that is automatically garbage collected.

For the garbage collection to work, the CUDA context must not be destroyed before the memory is freed (if necessary, with free()). This object keeps a reference to the context so you do not need to worry about it being garbage collected, but explicitly destroying it through the pycuda API is likely to lead to segmentation faults.

It can be passed as the gpudata kwarg to pycuda.gpuarray.GPUArray to wrap it into a GPUArray that can be used with pycuda.

Parameters:

  • owner – A Vkgdr created with the same device as the current CUDA context.

  • size – Number of bytes to allocate

  • flags – Flags for future expansion; must be 0

Raises:

VkgdrError – if there was an error from the underlying C library

free() → None

Free the memory.

It is safe to call it multiple times.

property device_ptr: int

Retrieve the CUDA device pointer for a memory allocation.

flush(offset: int, size: int) → None

Flush host writes so that they are visible to the device.

Warning

offset and size must be multiples of non_coherent_atom_size (except where offset + size corresponds to the end of the memory allocation). Failing to observe this has undefined behaviour.

Parameters:

  • offset – Offset in bytes to the first byte to flush.

  • size – Size in bytes of the region to flush.

invalidate(offset: int, size: int) → None

Invalidate host view of device memory so that previous device writes are visible to the host.

Warning

offset and size must be multiples of non_coherent_atom_size (except where offset + size corresponds to the end of the memory allocation). Failing to observe this has undefined behaviour.

Parameters:

  • offset – Offset in bytes to the first byte to invalidate.

  • size – Size in bytes of the region to invalidate.

property is_coherent: bool

Determine whether the memory allocation is coherent from the host’s point of view.

property non_coherent_atom_size: int

Get the alignment requirement for flush and invalidate operations.

If the memory is coherent, returns 1.