diff --git a/CHANGELOG.md b/CHANGELOG.md index 2368c8d..8dc13ce 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -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 diff --git a/cuvis/cube_utils.py b/cuvis/cube_utils.py index 0203195..ccbdcc8 100644 --- a/cuvis/cube_utils.py +++ b/cuvis/cube_utils.py @@ -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 @@ -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( + " 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(" bytes: @@ -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 diff --git a/tests/test_cuda_image_data.py b/tests/test_cuda_image_data.py new file mode 100644 index 0000000..efc4947 --- /dev/null +++ b/tests/test_cuda_image_data.py @@ -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.` 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(" 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" + )