Skip to content
Merged
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
8 changes: 8 additions & 0 deletions CHANGELOG.md
Original file line number Diff line number Diff line change
Expand Up @@ -113,6 +113,14 @@ Pre-releases (`b*`, `rc*`) are not listed.
- `cuvis.AcquisitionContext.capture` - `to_internal=True` raised `TypeError` instead of queueing the measurement, because it passed a Python `0` where SWIG requires a null pointer.
- `cuvis.Calibration`, `cuvis.AcquisitionContext`, `cuvis.ProcessingContext`, `cuvis.SessionFile`, `cuvis.Measurement`, `cuvis.Viewer`, `cuvis.Worker`, `cuvis.CubeExporter`, `cuvis.EnviExporter`, `cuvis.TiffExporter`, `cuvis.ViewExporter` - `__del__` raised `TypeError` after a failed construction, because it freed a handle that was still `None`.
- `cuvis.Worker.get_next_result_async` - a timeout returned a `cuvis.Worker.WorkerResult` built from handles the SDK never filled in; it now raises `cuvis.cuvis_aux.SDKException`.
- `cuvis.CudaImageData.to_torch`, `cuvis.CudaImageData.__cuda_array_interface__` - raised `AttributeError` on every call, because `_view` used `cuvis_il.cuvis_cuda_view_ptr`, which no `cuvis-il` build exports.
The device pointer is now read from the `cuvis_cuda_mem_view_t` field directly, so no binding helper is involved and none can go missing.
- `cuvis.CudaImageData.make_ipc`, `cuvis.CudaImageData.export_payload` - raised `AttributeError`, because they used `cuvis_il.cuvis_cuda_descriptor_bytes`, which no `cuvis-il` build exports.
The descriptor is now serialized in Python to the same 184-byte layout `cuvis_ipc` parses.
- `cuvis.CudaImageData.__del__`, `cuvis.CudaImageData.to_torch` - device buffers were never released: both freed through `cuvis_cuda_mem_free(handle)`, but the C API declares `cuvis_cuda_mem_free(CUVIS_CUDA_MEM*)`, so every call raised `TypeError` out of the binding.
In `__del__` that surfaced only as an ignored exception, and in the DLPack capsule deleter not at all, so a long-running consumer exhausted the card. The handle is now boxed, and `cuvis_cuda_ipc_handle_free` is corrected the same way.
- `tests/test_cuda_image_data.py` - behavior tests for the device-buffer path, which nothing previously executed: a static check that `cube_utils` references no absent `cuvis_il` symbol, the descriptor's wire layout and its agreement with `cuvis_ipc`, the free calling convention, and, on a machine with a CUDA device, that the zero-copy tensor equals the host cube and that repeated read-and-drop cycles return their memory.
The static and layout checks need no device, which matters because CI has none and therefore never ran this code.

## [3.5.3.2] - 2026-08-19

Expand Down
80 changes: 73 additions & 7 deletions cuvis/cube_utils.py
Original file line number Diff line number Diff line change
Expand Up @@ -3,6 +3,7 @@
from ._cuvis_il import cuvis_il
import numpy as np
import operator
import struct
from .cuvis_aux import SDKException
from .cuvis_types import DataFormat
from . import cuda
Expand Down Expand Up @@ -422,6 +423,57 @@ def apply(self, other):
del _op, _reflected, _method


# Wire format of cuvis_cuda_ipc_descriptor_t, mirroring the offsets cuvis_ipc parses. Kept
# here rather than imported from cuvis_ipc, which is the consumer half and lives outside this
# package precisely so a consumer process need not be able to import cuvis.
_IPC_HEAD = struct.Struct(
"<iiiIQQQQ"
) # backend, device_ordinal, handle_type, blob_len, size, alloc_size, offset, exporter_pid
_IPC_BLOB_OFF = 48
_IPC_PTR_LEN_OFF = 112
_IPC_PTR_BLOB_OFF = 120
_IPC_BLOB_MAX = 64
_IPC_DESC_LEN = 184


def _descriptor_bytes(desc) -> bytes:
"""Serialise a cuvis_cuda_ipc_descriptor_t to its transportable form.

Done field by field rather than as one memcpy of the struct: SWIG exposes the scalars
directly and the two blobs only as `unsigned char *`, so there is no way to hand the whole
struct out as bytes from Python. The layout is fixed by the C header and asserted below.
"""

def blob(pointer, length):
"""`length` bytes out of an unsigned char array, padded to the fixed field width."""
if length > _IPC_BLOB_MAX:
raise ValueError("blob length {} exceeds {}".format(length, _IPC_BLOB_MAX))
taken = bytes(
cuvis_il.p_unsigned_char_getitem(pointer, i) for i in range(length)
)
return taken.ljust(_IPC_BLOB_MAX, bytes(1))

out = bytearray(_IPC_DESC_LEN)
_IPC_HEAD.pack_into(
out,
0,
int(desc.backend),
int(desc.device_ordinal),
int(desc.handle_type),
int(desc.blob_len),
int(desc.size),
int(desc.alloc_size),
int(desc.offset),
int(desc.exporter_pid),
)
out[_IPC_BLOB_OFF : _IPC_BLOB_OFF + _IPC_BLOB_MAX] = blob(desc.blob, desc.blob_len)
struct.pack_into("<I", out, _IPC_PTR_LEN_OFF, int(desc.ptr_blob_len))
out[_IPC_PTR_BLOB_OFF : _IPC_PTR_BLOB_OFF + _IPC_BLOB_MAX] = blob(
desc.ptr_blob, desc.ptr_blob_len
)
return bytes(out)


class CudaImageData(object):
"""Device-resident image data backed by a shareable CUDA buffer.

Expand Down Expand Up @@ -467,12 +519,26 @@ def __init__(self, cuda_buf):
# bytes of the transportable IPC descriptor, filled by make_ipc()
self.descriptor = None

@staticmethod
def _free(handle):
"""Release one CUVIS_CUDA_MEM.

cuvis_cuda_mem_free takes CUVIS_CUDA_MEM* (like cuvis_cuda_ipc_handle_free), not the
handle by value, so the handle has to be boxed. Passing it by value raises TypeError
out of the binding and the buffer is never returned to the SDK's pool.
"""
box = cuvis_il.new_p_int()
cuvis_il.p_int_assign(box, int(handle))
return cuvis_il.cuvis_cuda_mem_free(box)

def _view(self):
"""(device_ptr:int, size_bytes:int, device_ordinal:int)."""
v = cuvis_il.cuvis_cuda_mem_view_t()
if cuvis_il.status_ok != cuvis_il.cuvis_cuda_mem_get_view(self._handle, v):
raise SDKException()
return int(cuvis_il.cuvis_cuda_view_ptr(v)), int(v.size), int(v.device_ordinal)
# int() on the void* SWIG object yields the address directly; no binding helper
# is involved, so this cannot drift out of sync with one.
return int(v.device_ptr), int(v.size), int(v.device_ordinal)

@property
def __cuda_array_interface__(self):
Expand Down Expand Up @@ -519,9 +585,7 @@ def to_torch(self):
):
raise SDKException()
ref = cuvis_il.p_int_value(pref)
producer = make_cuda_dlpack(
ptr, size, dev, on_delete=lambda: cuvis_il.cuvis_cuda_mem_free(ref)
)
producer = make_cuda_dlpack(ptr, size, dev, on_delete=lambda: self._free(ref))
t = torch.from_dlpack(producer) # flat uint8
t = t.view(getattr(torch, self._TORCH_DTYPE[self._format]))
return t.reshape(self.height, self.width, self.channels)
Expand All @@ -548,7 +612,7 @@ def make_ipc(self, backend: int = 0):
self._ipc_handle, desc
):
raise SDKException()
self.descriptor = cuvis_il.cuvis_cuda_descriptor_bytes(desc)
self.descriptor = _descriptor_bytes(desc)
return self.descriptor

def export_payload(self, backend: int = 0) -> bytes:
Expand Down Expand Up @@ -576,7 +640,9 @@ def __del__(self):
# Not wrapped in try/except: a device buffer that fails to free is a VRAM leak,
# and swallowing it here would hide the leak as well as the reason for it.
if self._ipc_handle is not None:
cuvis_il.cuvis_cuda_ipc_handle_free(self._ipc_handle)
box = cuvis_il.new_p_int()
cuvis_il.p_int_assign(box, int(self._ipc_handle))
cuvis_il.cuvis_cuda_ipc_handle_free(box)
self._ipc_handle = None
cuvis_il.cuvis_cuda_mem_free(self._handle)
self._free(self._handle)
self._handle = None
219 changes: 219 additions & 0 deletions tests/test_cuda_image_data.py
Original file line number Diff line number Diff line change
@@ -0,0 +1,219 @@
"""Tests for the CudaImageData device-buffer path.

The device tests need two things: a CUDA device the SDK accepts, and an SDK actually
processing on it. Since 3.6.0 the latter is not the default -- a process whose `cuvis.init`
did not ask for it processes on the host, and then no cube is backed by device memory -- so
point CUVIS_SETTINGS at a directory whose `cuvis.settings` carries
`force_gpu_mode="cuda"` before running these::

python -c "import cuvis; cuvis.SdkSettings(force_gpu_mode='cuda').save('/tmp/cuvis-gpu')"
CUVIS_SETTINGS=/tmp/cuvis-gpu python -m pytest tests/test_cuda_image_data.py

They skip otherwise, which CI always is: it runs in the cuvis_pyil container on a GPU-less
runner. That is precisely how a release went out calling two cuvis_il functions that do not
exist, so the tests that matter most here are the ones needing no device at all.
"""

import ast
import struct
from pathlib import Path

import pytest

import cuvis
from cuvis import binding, cuda
from cuvis._cuvis_il import cuvis_il
from cuvis.cube_utils import _descriptor_bytes

# Two different denials: the loaded library may not export the CUDA functions at all (the
# CPU-only build CI runs against), and the device may not support them. The first makes even
# calling into the binding raise, so it gates separately from the device tests below.
_HAS_CUDA_EXPORTS = binding.available("cuvis_cuda_mem_free")
requires_cuda_exports = pytest.mark.skipif(
not _HAS_CUDA_EXPORTS, reason="loaded cuvis library exports no CUDA functions"
)
requires_device = pytest.mark.skipif(
not cuda.capabilities().same_process, reason="needs a CUDA device the SDK accepts"
)


def _binding_names(module_path):
"""Every `cuvis_il.<name>` this module reaches for, found without importing it."""
tree = ast.parse(Path(module_path).read_text(encoding="utf-8"))
return {
node.attr
for node in ast.walk(tree)
if isinstance(node, ast.Attribute)
and isinstance(node.value, ast.Name)
and node.value.id == "cuvis_il"
}


def test_every_binding_symbol_the_cuda_path_uses_exists():
"""Test cube_utils calls no cuvis_il function the installed binding lacks.

Nothing on a GPU-less runner ever executes the device path, so a missing symbol there
surfaces only as an AttributeError in a user's process. This catches it at any commit.
"""
used = _binding_names(cuvis.cube_utils.__file__)
missing = sorted(name for name in used if not hasattr(cuvis_il, name))
assert not missing, f"cube_utils references absent cuvis_il symbols: {missing}"


@requires_cuda_exports
def test_free_passes_the_handle_the_way_the_c_api_takes_it():
"""Test cuvis_cuda_mem_free is called with CUVIS_CUDA_MEM*, not the handle by value.

The C API declares `cuvis_cuda_mem_free(CUVIS_CUDA_MEM* i_mem)`, like
`cuvis_cuda_ipc_handle_free`. Passing the int raises TypeError out of the binding, and the
buffer is then never returned to the SDK's pool.
"""
with pytest.raises(TypeError):
cuvis_il.cuvis_cuda_mem_free(0) # the shape that silently leaked

box = cuvis_il.new_p_int()
cuvis_il.p_int_assign(box, 0)
cuvis_il.cuvis_cuda_mem_free(box) # freeing a null handle is a no-op, not an error


# --- the IPC descriptor, which needs no device to serialise -------------------------------
def test_descriptor_serialises_to_the_locked_wire_layout():
"""Test _descriptor_bytes emits the 184-byte layout cuvis_ipc parses, blobs included."""
desc = cuvis_il.cuvis_cuda_ipc_descriptor_t()
desc.backend = 2
desc.device_ordinal = 1
desc.handle_type = 3
desc.blob_len = 4
desc.size = 65880000
desc.alloc_size = 67108864
desc.offset = 128
desc.exporter_pid = 4321
desc.ptr_blob_len = 2
for index, value in enumerate((0xDE, 0xAD, 0xBE, 0xEF)):
cuvis_il.p_unsigned_char_setitem(desc.blob, index, value)
for index, value in enumerate((0x01, 0x02)):
cuvis_il.p_unsigned_char_setitem(desc.ptr_blob, index, value)

raw = _descriptor_bytes(desc)

assert len(raw) == 184
head = struct.unpack_from("<iiiIQQQQ", raw, 0)
assert head == (2, 1, 3, 4, 65880000, 67108864, 128, 4321)
assert raw[48:52] == bytes((0xDE, 0xAD, 0xBE, 0xEF))
assert struct.unpack_from("<I", raw, 112) == (2,)
assert raw[120:122] == bytes((0x01, 0x02))


def test_descriptor_rejects_an_over_long_blob():
"""Test a blob_len past the fixed field width fails loudly rather than truncating."""
desc = cuvis_il.cuvis_cuda_ipc_descriptor_t()
desc.blob_len = 65
with pytest.raises(ValueError, match="exceeds 64"):
_descriptor_bytes(desc)


def test_the_wire_layout_matches_the_consumer_half():
"""Test cuvis_ipc and cube_utils agree on the offsets; they are two copies of one layout."""
cuvis_ipc = pytest.importorskip("cuvis_ipc")
from cuvis import cube_utils

assert cube_utils._IPC_HEAD.format == cuvis_ipc._HEAD.format
assert cube_utils._IPC_BLOB_OFF == cuvis_ipc._BLOB_OFF
assert cube_utils._IPC_PTR_LEN_OFF == cuvis_ipc._PTR_LEN_OFF
assert cube_utils._IPC_PTR_BLOB_OFF == cuvis_ipc._PTR_BLOB_OFF
assert cube_utils._IPC_BLOB_MAX == cuvis_ipc._BLOB_MAX
assert cube_utils._IPC_DESC_LEN == cuvis_ipc._DESC_LEN


# --- the real device path ------------------------------------------------------------------
def _device_cube(pc, session):
"""A cube left in device memory, or a skip naming why the SDK did not produce one."""
try:
return pc.apply(session.get_measurement(0)).get_cube_cuda()
except cuvis.cuvis_aux.SDKException as exc:
pytest.skip(
"SDK is not processing on the device ({}); set CUVIS_SETTINGS to a directory "
"whose cuvis.settings has force_gpu_mode=cuda".format(exc)
)


@pytest.fixture
def raw_context(test_session_file):
"""A Raw ProcessingContext shared with the session, as the reader path uses it."""
pc = cuvis.ProcessingContext(test_session_file)
test_session_file._pc = pc
pc.processing_mode = cuvis.ProcessingMode.Raw
return pc


@pytest.fixture
def device_cube(test_session_file, raw_context):
"""A processed cube left in device memory, plus the same cube fetched to the host."""
import numpy as np

host = np.ascontiguousarray(
raw_context.apply(test_session_file.get_measurement(0)).cube.array
)
cuda.enable() # one way for this process, so it happens after the host reference
try:
yield _device_cube(raw_context, test_session_file), host
finally:
cuda.disable()


@requires_device
def test_view_describes_the_device_buffer(device_cube):
"""Test _view() returns a usable pointer and the cube's exact byte count."""
cimg, host = device_cube
ptr, size, ordinal = cimg._view()
assert ptr > 0
assert size == host.nbytes
assert ordinal >= 0


@requires_device
def test_to_torch_is_the_same_cube_on_the_device(device_cube):
"""Test the zero-copy tensor holds exactly what the host path would have produced."""
torch = pytest.importorskip("torch")
cimg, host = device_cube
tensor = cimg.to_torch()
assert tensor.is_cuda
assert tuple(tensor.shape) == host.shape
assert torch.equal(tensor.cpu(), torch.from_numpy(host))


@requires_device
def test_cuda_array_interface_reports_the_buffer(device_cube):
"""Test the fallback interop path answers instead of raising from the binding."""
cimg, host = device_cube
with pytest.warns(UserWarning, match="lifecycle"):
interface = cimg.__cuda_array_interface__
assert interface["shape"] == host.shape
assert interface["data"][0] > 0


@requires_device
def test_device_buffers_are_returned_to_the_sdk(test_session_file, raw_context):
"""Test repeated read-and-drop cycles do not accumulate device memory.

A free that raises leaves every cube's buffer outstanding, which is invisible until a
long run exhausts the card. The SDK pools the buffers, so this asserts a plateau rather
than a return to the starting value.
"""
torch = pytest.importorskip("torch")
cuda.enable()
try:
_device_cube(raw_context, test_session_file).to_torch()
torch.cuda.synchronize()
settled = torch.cuda.mem_get_info()[0]
for _ in range(20):
held = _device_cube(raw_context, test_session_file).to_torch()
del held
torch.cuda.synchronize()
free_now = torch.cuda.mem_get_info()[0]
finally:
cuda.disable()
lost_mib = (settled - free_now) / 2**20
assert lost_mib < 256, (
f"{lost_mib:.0f} MiB of device memory not returned over 20 cycles"
)