diff --git a/examples/camera_livekit_bridge/README.md b/examples/camera_livekit_bridge/README.md index 6540688247..b924d69a4f 100644 --- a/examples/camera_livekit_bridge/README.md +++ b/examples/camera_livekit_bridge/README.md @@ -22,8 +22,8 @@ sequence is the track's `frame_id`, the sensor start time (when the receiver derived one) is the `user_timestamp` in Unix microseconds, and the sensor counter is the 8-byte `user_data`. The newest picture is encoded and older queued ones are skipped. The receiver overwrites a slot without notice once its ring wraps, so after the GPU copy the -bridge checks for a newer notice for the same slot, or as many newer notices as the ring has other slots, and drops the -picture instead of encoding it (counted as `slot overruns`). The session also answers clock-sync requests that +bridge checks the slot's shared write-generation marker and drops the picture instead of encoding it when the receiver +began a write meanwhile (counted as `slot overruns`). The session also answers clock-sync requests that arrive as LiveKit data messages. ## Integration boundary @@ -33,8 +33,8 @@ wiring (`livekit_publisher/` and the session handling in `bridge/`) is temporary behind transport adapters: a layer that carries camera video and application messages over a selectable network transport and owns sessions, admission limits and feedback. Camera buffer ownership and encode and decode responsibilities belong to the camera interface. A replacement must preserve browser delivery, bounded latency and -safe GPU access. Until receiver slots have read leases, the residual risk described under "Reading the receiver's -slots" applies. +safe GPU access. Until the receiver excludes overlapping slot access instead of letting the bridge detect it, the +residual described under "Reading the receiver's slots" applies. | Current path | Intended owner or replacement | Reuse, adapt or retire | Follow-up and landing condition | | --- | --- | --- | --- | @@ -113,15 +113,24 @@ build/probe/camera_ipc_probe --socket /tmp/camera_receiver_avs1_cuda_ipc.sock \ It prints each stream's plane layout, then per frame the slot, generation, stream sequence, session id, sensor start time and a checksum of the first -pixels. Slots are overwritten without notice when the publisher's ring wraps. +pixels. Slots are overwritten without notice when the publisher's ring wraps; the probe does not validate the pixels it +checksums. ## Reading the receiver's slots The receiver rewrites its GPU ring slots in rotation and never waits for a reader: a slot is overwritten without -notice about `ring_depth` frames after it was announced, and the only signal is a later frame notice. A consumer -therefore has to finish with a slot within that window or skip ahead. The bridge follows this: it uses only the -newest notice, starts the GPU copy at once on its own stream, waits for it to complete, and drops (never encodes) -the picture when later notices show the ring may have wrapped; those frames count as slot overruns in the `[stats]` -line. The notices arrive asynchronously, so this check cannot prove a copy was clean: a stall of most of the ring's -window between the notice and the end of the copy can still publish a picture that mixes two frames under the earlier -frame's metadata. Only a read guard in the receiver, which skips slots a reader holds, would remove that case. +notice about `ring_depth` frames after it was announced, and the replacement notice only arrives after the new write. +It therefore advances a shared write-generation marker for the slot before it touches the pixels and announces that +generation in the frame notice once the write is complete. The bridge maps the markers through the same native helper +the receiver uses (`camera_streamer/ipc_protocol`), uses only the newest notice, starts the GPU copy into the encoder +input surface at once on its own stream, waits for it to complete, and then loads the marker. It encodes the picture +only if the marker still equals the notified generation; otherwise it drops it, prints a prominent error (at most every +5 s per stream) and counts a slot overrun in the `[stats]` line. The same check before the copy only saves work. A +publisher that does not provide write generations is refused at connect time. + +This is interim protection, not a documented guarantee. CUDA's memory model makes a read that races a write undefined +behavior, and the check relies on the race only changing the bridge's private copy, which it discards. It makes every +detected overlap visible and narrows the window, but a picture that passed it is very likely intact rather than proven +intact. The proper fix is for the receiver to exclude overlapping access (short reader reservations it honours), planned +as follow-up work that would replace this check. See `camera_streamer/ipc_protocol/README.md` for the ordering +contract. diff --git a/examples/camera_livekit_bridge/bridge/main.cpp b/examples/camera_livekit_bridge/bridge/main.cpp index 9c7360373b..cd854b1810 100644 --- a/examples/camera_livekit_bridge/bridge/main.cpp +++ b/examples/camera_livekit_bridge/bridge/main.cpp @@ -33,7 +33,7 @@ void usage() { std::cerr << "usage: camera_livekit_bridge --livekit-url URL --livekit-token-file FILE --stream NAME=TRACK[:DIV] [--stream ...]\n" - " [--socket PATH] [--fps N] [--bitrate-mbps N] [--idr-period N] [--max-notice-age-ms N] [--gpu N] [--source-full-range]\n [--timestamp-basis monotonic_us|capture_monotonic_us|capture_unix_us]\n" + " [--socket PATH] [--fps N] [--bitrate-mbps N] [--idr-period N] [--gpu N] [--source-full-range]\n [--timestamp-basis monotonic_us|capture_monotonic_us|capture_unix_us]\n" " NAME is a stream in camera_receiver's IPC catalog; TRACK is the LiveKit track name egocap expects;\n DIV shrinks the picture on the GPU by that integer factor before encoding.\n"; } @@ -91,8 +91,6 @@ int main(int argc, char** argv) defaults.bitrate_bps = static_cast(std::atof(next().c_str()) * 1e6); else if (arg == "--source-full-range") defaults.source_full_range = true; - else if (arg == "--max-notice-age-ms") - defaults.max_notice_age_ms = static_cast(std::atoi(next().c_str())); else if (arg == "--idr-period") defaults.idr_period = static_cast(std::atoi(next().c_str())); else if (arg == "--timestamp-basis") @@ -200,12 +198,9 @@ int main(int argc, char** argv) std::cerr << "[stats] " << workers[i]->config().track << ": " << (frames - last_frames[i]) / seconds << " fps, " << frames << " frames, " << stats.keyframes.load() << " keyframes, " << stats.skipped.load() << " skipped, " << stats.rejected.load() << " rejected, " - << stats.slot_overruns.load() << " slot overruns, " << stats.stale_slot_reads.load() - << " stale slot reads, encode " << mean_ms << " ms mean, bitrate " - << stats.bitrate_bps.load() / 1000 << " kbps (transport target " + << stats.slot_overruns.load() << " slot overruns, encode " << mean_ms + << " ms mean, bitrate " << stats.bitrate_bps.load() / 1000 << " kbps (transport target " << stats.target_bps.load() / 1000 << " kbps, " << stats.rate_changes.load() << " changes)"; - if (const uint64_t unchecked = stats.unchecked_slot_reads.load(); unchecked > 0) - std::cerr << ", " << unchecked << " slot reads without a notice time to check"; const uint64_t ready_samples = stats.capture_to_ready_samples.load(); if (ready_samples > 0) { diff --git a/examples/camera_livekit_bridge/bridge/stream_worker.cpp b/examples/camera_livekit_bridge/bridge/stream_worker.cpp index 77f5cb8f58..f8e5d3ee97 100644 --- a/examples/camera_livekit_bridge/bridge/stream_worker.cpp +++ b/examples/camera_livekit_bridge/bridge/stream_worker.cpp @@ -6,7 +6,6 @@ #include #include #include -#include #include #include @@ -15,7 +14,6 @@ #include #include #include -#include #include #include @@ -27,27 +25,20 @@ namespace constexpr auto kOverwriteReportInterval = std::chrono::seconds(5); -/// The loud error for a picture that may mix two frames. Rate limited per stream; the stats line keeps the totals. -void report_slot_overwrite_risk(const WorkerConfig& config, - const FrameNotice& notice, - std::size_t slot_count, - bool newer_notice, - bool late_copy, - int64_t age_ns, - int64_t deadline_ns, - uint64_t dropped_total) +/// The loud error for a picture whose slot the publisher rewrote after announcing it. Rate limited per stream; the +/// stats line keeps the totals. +void report_slot_overwrite(const WorkerConfig& config, + const FrameNotice& notice, + std::size_t slot_count, + bool during_copy, + uint64_t dropped_total) { - std::cerr << "\n!!!!!!!!!! SLOT OVERWRITE RISK on stream '" << config.stream << "': picture DROPPED !!!!!!!!!!\n" - << " The receiver's ring (" << slot_count << " slots) may have rewritten slot " << notice.slot - << " (generation " << notice.slot_generation << ") while this bridge was still reading it, so the\n" - << " pixels could be a mix of two frames under the first frame's ID and timestamp.\n"; - if (newer_notice) - std::cerr << " Evidence: a newer notice for the same slot, or a full ring of newer notices, arrived.\n"; - if (late_copy) - std::cerr << " Evidence: the copy finished " << static_cast(age_ns) / 1e6 - << " ms after the notice; the ring wraps in " << static_cast(deadline_ns) / 1e6 << " ms at " - << config.fps << " fps.\n"; std::cerr + << "\n!!!!!!!!!! SLOT OVERWRITE DETECTED on stream '" << config.stream << "': picture DROPPED !!!!!!!!!!\n" + << " The receiver began writing slot " << notice.slot << " (generation " << notice.slot_generation + << ") of its " << slot_count << "-slot ring " + << (during_copy ? "while this bridge was copying it" : "before this bridge started copying it") + << ",\n so the pixels could be a mix of two frames under the first frame's ID and timestamp.\n" << " Cause: this consumer is reading too slowly (starved GPU or CPU), or the receiver is delivering frames\n" << " faster than " << config.fps << " fps. Fix the stall; do not trust recordings of this period.\n" << " Pictures dropped for this reason so far: " << dropped_total << " (reported at most every " @@ -166,22 +157,13 @@ struct StreamWorker::Impl const IpcStream& stream = client.streams().front(); bool need_idr = true; - const int64_t deadline_ns = config.max_notice_age_ms != 0 ? - static_cast(config.max_notice_age_ms) * 1'000'000 : - slot_read_deadline_ns(config.fps, stream.slots.size()); auto last_overwrite_report = std::chrono::steady_clock::now() - kOverwriteReportInterval; uint32_t own_frame_id = 0; uint64_t last_session = 0; FrameNotice notice; - std::optional pending; // a newer notice seen while checking the last slot; used next while (running) { - if (pending) - { - notice = std::move(*pending); - pending.reset(); - } - else if (!client.next_frame(notice, std::chrono::milliseconds(200))) + if (!client.next_frame(notice, std::chrono::milliseconds(200))) continue; // Encode the newest picture: anything queued behind it is older, and a late frame is worse than a skipped // one. @@ -192,6 +174,24 @@ struct StreamWorker::Impl ++stats.skipped; } + // A picture whose slot the publisher rewrote is dropped, counted and reported loudly (rate limited). + const auto drop_overwritten = [&](bool during_copy) + { + ++stats.slot_overruns; + const auto now = std::chrono::steady_clock::now(); + if (now - last_overwrite_report >= kOverwriteReportInterval) + { + last_overwrite_report = now; + report_slot_overwrite(config, notice, stream.slots.size(), during_copy, stats.slot_overruns.load()); + } + }; + // Check before spending a copy on a slot that is already being rewritten. This only saves work; the check + // after the copy is the one that decides. + if (!client.slot_unchanged(notice)) + { + drop_overwritten(/*during_copy=*/false); + continue; + } const IpcSlot& slot = client.slot(notice); const auto* base = static_cast(slot.device_ptr); NvencEncoder::Surface surface; @@ -224,51 +224,19 @@ struct StreamWorker::Impl cudaGetErrorString(copy_status)); } - // The publisher overwrites a slot without notice once its ring wraps. The copy must have finished before - // that, and a newer notice for the same slot, or as many newer notices as the ring has other slots, means - // it may not have. Such a picture is dropped, never encoded. + // The copy must have finished before the marker is read: a write that began during it advanced the marker + // first, so an unchanged marker means no write overlapped the copy. A changed one means the picture may + // mix two frames; it is dropped, never encoded. if (cudaStreamSynchronize(copy_stream) != cudaSuccess) { encoder.release(surface); throw std::runtime_error("GPU copy from the IPC slot did not complete"); } + if (!client.slot_unchanged(notice)) { - bool overwritten = false; - std::size_t newer_count = 0; - FrameNotice newer; - while (client.next_frame(newer, std::chrono::milliseconds(0))) - { - ++newer_count; - if (newer.slot == notice.slot && newer.slot_generation > notice.slot_generation) - overwritten = true; - pending = std::move(newer); - } - if (stream.slots.size() > 1 && newer_count + 1 >= stream.slots.size()) - overwritten = true; - // The copy is done. If it finished later than the publisher needs to wrap its ring, the slot may have - // been overwritten during it, whether or not the replacement notice has arrived yet. - const int64_t copy_done_ns = monotonic_ns(); - const SlotAge age = classify_slot_age(notice.timestamp_ns, copy_done_ns, deadline_ns); - if (age == SlotAge::Unknown && deadline_ns > 0) - ++stats.unchecked_slot_reads; - const bool stale = age == SlotAge::Stale; - if (overwritten || stale) - { - encoder.release(surface); - if (overwritten) - ++stats.slot_overruns; - else - ++stats.stale_slot_reads; - const auto now = std::chrono::steady_clock::now(); - if (now - last_overwrite_report >= kOverwriteReportInterval) - { - last_overwrite_report = now; - report_slot_overwrite_risk(config, notice, stream.slots.size(), overwritten, stale, - copy_done_ns - static_cast(notice.timestamp_ns), - deadline_ns, stats.slot_overruns + stats.stale_slot_reads); - } - continue; - } + encoder.release(surface); + drop_overwritten(/*during_copy=*/true); + continue; } const uint64_t session_id = unsigned_field(notice.metadata, "session_id"); diff --git a/examples/camera_livekit_bridge/bridge/stream_worker.hpp b/examples/camera_livekit_bridge/bridge/stream_worker.hpp index 2d9cf6c4e1..8b37696e8d 100644 --- a/examples/camera_livekit_bridge/bridge/stream_worker.hpp +++ b/examples/camera_livekit_bridge/bridge/stream_worker.hpp @@ -26,9 +26,6 @@ struct WorkerConfig uint32_t fps = 30; uint32_t bitrate_bps = 8'000'000; uint32_t idr_period = 30; - /// A read that finishes later than this after its slot's notice is treated as possibly overwritten and dropped. - /// Zero derives it from the ring: the time the publisher needs to wrap it at `fps`. - uint32_t max_notice_age_ms = 0; /// Integer factor the picture is shrunk by on the GPU before encoding (1 keeps the source size). uint32_t scale_div = 1; /// The IPC pictures are full-range (0-255) rather than limited-range (16-235); the encoded stream signals it. The @@ -44,12 +41,9 @@ struct WorkerStats std::atomic skipped{ 0 }; std::atomic keyframes{ 0 }; std::atomic rejected{ 0 }; - /// Pictures dropped because the publisher may have overwritten the IPC slot during the copy. + /// Pictures dropped because the publisher began writing the IPC slot after announcing the picture, either before + /// the copy or while it ran. std::atomic slot_overruns{ 0 }; - /// Pictures dropped because the copy finished too long after the slot's notice for the pixels to be trusted, and - /// pictures whose notice carried no time to check (those are kept). - std::atomic stale_slot_reads{ 0 }; - std::atomic unchecked_slot_reads{ 0 }; std::atomic encode_us_total{ 0 }; /// The bitrate the encoder is configured for now, and how many times congestion feedback changed it. std::atomic bitrate_bps{ 0 }; diff --git a/examples/camera_livekit_bridge/ipc_client/CMakeLists.txt b/examples/camera_livekit_bridge/ipc_client/CMakeLists.txt index 490db23f5c..d39d3bff48 100644 --- a/examples/camera_livekit_bridge/ipc_client/CMakeLists.txt +++ b/examples/camera_livekit_bridge/ipc_client/CMakeLists.txt @@ -1,6 +1,13 @@ # SPDX-FileCopyrightText: Copyright (c) 2026 NVIDIA CORPORATION & AFFILIATES. All rights reserved. # SPDX-License-Identifier: Apache-2.0 +# The slot write-generation markers are shared with camera_receiver and its other readers; the header lives with them. +set(CAMERA_IPC_PROTOCOL_DIR "${CMAKE_CURRENT_SOURCE_DIR}/../../camera_streamer/ipc_protocol" + CACHE PATH "camera_streamer's ipc_protocol directory") +if(NOT EXISTS "${CAMERA_IPC_PROTOCOL_DIR}/inc/ipc_protocol/slot_markers.hpp") + message(FATAL_ERROR "slot_markers.hpp not found under CAMERA_IPC_PROTOCOL_DIR=${CAMERA_IPC_PROTOCOL_DIR}") +endif() + add_library(ipc_client STATIC cuda_ipc_client.cpp) target_include_directories(ipc_client @@ -8,9 +15,16 @@ target_include_directories(ipc_client $ ) +# The client's own sources include the markers header, and so do its consumers through cuda_ipc_client.hpp. +target_include_directories(ipc_client + PUBLIC + $ +) + target_link_libraries(ipc_client PUBLIC nlohmann_json::nlohmann_json + rt PRIVATE CUDA::cudart ) diff --git a/examples/camera_livekit_bridge/ipc_client/cuda_ipc_client.cpp b/examples/camera_livekit_bridge/ipc_client/cuda_ipc_client.cpp index 0d6c54980f..f8005c051d 100644 --- a/examples/camera_livekit_bridge/ipc_client/cuda_ipc_client.cpp +++ b/examples/camera_livekit_bridge/ipc_client/cuda_ipc_client.cpp @@ -6,6 +6,7 @@ #include #include +#include #include #include #include @@ -83,6 +84,8 @@ void CudaIpcClient::close_all() } } m_streams.clear(); + m_markers.reset(); + m_marker_streams.clear(); if (m_fd >= 0) { ::close(m_fd); @@ -166,6 +169,12 @@ void CudaIpcClient::connect() const auto hello = read_message(std::chrono::seconds(5), timed_out); if (timed_out || hello.value("type", "") != "hello") fail("expected a hello message from the IPC publisher"); + // A publisher that does not advance write generations gives no way to tell that a copy overlapped a rewrite. + const auto features = hello.value("features", nlohmann::json::array()); + if (std::find(features.begin(), features.end(), nlohmann::json("slot_write_generation")) == features.end()) + fail( + "the IPC publisher does not provide slot write generations, so a copied picture cannot be validated; " + "update camera_receiver"); send_message({ { "type", "subscribe" }, { "streams", m_requested } }); const auto subscribed = read_message(std::chrono::seconds(5), timed_out); if (timed_out) @@ -174,9 +183,29 @@ void CudaIpcClient::connect() fail("the IPC subscription was refused: " + subscribed.value("error", std::string("no reason given"))); if (subscribed.value("type", "") != "subscribed") fail("expected a subscribed message from the IPC publisher"); + open_markers(subscribed); open_streams(subscribed); } +void CudaIpcClient::open_markers(const nlohmann::json& subscribed) +{ + const auto descriptor = subscribed.find("slot_markers"); + if (descriptor == subscribed.end() || !descriptor->is_object()) + fail("the IPC publisher did not offer slot write generations"); + try + { + m_markers.emplace(camera_ipc::SlotMarkers::attach( + descriptor->at("name").get(), descriptor->at("size").get(), + descriptor->at("layout_version").get(), descriptor->at("epoch").get())); + } + catch (const nlohmann::json::exception& error) + { + fail(std::string("malformed slot write generation descriptor: ") + error.what()); + } + for (const auto& [name, index] : descriptor->at("stream_indexes").items()) + m_marker_streams[name] = index.get(); +} + void CudaIpcClient::open_streams(const nlohmann::json& subscribed) { for (const auto& entry : subscribed.at("streams")) @@ -221,6 +250,14 @@ const IpcSlot& CudaIpcClient::slot(const FrameNotice& notice) const throw std::out_of_range("unknown IPC stream " + notice.stream); } +bool CudaIpcClient::slot_unchanged(const FrameNotice& notice) const +{ + const auto stream = m_marker_streams.find(notice.stream); + if (!m_markers || stream == m_marker_streams.end()) + throw std::out_of_range("unknown IPC stream " + notice.stream); + return m_markers->unchanged(stream->second, static_cast(notice.slot), notice.slot_generation); +} + bool CudaIpcClient::next_frame(FrameNotice& out, std::chrono::milliseconds timeout) { const auto deadline = std::chrono::steady_clock::now() + timeout; diff --git a/examples/camera_livekit_bridge/ipc_client/inc/ipc_client/cuda_ipc_client.hpp b/examples/camera_livekit_bridge/ipc_client/inc/ipc_client/cuda_ipc_client.hpp index ddd6dc499e..c7213cb30e 100644 --- a/examples/camera_livekit_bridge/ipc_client/inc/ipc_client/cuda_ipc_client.hpp +++ b/examples/camera_livekit_bridge/ipc_client/inc/ipc_client/cuda_ipc_client.hpp @@ -3,12 +3,15 @@ #pragma once +#include #include #include #include #include +#include #include +#include #include namespace camera_bridge @@ -34,8 +37,9 @@ struct IpcStream std::vector slots; }; -/// A frame notification: the slot now holds a new picture. The slot is overwritten without notice when the -/// publisher's ring wraps, so a consumer must finish with it before `slot_generation` advances by the ring size. +/// A frame notification: the slot now holds a new picture, written under generation `slot_generation`. The publisher +/// rewrites a slot without notice when its ring wraps; a copy of it is valid only if `slot_unchanged` still holds after +/// the copy has finished. struct FrameNotice { std::string stream; @@ -50,8 +54,9 @@ struct FrameNotice * @brief Client of camera_receiver's CUDA IPC publisher (newline-delimited JSON on a unix socket). * * Protocol: the publisher sends `hello`; the client answers `subscribe` with stream names (all when empty); the - * publisher replies `subscribed` with one CUDA IPC handle per slot, then sends `frame` notices. Pixels never cross - * the socket. Must run in a different process from the publisher. + * publisher replies `subscribed` with one CUDA IPC handle per slot and the shared write-generation markers, then sends + * `frame` notices. Pixels never cross the socket. Must run in a different process from the publisher. A publisher + * without write generations is refused, because a copy from it cannot be validated. */ class CudaIpcClient { @@ -62,7 +67,8 @@ class CudaIpcClient CudaIpcClient(const CudaIpcClient&) = delete; CudaIpcClient& operator=(const CudaIpcClient&) = delete; - /// Connects, subscribes and opens every slot. Throws std::runtime_error with the reason on failure. + /// Connects, subscribes, maps the write-generation markers and opens every slot. Throws std::runtime_error with + /// the reason on failure, including a publisher that does not provide write generations. void connect(); const std::vector& streams() const @@ -73,6 +79,11 @@ class CudaIpcClient /// The slot a frame notice refers to; throws std::out_of_range for an unknown stream or slot. const IpcSlot& slot(const FrameNotice& notice) const; + /// Whether the publisher has begun no write on the notice's slot since it announced the notice's generation. A + /// copy of the slot may be used only if this is true after every GPU read of the slot has completed; checking + /// before the copy only saves work. + bool slot_unchanged(const FrameNotice& notice) const; + /// Waits up to `timeout` for the next frame notice. Returns false on timeout; throws if the publisher went away. bool next_frame(FrameNotice& out, std::chrono::milliseconds timeout); @@ -80,6 +91,7 @@ class CudaIpcClient nlohmann::json read_message(std::chrono::milliseconds timeout, bool& timed_out); void send_message(const nlohmann::json& message); void open_streams(const nlohmann::json& subscribed); + void open_markers(const nlohmann::json& subscribed); void close_all(); std::string m_socket_path; @@ -87,6 +99,8 @@ class CudaIpcClient int m_fd = -1; std::string m_buffer; std::vector m_streams; + std::optional m_markers; + std::unordered_map m_marker_streams; }; } // namespace camera_bridge diff --git a/examples/camera_livekit_bridge/tests/python/test_bridge_slot_age.py b/examples/camera_livekit_bridge/tests/python/test_bridge_slot_age.py deleted file mode 100644 index c32722c04d..0000000000 --- a/examples/camera_livekit_bridge/tests/python/test_bridge_slot_age.py +++ /dev/null @@ -1,250 +0,0 @@ -# SPDX-FileCopyrightText: Copyright (c) 2026 NVIDIA CORPORATION & AFFILIATES. All rights reserved. -# SPDX-License-Identifier: Apache-2.0 - -"""The bridge drops a picture whose notice is older than the ring's wrap time. - -A separate publisher process serves one NV12 stream through the real CUDA IPC -publisher, stamping each notice with ``time.monotonic_ns()`` (fresh) or ten -seconds earlier (stale). The bridge publishes to a local livekit-server; no -subscriber is needed, because the check is on the bridge's own stderr and -``[stats]`` line. - -Run: python3 test_bridge_slot_age.py -v (about 30 s; needs a CUDA device). - -Environment overrides: LIVEKIT_SERVER_BIN, CAMERA_LIVEKIT_BRIDGE_BIN, -CUPY_PYTHON (interpreter with CuPy for the publisher process). Skipped, never -faked, when a prerequisite is missing. -""" - -from __future__ import annotations - -import os -import re -import shutil -import signal -import socket -import sys -import tempfile -import time -import unittest -import uuid -from pathlib import Path - -from test_bridge_pipeline import ( - BRIDGE_BIN, - RECEIVER_DIR, - RECEIVER_PY, - SERVER_BIN, - _cuda_present, - _Proc, - _python_has, - free_port, - make_token, -) - -FPS = 30 -RING = 6 -WIDTH, HEIGHT = 320, 240 -STREAM, TRACK = "cam", "cam_track" -STALE_AGE_NS = 10_000_000_000 -PUBLISHER_IDENTITY = "bridge-pub" -RUN_S = 8.0 -STATS_TIMEOUT_S = 20.0 - -STATS_RE = re.compile( - r"\[stats\] " + TRACK + r": (?P[\d.]+) fps, (?P\d+) frames, " - r"(?P\d+) keyframes, (?P\d+) skipped, " - r"(?P\d+) rejected, (?P\d+) slot overruns, " - r"(?P\d+) stale slot reads," -) - - -def _cupy_python() -> Path: - override = os.environ.get("CUPY_PYTHON") - if override: - return Path(override) - if _python_has(RECEIVER_PY, "cupy"): - return RECEIVER_PY - return Path(sys.executable) - - -def _skip_reason() -> str | None: - if not SERVER_BIN.is_file(): - return f"livekit-server not found ({SERVER_BIN}); set LIVEKIT_SERVER_BIN" - if not BRIDGE_BIN.is_file(): - return f"camera_livekit_bridge not built ({BRIDGE_BIN}); set CAMERA_LIVEKIT_BRIDGE_BIN" - if not _cuda_present(): - return "no CUDA device (nvidia-smi -L lists no GPU)" - if not _python_has(_cupy_python(), "cupy"): - return f"{_cupy_python()} lacks CuPy; set CUPY_PYTHON" - return None - - -def _publisher_main(socket_path: str, mode: str) -> None: - """Child process: serve one stream and announce frames until terminated.""" - import cupy as cp - - sys.path.insert(0, str(RECEIVER_DIR)) - from cuda_ipc import CudaIpcFramePublisher - - publisher = CudaIpcFramePublisher(socket_path=socket_path, owner_name="slot_age") - y_bytes = WIDTH * HEIGHT - layout = { - "planes": [ - { - "name": "y", - "offset": 0, - "width": WIDTH, - "height": HEIGHT, - "pitch": WIDTH, - }, - { - "name": "uv", - "offset": y_bytes, - "width": WIDTH, - "height": HEIGHT // 2, - "pitch": WIDTH, - }, - ] - } - buffers = [ - cp.full((y_bytes * 3 // 2,), 100 + i, dtype=cp.uint8) for i in range(RING) - ] - publisher.register_stream(STREAM, WIDTH, HEIGHT, "nv12", 0, buffers, layout) - cp.cuda.Device(0).synchronize() - publisher.start() - - stopping = False - - def _stop(*_args: object) -> None: - nonlocal stopping - stopping = True - - signal.signal(signal.SIGTERM, _stop) - print("READY", flush=True) - - seq = 0 - while not stopping: - now = time.monotonic_ns() - publisher.publish( - STREAM, - slot=seq % RING, - slot_generation=seq // RING + 1, - seq=seq, - timestamp_ns=now - STALE_AGE_NS if mode == "stale" else now, - metadata={"session_id": 1, "stream_name": STREAM, "stream_sequence": seq}, - ) - seq += 1 - time.sleep(1.0 / FPS) - publisher.stop() - - -@unittest.skipIf(_skip_reason() is not None, _skip_reason() or "") -class BridgeSlotAgeTest(unittest.TestCase): - @classmethod - def setUpClass(cls): - cls._tmp = Path(tempfile.mkdtemp(prefix="bridge_slot_age_")) - cls.addClassCleanup(shutil.rmtree, cls._tmp, ignore_errors=True) - lk_port = free_port(socket.SOCK_STREAM) - cls.url = f"ws://127.0.0.1:{lk_port}" - cls.room = f"slot-age-{uuid.uuid4().hex[:10]}" - server = _Proc( - "livekit", - [ - str(SERVER_BIN), - "--dev", - "--bind", - "127.0.0.1", - "--node-ip", - "127.0.0.1", - "--port", - str(lk_port), - "--rtc.tcp_port", - str(free_port(socket.SOCK_STREAM)), - "--udp-port", - str(free_port(socket.SOCK_DGRAM)), - ], - cls._tmp, - ) - cls.addClassCleanup(server.stop) - server.wait_for("starting LiveKit server", 20) - deadline = time.monotonic() + 20 - while time.monotonic() < deadline: - try: - socket.create_connection(("127.0.0.1", lk_port), timeout=1).close() - break - except OSError: - time.sleep(0.2) - else: - raise AssertionError("livekit-server never accepted connections") - token = cls._tmp / "pub.token" - token.write_text(make_token(cls.room, PUBLISHER_IDENTITY, True)) - cls.token = token - - def _run(self, mode: str) -> str: - """Run publisher + bridge for RUN_S; return the bridge's output.""" - sock = self._tmp / f"{mode}.sock" - publisher = _Proc( - f"publisher_{mode}", - [ - str(_cupy_python()), - str(Path(__file__).resolve()), - "--publisher", - str(sock), - mode, - ], - self._tmp, - ) - self.addCleanup(publisher.stop) - publisher.wait_for("READY", 60) - bridge = _Proc( - f"bridge_{mode}", - [ - str(BRIDGE_BIN), - "--livekit-url", - self.url, - "--livekit-token-file", - str(self.token), - "--socket", - str(sock), - "--fps", - str(FPS), - "--stream", - f"{STREAM}={TRACK}", - ], - self._tmp, - ) - self.addCleanup(bridge.stop) - bridge.wait_for("publishing", 60) - time.sleep(RUN_S) - bridge.wait_for("[stats]", STATS_TIMEOUT_S) - text = bridge.text() - bridge.stop() - return text - - def _stats(self, text: str) -> dict[str, int]: - matches = list(STATS_RE.finditer(text)) - self.assertTrue(matches, f"no [stats] line for {TRACK}:\n{text[-3000:]}") - last = matches[-1] - return {k: int(float(v)) for k, v in last.groupdict().items()} - - def test_stale_notice_is_dropped_loudly(self): - text = self._run("stale") - self.assertIn("SLOT OVERWRITE RISK", text) - stats = self._stats(text) - self.assertGreater(stats["stale"], 0, text[-3000:]) - self.assertEqual(stats["frames"], 0, "a stale picture was published") - - def test_fresh_notice_is_published(self): - text = self._run("fresh") - self.assertNotIn("SLOT OVERWRITE RISK", text) - stats = self._stats(text) - self.assertEqual(stats["stale"], 0, text[-3000:]) - self.assertGreater(stats["frames"], 0, text[-3000:]) - - -if __name__ == "__main__": - if len(sys.argv) == 4 and sys.argv[1] == "--publisher": - _publisher_main(sys.argv[2], sys.argv[3]) - else: - unittest.main() diff --git a/examples/camera_livekit_bridge/tests/python/test_bridge_slot_marker.py b/examples/camera_livekit_bridge/tests/python/test_bridge_slot_marker.py new file mode 100644 index 0000000000..aedf35a33f --- /dev/null +++ b/examples/camera_livekit_bridge/tests/python/test_bridge_slot_marker.py @@ -0,0 +1,392 @@ +# SPDX-FileCopyrightText: Copyright (c) 2026 NVIDIA CORPORATION & AFFILIATES. All rights reserved. +# SPDX-License-Identifier: Apache-2.0 + +"""The bridge encodes only pictures whose slot write generation is unchanged. + +A separate publisher process serves one NV12 stream through the real CUDA IPC +publisher. Each notice carries the generation returned by ``begin_write``; the +"stale" notices are announced after the same slot's marker has advanced again, +which is what a rewrite that began after the announcement looks like. The +bridge publishes to a local livekit-server; no subscriber is needed, because +the checks are on the bridge's own stderr and ``[stats]`` line. A small relay +between the bridge and the real publisher covers a publisher that lacks the +feature and a damaged marker descriptor. + +Run: python3 test_bridge_slot_marker.py -v (about 60 s; needs a CUDA device). + +Environment overrides: LIVEKIT_SERVER_BIN, CAMERA_LIVEKIT_BRIDGE_BIN, +CUPY_PYTHON (interpreter with CuPy for the publisher process). Skipped, never +faked, when a prerequisite is missing. +""" + +from __future__ import annotations + +import json +import os +import re +import shutil +import signal +import socket +import subprocess +import sys +import tempfile +import threading +import time +import unittest +import uuid +from pathlib import Path + +from test_bridge_pipeline import ( + BRIDGE_BIN, + RECEIVER_DIR, + RECEIVER_PY, + SERVER_BIN, + _cuda_present, + _Proc, + _python_has, + free_port, + make_token, +) + +FPS = 30 +RING = 6 +WIDTH, HEIGHT = 320, 240 +STREAM, TRACK = "cam", "cam_track" +PUBLISHER_IDENTITY = "bridge-pub" +RUN_S = 6.0 +STATS_TIMEOUT_S = 20.0 +EXIT_TIMEOUT_S = 30.0 + +STATS_RE = re.compile( + r"\[stats\] " + TRACK + r": (?P[\d.]+) fps, (?P\d+) frames, " + r"(?P\d+) keyframes, (?P\d+) skipped, " + r"(?P\d+) rejected, (?P\d+) slot overruns," +) + + +def _cupy_python() -> Path: + override = os.environ.get("CUPY_PYTHON") + if override: + return Path(override) + if _python_has(RECEIVER_PY, "cupy"): + return RECEIVER_PY + return Path(sys.executable) + + +def _skip_reason() -> str | None: + if not SERVER_BIN.is_file(): + return f"livekit-server not found ({SERVER_BIN}); set LIVEKIT_SERVER_BIN" + if not BRIDGE_BIN.is_file(): + return f"camera_livekit_bridge not built ({BRIDGE_BIN}); set CAMERA_LIVEKIT_BRIDGE_BIN" + if not _cuda_present(): + return "no CUDA device (nvidia-smi -L lists no GPU)" + if not _python_has(_cupy_python(), "cupy"): + return f"{_cupy_python()} lacks CuPy; set CUPY_PYTHON" + return None + + +def _publisher_main(socket_path: str, mode: str) -> None: + """Child process: serve one stream and announce frames until terminated. + + ``valid`` announces the generation of the write just made. ``stale`` + advances the slot's marker a second time before announcing, so every + notice names a generation the slot has already left. ``mixed`` alternates. + """ + import cupy as cp + + sys.path.insert(0, str(RECEIVER_DIR)) + from cuda_ipc import CudaIpcFramePublisher + + publisher = CudaIpcFramePublisher(socket_path=socket_path, owner_name="slot_marker") + y_bytes = WIDTH * HEIGHT + layout = { + "planes": [ + { + "name": "y", + "offset": 0, + "width": WIDTH, + "height": HEIGHT, + "pitch": WIDTH, + }, + { + "name": "uv", + "offset": y_bytes, + "width": WIDTH, + "height": HEIGHT // 2, + "pitch": WIDTH, + }, + ] + } + buffers = [ + cp.full((y_bytes * 3 // 2,), 100 + i, dtype=cp.uint8) for i in range(RING) + ] + publisher.register_stream(STREAM, WIDTH, HEIGHT, "nv12", 0, buffers, layout) + cp.cuda.Device(0).synchronize() + publisher.start() + + stopping = False + + def _stop(*_args: object) -> None: + nonlocal stopping + stopping = True + + signal.signal(signal.SIGTERM, _stop) + print("READY", flush=True) + + seq = 0 + while not stopping: + slot = seq % RING + generation = publisher.begin_write(STREAM, slot) + if mode == "stale" or (mode == "mixed" and seq % 2 == 1): + publisher.begin_write(STREAM, slot) + publisher.publish( + STREAM, + slot=slot, + slot_generation=generation, + seq=seq, + timestamp_ns=time.monotonic_ns(), + metadata={"session_id": 1, "stream_name": STREAM, "stream_sequence": seq}, + ) + seq += 1 + time.sleep(1.0 / FPS) + publisher.stop() + + +class _Relay: + """Forwards one bridge connection to a real publisher, editing its replies. + + The handshake is ``hello``, ``subscribe``, ``subscribed``; ``edit`` is + applied to the parsed ``subscribed`` message and ``edit_hello`` to the + ``hello``. Either may be None to forward unchanged. + """ + + def __init__(self, path: Path, upstream: Path, edit_hello=None, edit=None): + self.path = path + self._upstream = upstream + self._edit_hello = edit_hello + self._edit = edit + self._server = socket.socket(socket.AF_UNIX, socket.SOCK_STREAM) + self._server.bind(str(path)) + self._server.listen(1) + self._thread = threading.Thread(target=self._serve, daemon=True) + self._thread.start() + + @staticmethod + def _line(sock: socket.socket) -> bytes: + data = b"" + while not data.endswith(b"\n"): + chunk = sock.recv(1) + if not chunk: + raise ConnectionError("peer closed") + data += chunk + return data + + def _serve(self) -> None: + try: + down, _ = self._server.accept() + up = socket.socket(socket.AF_UNIX, socket.SOCK_STREAM) + up.connect(str(self._upstream)) + with down, up: + hello = json.loads(self._line(up)) + if self._edit_hello: + self._edit_hello(hello) + down.sendall(json.dumps(hello).encode() + b"\n") + up.sendall(self._line(down)) + subscribed = json.loads(self._line(up)) + if self._edit: + self._edit(subscribed) + down.sendall(json.dumps(subscribed).encode() + b"\n") + time.sleep(2.0) + except (OSError, ConnectionError, ValueError): + pass + + def close(self) -> None: + self._server.close() + + +@unittest.skipIf(_skip_reason() is not None, _skip_reason() or "") +class BridgeSlotMarkerTest(unittest.TestCase): + @classmethod + def setUpClass(cls): + cls._tmp = Path(tempfile.mkdtemp(prefix="bridge_slot_marker_")) + cls.addClassCleanup(shutil.rmtree, cls._tmp, ignore_errors=True) + lk_port = free_port(socket.SOCK_STREAM) + cls.url = f"ws://127.0.0.1:{lk_port}" + cls.room = f"slot-marker-{uuid.uuid4().hex[:10]}" + server = _Proc( + "livekit", + [ + str(SERVER_BIN), + "--dev", + "--bind", + "127.0.0.1", + "--node-ip", + "127.0.0.1", + "--port", + str(lk_port), + "--rtc.tcp_port", + str(free_port(socket.SOCK_STREAM)), + "--udp-port", + str(free_port(socket.SOCK_DGRAM)), + ], + cls._tmp, + ) + cls.addClassCleanup(server.stop) + server.wait_for("starting LiveKit server", 20) + deadline = time.monotonic() + 20 + while time.monotonic() < deadline: + try: + socket.create_connection(("127.0.0.1", lk_port), timeout=1).close() + break + except OSError: + time.sleep(0.2) + else: + raise AssertionError("livekit-server never accepted connections") + token = cls._tmp / "pub.token" + token.write_text(make_token(cls.room, PUBLISHER_IDENTITY, True)) + cls.token = token + + def _start_publisher(self, mode: str) -> Path: + sock = self._tmp / f"{mode}_{uuid.uuid4().hex[:6]}.sock" + publisher = _Proc( + f"publisher_{mode}", + [str(_cupy_python()), str(Path(__file__).resolve()), "--publisher"] + + [str(sock), mode], + self._tmp, + ) + self.addCleanup(publisher.stop) + publisher.wait_for("READY", 60) + return sock + + def _bridge(self, name: str, sock: Path) -> _Proc: + bridge = _Proc( + name, + [ + str(BRIDGE_BIN), + "--livekit-url", + self.url, + "--livekit-token-file", + str(self.token), + "--socket", + str(sock), + "--fps", + str(FPS), + "--stream", + f"{STREAM}={TRACK}", + ], + self._tmp, + ) + self.addCleanup(bridge.stop) + return bridge + + def _run(self, mode: str) -> str: + """Run publisher + bridge for RUN_S; return the bridge's output.""" + bridge = self._bridge(f"bridge_{mode}", self._start_publisher(mode)) + bridge.wait_for("publishing", 60) + time.sleep(RUN_S) + bridge.wait_for("[stats]", STATS_TIMEOUT_S) + text = bridge.text() + bridge.stop() + return text + + def _stats(self, text: str) -> dict[str, int]: + matches = list(STATS_RE.finditer(text)) + self.assertTrue(matches, f"no [stats] line for {TRACK}:\n{text[-3000:]}") + last = matches[-1] + return {k: int(float(v)) for k, v in last.groupdict().items()} + + def _refused(self, sock: Path, name: str) -> str: + """Run the bridge against ``sock``; it must exit non-zero; return its output.""" + bridge = self._bridge(name, sock) + try: + bridge.proc.wait(timeout=EXIT_TIMEOUT_S) + except subprocess.TimeoutExpired: + self.fail(f"bridge did not exit:\n{bridge.text()[-3000:]}") + self.assertNotEqual(bridge.proc.returncode, 0, bridge.text()[-3000:]) + text = bridge.text() + self.assertNotRegex(text, r"\d+ frames", "the bridge streamed anyway") + return text + + def test_unchanged_marker_is_encoded(self): + text = self._run("valid") + self.assertNotIn("SLOT OVERWRITE", text) + stats = self._stats(text) + self.assertEqual(stats["overruns"], 0, text[-3000:]) + self.assertGreater(stats["frames"], 0, text[-3000:]) + + def test_advanced_marker_is_dropped_loudly(self): + text = self._run("stale") + self.assertIn("SLOT OVERWRITE", text) + stats = self._stats(text) + self.assertGreater(stats["overruns"], 0, text[-3000:]) + self.assertEqual(stats["frames"], 0, "an overwritten picture was encoded") + + def test_only_the_overwritten_pictures_are_dropped(self): + text = self._run("mixed") + self.assertIn("SLOT OVERWRITE", text) + stats = self._stats(text) + self.assertGreater(stats["overruns"], 0, text[-3000:]) + self.assertGreater(stats["frames"], 0, text[-3000:]) + + def test_publisher_without_write_generations_is_refused(self): + upstream = self._start_publisher("valid") + + def drop_feature(hello: dict) -> None: + hello["features"] = [ + f for f in hello["features"] if f != "slot_write_generation" + ] + + relay = _Relay(self._tmp / "nofeature.sock", upstream, edit_hello=drop_feature) + self.addCleanup(relay.close) + text = self._refused(relay.path, "bridge_nofeature") + self.assertIn("does not provide slot write generations", text) + + def test_missing_marker_descriptor_is_refused(self): + upstream = self._start_publisher("valid") + relay = _Relay( + self._tmp / "nodesc.sock", + upstream, + edit=lambda msg: msg.pop("slot_markers", None), + ) + self.addCleanup(relay.close) + text = self._refused(relay.path, "bridge_nodesc") + self.assertIn("did not offer slot write generations", text) + + def test_wrong_epoch_descriptor_is_refused(self): + upstream = self._start_publisher("valid") + + def wrong_epoch(msg: dict) -> None: + msg["slot_markers"]["epoch"] += 1 + + relay = _Relay(self._tmp / "epoch.sock", upstream, edit=wrong_epoch) + self.addCleanup(relay.close) + text = self._refused(relay.path, "bridge_epoch") + self.assertIn("[error]", text) + self.assertIn("not the advertised region", text) + + def test_garbled_descriptors_are_refused(self): + edits = { + "layout": lambda d: d.update(layout_version=d["layout_version"] + 1), + "size": lambda d: d.update(size=d["size"] + 8), + "name": lambda d: d.update(name="/no_such_marker_region"), + "fields": lambda d: d.pop("epoch"), + "type": lambda d: d.update(size="large"), + } + upstream = self._start_publisher("valid") + for label, edit in edits.items(): + with self.subTest(label): + relay = _Relay( + self._tmp / f"garbled_{label}.sock", + upstream, + edit=lambda msg, edit=edit: edit(msg["slot_markers"]), + ) + self.addCleanup(relay.close) + text = self._refused(relay.path, f"bridge_garbled_{label}") + self.assertIn("[error]", text) + + +if __name__ == "__main__": + if len(sys.argv) == 4 and sys.argv[1] == "--publisher": + _publisher_main(sys.argv[2], sys.argv[3]) + else: + unittest.main() diff --git a/examples/camera_livekit_bridge/tests/slot_age/CMakeLists.txt b/examples/camera_livekit_bridge/tests/slot_age/CMakeLists.txt deleted file mode 100644 index 51a7fbac02..0000000000 --- a/examples/camera_livekit_bridge/tests/slot_age/CMakeLists.txt +++ /dev/null @@ -1,13 +0,0 @@ -# SPDX-FileCopyrightText: Copyright (c) 2026 NVIDIA CORPORATION & AFFILIATES. All rights reserved. -# SPDX-License-Identifier: Apache-2.0 - -add_executable(test_slot_age test_slot_age.cpp) - -target_link_libraries(test_slot_age - PRIVATE - camera_livekit_bridge::video_types -) - -target_compile_options(test_slot_age PRIVATE -Wall -Wextra) - -add_test(NAME slot_age COMMAND test_slot_age) diff --git a/examples/camera_livekit_bridge/tests/slot_age/test_slot_age.cpp b/examples/camera_livekit_bridge/tests/slot_age/test_slot_age.cpp deleted file mode 100644 index 5adeaf56d0..0000000000 --- a/examples/camera_livekit_bridge/tests/slot_age/test_slot_age.cpp +++ /dev/null @@ -1,71 +0,0 @@ -// SPDX-FileCopyrightText: Copyright (c) 2026 NVIDIA CORPORATION & AFFILIATES. All rights reserved. -// SPDX-License-Identifier: Apache-2.0 - -#include - -#include -#include - -namespace -{ - -int g_failures = 0; - -void check(bool condition, const char* what) -{ - if (!condition) - { - std::cerr << "FAILED: " << what << "\n"; - ++g_failures; - } -} - -} // namespace - -int main() -{ - using camera_bridge::classify_slot_age; - using camera_bridge::slot_read_deadline_ns; - using camera_bridge::SlotAge; - - // The publisher wraps a ring of N slots after N - 1 further frames. - check(slot_read_deadline_ns(30, 6) == 5 * 1'000'000'000LL / 30, "6 slots at 30 fps"); - check(slot_read_deadline_ns(30, 6) >= 166'666'666 && slot_read_deadline_ns(30, 6) <= 166'666'667, - "6 slots at 30 fps is about 166.67 ms"); - check(slot_read_deadline_ns(60, 3) == 2 * 1'000'000'000LL / 60, "3 slots at 60 fps"); - check(slot_read_deadline_ns(30, 2) == 1'000'000'000LL / 30, "2 slots is the smallest usable ring"); - check(slot_read_deadline_ns(0, 6) == 0, "fps 0 disables the check"); - check(slot_read_deadline_ns(30, 1) == 0, "a one-slot ring disables the check"); - check(slot_read_deadline_ns(30, 0) == 0, "an empty ring disables the check"); - - const int64_t now = 10'000'000'000; - const int64_t deadline = 166'000'000; - const uint64_t notice = static_cast(now - 100'000'000); - - check(classify_slot_age(notice, now, deadline) == SlotAge::Fresh, "well within the deadline is fresh"); - check(classify_slot_age(static_cast(now), now, deadline) == SlotAge::Fresh, "age 0 is fresh"); - check(classify_slot_age(static_cast(now - deadline), now, deadline) == SlotAge::Fresh, - "exactly at the deadline is fresh"); - check(classify_slot_age(static_cast(now - deadline - 1), now, deadline) == SlotAge::Stale, - "one nanosecond past the deadline is stale"); - check(classify_slot_age(static_cast(now - 5'000'000'000), now, deadline) == SlotAge::Stale, - "long past the deadline is stale"); - - check(classify_slot_age(0, now, deadline) == SlotAge::Unknown, "no notice time is unknown"); - check(classify_slot_age(static_cast(now + 1), now, deadline) == SlotAge::Unknown, - "a notice from the future is unknown"); - check(classify_slot_age(static_cast(now + 5'000'000'000), now, deadline) == SlotAge::Unknown, - "a notice far in the future is unknown"); - check(classify_slot_age(notice, now, 0) == SlotAge::Unknown, "deadline 0 disables the check"); - check(classify_slot_age(notice, now, -1) == SlotAge::Unknown, "a negative deadline disables the check"); - // Even a very old notice is not judged when the check is off. - check(classify_slot_age(1, now, 0) == SlotAge::Unknown, "deadline 0 beats an ancient notice"); - - if (g_failures != 0) - { - std::cerr << g_failures << " check(s) failed\n"; - return 1; - } - std::cout << "slot_age: all checks passed\n"; - return 0; -} diff --git a/examples/camera_livekit_bridge/video_types/inc/video_types/slot_age.hpp b/examples/camera_livekit_bridge/video_types/inc/video_types/slot_age.hpp deleted file mode 100644 index 63deb76c9a..0000000000 --- a/examples/camera_livekit_bridge/video_types/inc/video_types/slot_age.hpp +++ /dev/null @@ -1,37 +0,0 @@ -// SPDX-FileCopyrightText: Copyright (c) 2026 NVIDIA CORPORATION & AFFILIATES. All rights reserved. -// SPDX-License-Identifier: Apache-2.0 - -#pragma once - -#include -#include - -namespace camera_bridge -{ - -/// How long after its notice a slot is still safe to read: the time the publisher needs to write the other slots of -/// its ring and come back to this one, at the stream's nominal rate. Zero when the rate or ring is unusable. -inline int64_t slot_read_deadline_ns(uint32_t fps, std::size_t slot_count) -{ - if (fps == 0 || slot_count < 2) - return 0; - return static_cast(slot_count - 1) * 1'000'000'000 / static_cast(fps); -} - -enum class SlotAge -{ - Fresh, ///< the read finished within the deadline - Stale, ///< the read finished after the deadline: the slot may have been overwritten during it - Unknown, ///< the notice has no usable time (missing, or later than now): nothing can be said -}; - -/// Classify a read that finished at `now_ns` (CLOCK_MONOTONIC) of the slot announced at `notice_ns` (the publisher's -/// CLOCK_MONOTONIC on the same host). A deadline of zero disables the check. -inline SlotAge classify_slot_age(uint64_t notice_ns, int64_t now_ns, int64_t deadline_ns) -{ - if (deadline_ns <= 0 || notice_ns == 0 || static_cast(notice_ns) > now_ns) - return SlotAge::Unknown; - return now_ns - static_cast(notice_ns) > deadline_ns ? SlotAge::Stale : SlotAge::Fresh; -} - -} // namespace camera_bridge diff --git a/examples/camera_streamer/camera_receiver/README.md b/examples/camera_streamer/camera_receiver/README.md index 2d47f3bdac..174848ece7 100644 --- a/examples/camera_streamer/camera_receiver/README.md +++ b/examples/camera_streamer/camera_receiver/README.md @@ -38,10 +38,12 @@ The setup script creates: ```text .venv/ codec/_camera_receiver_codec*.so +../ipc_protocol/_slot_markers*.so ``` -It installs the Python dependencies from `requirements.txt` and builds the -local native decoder from `codec/`. +It installs the Python dependencies from `requirements.txt`, builds the local +native decoder from `codec/` and builds the shared slot marker module from +[`ipc_protocol/`](../ipc_protocol/README.md). ## Run @@ -114,9 +116,15 @@ rotation during that existing output write. HEVC NV12 rotation replaces the normal NVDEC-to-ring device copy with a rotation kernel; RGBA rotation is fused into color conversion, so neither path adds a second full-frame pass. -`ring_depth` controls how many slots each physical IPC stream owns. Frame -notifications include `slot_generation`; consumers can detect if a slot was -overwritten before they consumed it. +`ring_depth` controls how many slots each physical IPC stream owns. The receiver +cycles through them without waiting for consumers, so a slot is rewritten +`ring_depth` pictures after it was announced. It advances the slot's shared +write-generation marker before it touches the pixels and announces that +generation in the frame notice's `slot_generation` once the write is complete. A +consumer copies the pixels, waits for its copy to finish, and accepts the copy +only if the marker still equals the notified generation. Generations skip a value +when a write attempt fails, so a gap is not a lost picture; use the frame +sequence for that. See [`ipc_protocol/`](../ipc_protocol/README.md). ## Downstream consumers @@ -130,8 +138,10 @@ already remapped by the sender, so consumers must not apply the wrist remap agai See the bundled [remap geometry and calibration](../argus_sender/remaps/README.md). Notifications include frame sequence, slot generation, source timing and local -publish timing. Validate frame identity and generation when associating frames -with metadata. The rings are bounded live buffers, not a durable recording queue. +publish timing. A consumer that reads the pixels must validate its copy against +the slot's marker, as described above; one that ignores the marker can receive a +picture that mixes two frames. The rings are bounded live buffers, not a durable +recording queue. ## Latency diff --git a/examples/camera_streamer/camera_receiver/camera_receiver.py b/examples/camera_streamer/camera_receiver/camera_receiver.py index 05b214b818..b0157f1cba 100755 --- a/examples/camera_streamer/camera_receiver/camera_receiver.py +++ b/examples/camera_streamer/camera_receiver/camera_receiver.py @@ -391,9 +391,6 @@ def __init__(self, config: StreamConfig, gpu_id: int) -> None: self.gpu_id = int(gpu_id) self.camera_count = 2 if config.stereo else 1 self.write_index = 0 - self.slot_generations = [ - [0 for _ in range(config.ring_depth)] for _ in range(self.camera_count) - ] self.decoders: list[Optional[NvVideoDecoder]] = [None] * self.camera_count self.executor = ThreadPoolExecutor( max_workers=1, @@ -456,10 +453,6 @@ def shutdown(self) -> None: self.executor.shutdown(wait=True) self.reset_decoders() - def next_generation(self, camera_index: int, slot: int) -> int: - self.slot_generations[camera_index][slot] += 1 - return self.slot_generations[camera_index][slot] - class Avs1TcpReceiver: def __init__( @@ -764,27 +757,40 @@ def _process_stream( self._validate_stream_descriptor(stream, runtime.config) slot = runtime.write_index + # Advance every eye's marker before any GPU work can touch the slot, so a reader's + # final check sees every write that may have overlapped its copy. A failed attempt + # keeps its new generation, which invalidates the slot's earlier notices. + generations = { + sample.camera_index: self._ipc_publisher.begin_write( + runtime.config.ipc_names[sample.camera_index], slot + ) + for sample in stream.samples + } t0 = time.monotonic() receiver_process_submit_mono_ns = time.monotonic_ns() receiver_process_submit_ns, _ = _read_wall_clock_ns() assert self._sample_pool is not None futures: list[Future[bool]] = [ - self._sample_pool.submit( - self._process_sample, runtime, stream, sample, slot - ) + self._sample_pool.submit(self._write_sample, runtime, stream, sample, slot) for sample in stream.samples ] # Finish every eye before a failure can allow slot reuse or decoder reset. wait(futures) - if not all(future.result() for future in futures): + errors = [future.exception() for future in futures] + if any(errors) or not all(future.result() for future in futures): + # Nothing is published. Drain the device so no launched work overlaps the next + # attempt on this slot, then report the first failure. + with cp.cuda.Device(self._gpu_device_id): + cp.cuda.Device().synchronize() + for error in errors: + if error is not None: + raise error return receiver_process_done_mono_ns = time.monotonic_ns() receiver_process_done_ns, _ = _read_wall_clock_ns() - # The native decoder is synchronous. Raw NV12 copies / conversion kernels - # run on CuPy's current stream, so sync before announcing IPC visibility. - with cp.cuda.Device(self._gpu_device_id): - cp.cuda.get_current_stream().synchronize() + # The native decoder is synchronous and every worker waited for its own CUDA stream, + # which carries the raw copies and conversion kernels, so the slot is complete here. timestamp_ns = time.monotonic_ns() receiver_ipc_publish_mono_ns = timestamp_ns @@ -802,7 +808,7 @@ def _process_stream( ) for sample in stream.samples: - generation = runtime.next_generation(sample.camera_index, slot) + generation = generations[sample.camera_index] metadata = self._frame_metadata( bundle=bundle, stream=stream, @@ -835,6 +841,25 @@ def _process_stream( latencies, ) + def _write_sample( + self, + runtime: _StreamRuntime, + stream: Avs1Stream, + sample: Avs1Sample, + slot: int, + ) -> bool: + """Write one eye and wait for this worker's own GPU stream. + + The marker may be announced only after every launch that wrote the slot has completed, + whichever thread ran it, so each worker finishes its stream before returning. + """ + import cupy as cp + + ok = self._process_sample(runtime, stream, sample, slot) + with cp.cuda.Device(self._gpu_device_id): + cp.cuda.get_current_stream().synchronize() + return ok + def _process_sample( self, runtime: _StreamRuntime, diff --git a/examples/camera_streamer/camera_receiver/cuda_ipc.py b/examples/camera_streamer/camera_receiver/cuda_ipc.py index 6d20b5b002..85e6c752d7 100644 --- a/examples/camera_streamer/camera_receiver/cuda_ipc.py +++ b/examples/camera_streamer/camera_receiver/cuda_ipc.py @@ -6,11 +6,15 @@ 1. Publisher -> client: ``hello`` stream catalog, no CUDA handles yet. 2. Client -> publisher: ``subscribe`` with stream names, or omitted/empty for all. -3. Publisher -> client: ``subscribed`` with CUDA IPC handles for selected streams. +3. Publisher -> client: ``subscribed`` with CUDA IPC handles for selected streams + and the shared write-generation markers for their slots. 4. Publisher -> client: ``frame`` notifications for selected streams only. Image bytes stay in same-host CUDA IPC memory. The socket only carries control -messages and per-frame metadata. +messages and per-frame metadata. The receiver advances a slot's marker before it +touches the slot's pixels and announces that generation once the write is +complete, so a reader that finds the marker unchanged after its copy finished +holds a picture that no write overlapped (see ``ipc_protocol``). """ from __future__ import annotations @@ -22,11 +26,15 @@ import queue import signal import socket +import sys import threading from dataclasses import dataclass from pathlib import Path from typing import Any, Optional +# ipc_protocol is a sibling of camera_receiver; import it from the source tree without an install step. +_STREAMER_ROOT = str(Path(__file__).resolve().parents[1]) + logger = logging.getLogger("isaaccapture.camera_streamer.ipc") _CLIENT_SEND_TIMEOUT_S = 2.0 @@ -35,6 +43,15 @@ _SEND_FLAGS = getattr(socket, "MSG_NOSIGNAL", 0) +def _markers_module(): + """The native slot-marker module, imported on first use.""" + if _STREAMER_ROOT not in sys.path: + sys.path.append(_STREAMER_ROOT) + import ipc_protocol + + return ipc_protocol + + @dataclass(frozen=True) class _SlotInfo: slot: int @@ -73,6 +90,8 @@ def __init__( ) -> None: self._socket_path = str(socket_path) self._owner_name = owner_name + self._stream_order: list[str] = [] + self._markers: Any = None self._queue: "queue.Queue[dict[str, Any]]" = queue.Queue(maxsize=queue_size) self._streams: dict[str, _StreamInfo] = {} self._clients: list[_ClientState] = [] @@ -132,6 +151,9 @@ def register_stream( with self._lock: if name in self._streams: raise ValueError(f"CUDA IPC stream {name!r} registered twice") + if self._started: + raise RuntimeError("CUDA IPC streams must be registered before start()") + self._stream_order.append(name) self._streams[name] = _StreamInfo( name=name, width=int(width), @@ -157,8 +179,14 @@ def start(self) -> None: self._ignore_sigpipe() self._stop.clear() try: + if self._stream_order: + self._markers = _markers_module().SlotMarkers.create( + "/camera_receiver_slots", + [len(self._streams[n].slots) for n in self._stream_order], + ) self._open_server() except Exception: + self._close_markers() with self._lock: self._started = False raise @@ -205,6 +233,7 @@ def stop(self) -> None: thread.join(timeout=2.0) self._accept_thread = None self._broadcast_thread = None + self._close_markers() try: if os.path.exists(self._socket_path): os.unlink(self._socket_path) @@ -213,6 +242,22 @@ def stop(self) -> None: "CUDA IPC: failed to unlink %s", self._socket_path, exc_info=True ) + def begin_write(self, stream_name: str, slot: int) -> int: + """Record a write attempt on ``slot`` and return its generation. + + Call before the first GPU operation that may touch the slot, for every stream the + attempt writes. Publish the returned generation only if the attempt succeeds; a failed + attempt is never undone, so earlier notices for the slot stay invalid. + """ + if self._markers is None: + raise RuntimeError("CUDA IPC publisher is not started") + return self._markers.begin_write(self._stream_order.index(stream_name), slot) + + def _close_markers(self) -> None: + markers, self._markers = self._markers, None + if markers is not None: + markers.close() + def publish( self, stream_name: str, @@ -296,6 +341,18 @@ def _stream_with_slots(self, stream: _StreamInfo) -> dict[str, Any]: ] return msg + def _markers_descriptor(self) -> Optional[dict[str, Any]]: + markers = self._markers + if markers is None: + return None + return { + "name": markers.name, + "size": markers.size, + "layout_version": markers.layout_version, + "epoch": markers.epoch, + "stream_indexes": {n: i for i, n in enumerate(self._stream_order)}, + } + def _hello_message(self) -> dict[str, Any]: with self._lock: streams = list(self._streams.values()) @@ -308,6 +365,7 @@ def _hello_message(self) -> dict[str, Any]: "avs1_metadata", "latency_metadata", "slot_generation", + "slot_write_generation", "nv12", ], "owner": self._owner_name, @@ -329,6 +387,7 @@ def _subscribed_message( { "type": "subscribed", "version": 2, + "slot_markers": self._markers_descriptor(), "streams": [ self._stream_with_slots(all_streams[name]) for name in selected_names diff --git a/examples/camera_streamer/camera_receiver/setup.sh b/examples/camera_streamer/camera_receiver/setup.sh index b6a71c7372..462f02b176 100755 --- a/examples/camera_streamer/camera_receiver/setup.sh +++ b/examples/camera_streamer/camera_receiver/setup.sh @@ -2,7 +2,7 @@ # SPDX-FileCopyrightText: Copyright (c) 2026 NVIDIA CORPORATION & AFFILIATES. All rights reserved. # SPDX-License-Identifier: Apache-2.0 # -# Create camera_receiver's local Python environment and build its local decoder. +# Create camera_receiver's local Python environment and build its local decoder and slot marker module. set -euo pipefail HERE="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)" @@ -69,13 +69,16 @@ export CAMERA_RECEIVER_VENV="$VENV" export CAMERA_RECEIVER_PYTHON="$PYTHON_EXE" if [[ "${CAMERA_RECEIVER_CLEAN_BUILD:-1}" != "0" ]]; then - echo "setup.sh: cleaning codec/build" - rm -rf "${HERE}/codec/build" + echo "setup.sh: cleaning codec/build and ipc_protocol/build" + rm -rf "${HERE}/codec/build" "${HERE}/../ipc_protocol/build" fi echo "setup.sh: building native decoder" "${HERE}/codec/build.sh" +echo "setup.sh: building slot marker module" +IPC_PROTOCOL_PYTHON="$PYTHON_EXE" "${HERE}/../ipc_protocol/build.sh" + echo "setup.sh: verifying receiver config" "$PYTHON_EXE" "${HERE}/camera_receiver.py" \ --config "${HERE}/configs/receiver.yaml" \ diff --git a/examples/camera_streamer/camera_receiver/tests/test_sample_completion.py b/examples/camera_streamer/camera_receiver/tests/test_sample_completion.py index 52b9b8a38c..4b08f67871 100644 --- a/examples/camera_streamer/camera_receiver/tests/test_sample_completion.py +++ b/examples/camera_streamer/camera_receiver/tests/test_sample_completion.py @@ -2,6 +2,7 @@ # SPDX-License-Identifier: Apache-2.0 from concurrent.futures import ThreadPoolExecutor +import logging import sys import threading from types import ModuleType, SimpleNamespace @@ -12,22 +13,95 @@ from camera_receiver import Avs1TcpReceiver +class _Recorder: + """Thread-safe ordered log of what the fake publisher, workers and CUDA did.""" + + def __init__(self): + self.events = [] + self._lock = threading.Lock() + + def add(self, *event): + with self._lock: + self.events.append(event) + + def kinds(self): + return [event[0] for event in self.events] + + +def _fake_cupy(recorder): + """The little of CuPy that the write path touches, recording who synchronizes what.""" + cupy = ModuleType("cupy") + + class Device: + def __init__(self, _id=None): + pass + + def __enter__(self): + return self + + def __exit__(self, *_): + return False + + def synchronize(self): + recorder.add("device_sync", threading.get_ident()) + + class Stream: + def synchronize(self): + recorder.add("stream_sync", threading.get_ident()) + + cupy.cuda = SimpleNamespace(Device=Device, get_current_stream=Stream) + return cupy + + +def _receiver(recorder, *, process_sample, generations=None, stereo=True): + receiver = Avs1TcpReceiver.__new__(Avs1TcpReceiver) + receiver._validate_stream_descriptor = Mock() + receiver._gpu_device_id = 0 + receiver._stats = None + receiver._frame_metadata = Mock(return_value={}) + receiver._receiver_latencies = Mock(return_value={}) + counters = {} + + def begin_write(name, slot): + counters[(name, slot)] = counters.get((name, slot), 0) + 1 + generation = (generations or {}).get(name, 100) + counters[(name, slot)] + recorder.add("begin_write", name, slot, generation) + return generation + + receiver._ipc_publisher = Mock() + receiver._ipc_publisher.begin_write.side_effect = begin_write + receiver._process_sample = process_sample + eyes = 2 if stereo else 1 + runtime = SimpleNamespace( + write_index=0, + config=SimpleNamespace( + name="head", ring_depth=3, ipc_names=["head_left", "head_right"][:eyes] + ), + ) + stream = SimpleNamespace( + samples=tuple(SimpleNamespace(camera_index=i) for i in range(eyes)), + sequence=7, + tsc_delta_ns=0, + ) + return receiver, runtime, stream + + +def _run(receiver, runtime, stream): + with ThreadPoolExecutor(max_workers=2) as sample_pool: + receiver._sample_pool = sample_pool + receiver._process_stream(None, None, stream, runtime) + + @pytest.mark.parametrize("failure_index", [0, 1]) @pytest.mark.parametrize("raises", [False, True]) def test_failed_stereo_bundle_finishes_both_eyes_before_next_operation( monkeypatch, failure_index, raises ): - monkeypatch.setitem(sys.modules, "cupy", ModuleType("cupy")) + recorder = _Recorder() + monkeypatch.setitem(sys.modules, "cupy", _fake_cupy(recorder)) blocked_eye_started = threading.Event() release_eye = threading.Event() next_operation = threading.Event() - receiver = Avs1TcpReceiver.__new__(Avs1TcpReceiver) - receiver._validate_stream_descriptor = Mock() - receiver._ipc_publisher = Mock() - runtime = SimpleNamespace(write_index=0, config=SimpleNamespace(name="head")) - stream = SimpleNamespace( - samples=tuple(SimpleNamespace(camera_index=i) for i in range(2)) - ) def process_sample(_runtime, _stream, sample, _slot): if sample.camera_index == failure_index: @@ -39,7 +113,7 @@ def process_sample(_runtime, _stream, sample, _slot): raise TimeoutError("test did not release the other eye") return True - receiver._process_sample = process_sample + receiver, runtime, stream = _receiver(recorder, process_sample=process_sample) with ( ThreadPoolExecutor(max_workers=2) as sample_pool, ThreadPoolExecutor(max_workers=1) as stream_pool, @@ -64,3 +138,209 @@ def process_sample(_runtime, _stream, sample, _slot): assert runtime.write_index == 0 receiver._ipc_publisher.publish.assert_not_called() + + +def test_every_eye_marker_advances_before_any_sample_starts(monkeypatch): + recorder = _Recorder() + monkeypatch.setitem(sys.modules, "cupy", _fake_cupy(recorder)) + + def process_sample(_runtime, _stream, sample, slot): + recorder.add("process", sample.camera_index, slot) + return True + + receiver, runtime, stream = _receiver(recorder, process_sample=process_sample) + runtime.write_index = 2 + _run(receiver, runtime, stream) + + kinds = recorder.kinds() + assert kinds[:2] == ["begin_write", "begin_write"] + assert [e[1:3] for e in recorder.events[:2]] == [ + ("head_left", 2), + ("head_right", 2), + ] + assert kinds.count("process") == 2 + assert kinds.index("process") > 1 + + +def test_failing_eye_leaves_markers_advanced_and_publishes_nothing(monkeypatch): + recorder = _Recorder() + monkeypatch.setitem(sys.modules, "cupy", _fake_cupy(recorder)) + receiver, runtime, stream = _receiver( + recorder, process_sample=lambda _r, _s, sample, _slot: sample.camera_index == 0 + ) + _run(receiver, runtime, stream) + + assert recorder.kinds().count("begin_write") == 2 + receiver._ipc_publisher.publish.assert_not_called() + assert runtime.write_index == 0 + assert "device_sync" in recorder.kinds() + # The next attempt on the same slot gets a newer generation than the failed one. + first = [e[3] for e in recorder.events if e[0] == "begin_write"] + recorder.events.clear() + receiver._process_sample = lambda *_: True + _run(receiver, runtime, stream) + second = [e[3] for e in recorder.events if e[0] == "begin_write"] + assert all(b > a for a, b in zip(first, second)) + assert runtime.write_index == 1 + + +def test_exception_in_one_eye_waits_for_the_other_drains_and_reraises(monkeypatch): + recorder = _Recorder() + monkeypatch.setitem(sys.modules, "cupy", _fake_cupy(recorder)) + other_started = threading.Event() + release_other = threading.Event() + + def process_sample(_runtime, _stream, sample, _slot): + if sample.camera_index == 0: + other_started.wait(timeout=5) + raise RuntimeError("eye 0 exploded") + other_started.set() + assert release_other.wait(timeout=5) + recorder.add("other_eye_done") + return True + + receiver, runtime, stream = _receiver(recorder, process_sample=process_sample) + with ( + ThreadPoolExecutor(max_workers=2) as sample_pool, + ThreadPoolExecutor(max_workers=1) as stream_pool, + ): + receiver._sample_pool = sample_pool + processing = stream_pool.submit( + receiver._process_stream, None, None, stream, runtime + ) + assert other_started.wait(timeout=2) + assert not processing.done() + release_other.set() + with pytest.raises(RuntimeError, match="eye 0 exploded"): + processing.result(timeout=5) + + kinds = recorder.kinds() + assert kinds.index("other_eye_done") < kinds.index("device_sync") + receiver._ipc_publisher.publish.assert_not_called() + + +def test_first_exception_wins_when_both_eyes_raise(monkeypatch): + recorder = _Recorder() + monkeypatch.setitem(sys.modules, "cupy", _fake_cupy(recorder)) + + def process_sample(_runtime, _stream, sample, _slot): + raise RuntimeError(f"eye {sample.camera_index}") + + receiver, runtime, stream = _receiver(recorder, process_sample=process_sample) + with pytest.raises(RuntimeError, match="eye 0"): + _run(receiver, runtime, stream) + assert "device_sync" in recorder.kinds() + + +def test_process_stream_safe_logs_the_reraised_exception(monkeypatch, caplog): + recorder = _Recorder() + monkeypatch.setitem(sys.modules, "cupy", _fake_cupy(recorder)) + + def process_sample(*_): + raise RuntimeError("decode failed") + + receiver, runtime, stream = _receiver(recorder, process_sample=process_sample) + with ThreadPoolExecutor(max_workers=2) as sample_pool: + receiver._sample_pool = sample_pool + with caplog.at_level(logging.WARNING): + receiver._process_stream_safe(None, None, stream, runtime) + assert any( + "processing failed" in r.getMessage() and "decode failed" in r.getMessage() + for r in caplog.records + ) + receiver._ipc_publisher.publish.assert_not_called() + + +def test_success_publishes_exactly_the_generation_begin_write_returned(monkeypatch): + recorder = _Recorder() + monkeypatch.setitem(sys.modules, "cupy", _fake_cupy(recorder)) + receiver, runtime, stream = _receiver( + recorder, + process_sample=lambda *_: True, + generations={"head_left": 40, "head_right": 900}, + ) + runtime.write_index = 1 + _run(receiver, runtime, stream) + + assert receiver._ipc_publisher.begin_write.call_count == 2 + published = { + call.args[0]: call.kwargs + for call in receiver._ipc_publisher.publish.call_args_list + } + assert published["head_left"]["slot_generation"] == 41 + assert published["head_right"]["slot_generation"] == 901 + assert all(kw["slot"] == 1 for kw in published.values()) + assert receiver._ipc_publisher.publish.call_count == 2 + assert runtime.write_index == 2 + # A second frame on the same slot is a fresh attempt: exactly one more begin_write per eye. + runtime.write_index = 1 + _run(receiver, runtime, stream) + published = { + call.args[0]: call.kwargs + for call in receiver._ipc_publisher.publish.call_args_list[2:] + } + assert published["head_left"]["slot_generation"] == 42 + assert published["head_right"]["slot_generation"] == 902 + assert receiver._ipc_publisher.begin_write.call_count == 4 + + +def test_mono_stream_begins_one_write(monkeypatch): + recorder = _Recorder() + monkeypatch.setitem(sys.modules, "cupy", _fake_cupy(recorder)) + receiver, runtime, stream = _receiver( + recorder, process_sample=lambda *_: True, stereo=False + ) + _run(receiver, runtime, stream) + receiver._ipc_publisher.begin_write.assert_called_once_with("head_left", 0) + receiver._ipc_publisher.publish.assert_called_once() + + +def test_each_worker_waits_for_its_own_cuda_stream_after_its_sample(monkeypatch): + recorder = _Recorder() + monkeypatch.setitem(sys.modules, "cupy", _fake_cupy(recorder)) + barrier = threading.Barrier(2, timeout=5) + + def process_sample(_runtime, _stream, sample, _slot): + barrier.wait() # force the two eyes onto two different worker threads + recorder.add("process_end", sample.camera_index, threading.get_ident()) + return True + + receiver, runtime, stream = _receiver(recorder, process_sample=process_sample) + _run(receiver, runtime, stream) + + ends = [e for e in recorder.events if e[0] == "process_end"] + assert len({e[2] for e in ends}) == 2 + for _, _, thread in ends: + idx = recorder.events.index(next(e for e in ends if e[2] == thread)) + later = [ + e + for e in recorder.events[idx + 1 :] + if e[0] == "stream_sync" and e[1] == thread + ] + assert later, "worker returned without synchronizing its own stream" + + +@pytest.mark.parametrize("raises", [False, True]) +def test_worker_waits_for_its_stream_even_when_the_sample_fails_softly( + monkeypatch, raises +): + recorder = _Recorder() + monkeypatch.setitem(sys.modules, "cupy", _fake_cupy(recorder)) + + def process_sample(*_): + if raises: + raise RuntimeError("boom") + return False + + receiver, runtime, stream = _receiver( + recorder, process_sample=process_sample, stereo=False + ) + try: + _run(receiver, runtime, stream) + except RuntimeError: + pass + # A soft failure returns False after the work it launched; that work must still be waited on + # before anything is reported. (An exception path is covered by the device-wide drain.) + assert "device_sync" in recorder.kinds() + if not raises: + assert "stream_sync" in recorder.kinds() diff --git a/examples/camera_streamer/camera_receiver/tests/test_slot_marker_publisher.py b/examples/camera_streamer/camera_receiver/tests/test_slot_marker_publisher.py new file mode 100644 index 0000000000..67249ca717 --- /dev/null +++ b/examples/camera_streamer/camera_receiver/tests/test_slot_marker_publisher.py @@ -0,0 +1,231 @@ +# SPDX-FileCopyrightText: Copyright (c) 2026 NVIDIA CORPORATION & AFFILIATES. All rights reserved. +# SPDX-License-Identifier: Apache-2.0 +"""CudaIpcFramePublisher's slot write-generation markers with real CuPy buffers.""" + +import json +from pathlib import Path +import socket +import sys + +import pytest + +cp = pytest.importorskip("cupy", reason="CuPy is not installed") +try: + _GPU_COUNT = cp.cuda.runtime.getDeviceCount() +except Exception as error: # pragma: no cover - depends on the machine + pytest.skip(f"no usable CUDA device: {error}", allow_module_level=True) +if _GPU_COUNT < 1: + pytest.skip("no CUDA device", allow_module_level=True) + +sys.path.insert(0, str(Path(__file__).resolve().parents[2])) + +from cuda_ipc import CudaIpcFramePublisher # noqa: E402 +from ipc_protocol import SlotMarkers # noqa: E402 + +SLOT_COUNTS = {"left": 3, "right": 2} + + +def _register(publisher, counts=None): + for name, slots in (counts or SLOT_COUNTS).items(): + publisher.register_stream( + name, + 4, + 4, + "rgba8", + 0, + [cp.zeros((4, 4, 4), dtype=cp.uint8) for _ in range(slots)], + ) + + +@pytest.fixture +def socket_path(tmp_path): + return str(tmp_path / "ipc.sock") + + +@pytest.fixture +def publisher(socket_path): + pub = CudaIpcFramePublisher(socket_path=socket_path) + _register(pub) + pub.start() + yield pub + pub.stop() + + +class _Client: + def __init__(self, path): + self.sock = socket.socket(socket.AF_UNIX, socket.SOCK_STREAM) + self.sock.settimeout(5) + self.sock.connect(path) + self.buf = b"" + + def read(self): + while b"\n" not in self.buf: + chunk = self.sock.recv(65536) + assert chunk, "publisher closed the connection" + self.buf += chunk + line, self.buf = self.buf.split(b"\n", 1) + return json.loads(line) + + def subscribe(self): + hello = self.read() + self.sock.sendall(b'{"type":"subscribe","streams":[]}\n') + return hello, self.read() + + def close(self): + self.sock.close() + + +def _connect(path): + client = _Client(path) + try: + return client, *client.subscribe() + except BaseException: + client.close() + raise + + +def test_hello_lists_slot_write_generation(publisher, socket_path): + client, hello, _ = _connect(socket_path) + client.close() + assert "slot_write_generation" in hello["features"] + + +def test_subscribed_carries_an_attachable_descriptor_in_registration_order( + publisher, socket_path +): + client, _, subscribed = _connect(socket_path) + client.close() + info = subscribed["slot_markers"] + assert info["stream_indexes"] == {"left": 0, "right": 1} + reader = SlotMarkers.attach( + info["name"], info["size"], info["layout_version"], info["epoch"] + ) + try: + assert reader.stream_count == 2 + assert [reader.slot_count(0), reader.slot_count(1)] == [3, 2] + finally: + reader.close() + + +def test_begin_write_increases_per_stream_and_slot_without_publishing( + publisher, socket_path +): + client, _, subscribed = _connect(socket_path) + info = subscribed["slot_markers"] + reader = SlotMarkers.attach( + info["name"], info["size"], info["layout_version"], info["epoch"] + ) + try: + assert [publisher.begin_write("left", 0) for _ in range(3)] == [1, 2, 3] + assert publisher.begin_write("left", 1) == 1 + assert publisher.begin_write("right", 0) == 1 + assert reader.load(0, 0) == 3 + assert reader.load(0, 1) == 1 + assert reader.load(1, 0) == 1 + assert reader.load(1, 1) == 0 + client.sock.settimeout(0.5) + with pytest.raises(socket.timeout): + client.sock.recv(1) + finally: + reader.close() + client.close() + + +def test_failed_attempt_leaves_a_gap_the_next_publish_carries(publisher, socket_path): + client, _, subscribed = _connect(socket_path) + info = subscribed["slot_markers"] + reader = SlotMarkers.attach( + info["name"], info["size"], info["layout_version"], info["epoch"] + ) + try: + first = publisher.begin_write("left", 0) + publisher.publish("left", 0, first, 1, 10) + notice = client.read() + assert notice["slot_generation"] == first + assert reader.unchanged(0, 0, notice["slot_generation"]) + + publisher.begin_write("left", 0) # failed attempt, never published + assert not reader.unchanged(0, 0, notice["slot_generation"]) + + last = publisher.begin_write("left", 0) + assert last == first + 2 + publisher.publish("left", 0, last, 2, 20) + later = client.read() + assert later["slot_generation"] == last + assert reader.unchanged(0, 0, later["slot_generation"]) + assert not reader.unchanged(0, 0, notice["slot_generation"]) + finally: + reader.close() + client.close() + + +def test_begin_write_before_start_raises(socket_path): + pub = CudaIpcFramePublisher(socket_path=socket_path) + _register(pub) + with pytest.raises(RuntimeError, match="not started"): + pub.begin_write("left", 0) + + +def test_begin_write_after_stop_raises(socket_path): + pub = CudaIpcFramePublisher(socket_path=socket_path) + _register(pub) + pub.start() + pub.stop() + with pytest.raises(RuntimeError, match="not started"): + pub.begin_write("left", 0) + + +def test_begin_write_unknown_stream_raises(publisher): + with pytest.raises(ValueError): + publisher.begin_write("missing", 0) + + +def test_registering_a_stream_after_start_raises(publisher): + with pytest.raises(RuntimeError, match="before start"): + publisher.register_stream( + "late", 4, 4, "rgba8", 0, [cp.zeros((4, 4, 4), dtype=cp.uint8)] + ) + + +def test_restart_advertises_a_new_region_and_epoch(socket_path): + descriptors = [] + for _ in range(2): + pub = CudaIpcFramePublisher(socket_path=socket_path) + _register(pub) + pub.start() + client, _, subscribed = _connect(socket_path) + client.close() + descriptors.append(subscribed["slot_markers"]) + if len(descriptors) == 1: + pub.stop() + try: + old, new = descriptors + assert new["name"] != old["name"] + assert new["epoch"] != old["epoch"] + with pytest.raises(RuntimeError): + SlotMarkers.attach( + old["name"], old["size"], old["layout_version"], old["epoch"] + ) + with pytest.raises(RuntimeError): + SlotMarkers.attach( + new["name"], new["size"], new["layout_version"], old["epoch"] + ) + SlotMarkers.attach( + new["name"], new["size"], new["layout_version"], new["epoch"] + ).close() + finally: + pub.stop() + + +def test_stop_removes_the_region(publisher, socket_path): + client, _, subscribed = _connect(socket_path) + client.close() + info = subscribed["slot_markers"] + path = Path("/dev/shm") / info["name"].lstrip("/") + assert path.exists() + publisher.stop() + assert not path.exists() + with pytest.raises(RuntimeError): + SlotMarkers.attach( + info["name"], info["size"], info["layout_version"], info["epoch"] + ) diff --git a/examples/camera_streamer/cuda_ipc_consumer/README.md b/examples/camera_streamer/cuda_ipc_consumer/README.md index 9d79f5fffc..b165be6b34 100644 --- a/examples/camera_streamer/cuda_ipc_consumer/README.md +++ b/examples/camera_streamer/cuda_ipc_consumer/README.md @@ -26,7 +26,8 @@ cd ../cuda_ipc_consumer ``` Each directory has its own `.venv`; the consumer does not use the -`camera_receiver` Python environment. +`camera_receiver` Python environment. Both build the shared slot marker module +from [`ipc_protocol/`](../ipc_protocol/README.md). ## Run @@ -49,6 +50,12 @@ Subscribe to only a subset of streams: ./run.sh --streams head.left,head.right --scale 0.35 ``` +The consumer refuses a publisher that does not provide slot write generations. +It checks the slot's marker after each copy has finished and discards a picture +whose slot was rewritten meanwhile, counted as `discarded_frames` in the +one-second stats. Other applications reading the pixels must do the same through +`CudaIpcClient.slot_unchanged`. + For a headless smoke test: ```bash diff --git a/examples/camera_streamer/cuda_ipc_consumer/consumer.py b/examples/camera_streamer/cuda_ipc_consumer/consumer.py index 20fba5e73c..0a08bdcb64 100755 --- a/examples/camera_streamer/cuda_ipc_consumer/consumer.py +++ b/examples/camera_streamer/cuda_ipc_consumer/consumer.py @@ -13,12 +13,17 @@ import select import signal import socket +import sys import time from dataclasses import dataclass +from pathlib import Path from typing import Optional logger = logging.getLogger("isaaccapture.camera_streamer.consumer") +# ipc_protocol is a sibling of cuda_ipc_consumer; import it from the source tree without an install step. +_STREAMER_ROOT = str(Path(__file__).resolve().parents[1]) + @dataclass class IpcSlot: @@ -57,6 +62,8 @@ def __init__(self, socket_path: str, streams: Optional[list[str]] = None) -> Non self.slots: dict[tuple[str, int], IpcSlot] = {} self.stream_order: list[str] = [] self.stream_info: dict[str, dict] = {} + self.markers = None + self._marker_streams: dict[str, int] = {} def connect(self) -> dict: sock = socket.socket(socket.AF_UNIX, socket.SOCK_STREAM) @@ -65,6 +72,11 @@ def connect(self) -> dict: hello = self._read_json_blocking() if hello is None or hello.get("type") != "hello": raise RuntimeError(f"expected hello message, got {hello!r}") + if "slot_write_generation" not in (hello.get("features") or []): + raise RuntimeError( + "the publisher does not provide slot write generations, so a copied " + "picture cannot be validated; update camera_receiver" + ) self._send_json({"type": "subscribe", "streams": self.requested_streams}) subscribed = self._read_json_blocking() if subscribed is None: @@ -73,6 +85,7 @@ def connect(self) -> dict: raise RuntimeError(str(subscribed.get("error", "subscription failed"))) if subscribed.get("type") != "subscribed": raise RuntimeError(f"expected subscribed message, got {subscribed!r}") + self._open_markers(subscribed) self._open_streams(subscribed) sock.setblocking(False) return {"hello": hello, "subscribed": subscribed} @@ -90,6 +103,35 @@ def close(self) -> None: slot.owner.close() self.slots.clear() self.recv_buf.clear() + if self.markers is not None: + self.markers.close() + self.markers = None + + def slot_unchanged(self, stream: str, slot: int, generation: int) -> bool: + """Whether no write has begun on the slot since ``generation`` was announced. + + Accept a copied picture only if this is true after every GPU read of the slot has + completed; checking before the copy only saves work. + """ + return self.markers.unchanged(self._marker_streams[stream], slot, generation) + + def _open_markers(self, subscribed: dict) -> None: + info = subscribed.get("slot_markers") + if not isinstance(info, dict): + raise RuntimeError("the publisher did not offer slot write generations") + if _STREAMER_ROOT not in sys.path: + sys.path.append(_STREAMER_ROOT) + import ipc_protocol + + self.markers = ipc_protocol.SlotMarkers.attach( + str(info["name"]), + int(info["size"]), + int(info["layout_version"]), + int(info["epoch"]), + ) + self._marker_streams = { + str(name): int(index) for name, index in info["stream_indexes"].items() + } def read_messages(self, timeout_s: float = 0.05) -> Optional[list[dict]]: """Return all currently available messages, or None on socket EOF.""" @@ -500,13 +542,12 @@ def on_sigint(_signum, _frame): latest_cpu: dict[str, object] = {} latest_metadata_by_stream: dict[str, dict] = {} - latest_generation_by_slot: dict[tuple[str, int], int] = {} counts: dict[str, int] = dict.fromkeys(client.stream_order, 0) stats_interval = max(1, args.stats_every) last_report = time.monotonic() last_counts = dict(counts) frames_seen = 0 - overwritten = 0 + discarded = 0 csv_file = None csv_writer = None if args.latency_csv: @@ -528,12 +569,6 @@ def on_sigint(_signum, _frame): msg = _annotate_consumer_receive(msg) stream = str(msg["stream"]) slot_id = int(msg["slot"]) - generation = int(msg.get("slot_generation", 0)) - key = (stream, slot_id) - previous = latest_generation_by_slot.get(key) - if previous is not None and generation > previous + 1: - overwritten += generation - previous - 1 - latest_generation_by_slot[key] = generation counts[stream] = counts.get(stream, 0) + 1 frames_seen += 1 latest_msg_by_stream[stream] = msg @@ -555,11 +590,19 @@ def on_sigint(_signum, _frame): if slot is None: print(f"unknown frame slot: {stream}[{slot_id}]", flush=True) continue - updated_display = True if cv2 is not None: - latest_cpu[stream] = _to_bgr_cpu( - slot.array, client.stream_info.get(stream, {}) - ) + generation = int(msg.get("slot_generation", 0)) + if not client.slot_unchanged(stream, slot_id, generation): + discarded += 1 + continue + # The device-to-host copy has finished when this returns; a write that + # began meanwhile has changed the marker, and the copy is discarded. + image = _to_bgr_cpu(slot.array, client.stream_info.get(stream, {})) + if not client.slot_unchanged(stream, slot_id, generation): + discarded += 1 + continue + latest_cpu[stream] = image + updated_display = True if cv2 is None: for msg in sampled_messages: @@ -572,7 +615,11 @@ def on_sigint(_signum, _frame): metadata_text = _format_stream_metadata(msg.get("metadata")) mean_text = "" if args.sample_mean: + generation = int(msg.get("slot_generation", 0)) mean = float(cp.mean(slot.array).get()) + if not client.slot_unchanged(stream, slot_id, generation): + discarded += 1 + continue mean_text = f" mean={mean:.2f}" print( f"{stream}[{slot_id}] gen={msg.get('slot_generation')} " @@ -603,9 +650,9 @@ def on_sigint(_signum, _frame): prev = last_counts.get(name, 0) rates.append(f"{name}: {current - prev} fps") last_counts[name] = current - if overwritten: - rates.append(f"overwritten_slots={overwritten}") - overwritten = 0 + if discarded: + rates.append(f"discarded_frames={discarded}") + discarded = 0 metadata_text = _format_summary_metadata( _latest_metadata(latest_metadata_by_stream, client.stream_order) ) diff --git a/examples/camera_streamer/cuda_ipc_consumer/requirements.txt b/examples/camera_streamer/cuda_ipc_consumer/requirements.txt index 814bee05b9..0c195db77e 100644 --- a/examples/camera_streamer/cuda_ipc_consumer/requirements.txt +++ b/examples/camera_streamer/cuda_ipc_consumer/requirements.txt @@ -4,3 +4,5 @@ numpy>=1.26,<2 cupy-cuda12x>=13.0,<14 opencv-python>=4.9,<4.12 +pybind11>=2.12 +ninja>=1.11 diff --git a/examples/camera_streamer/cuda_ipc_consumer/setup.sh b/examples/camera_streamer/cuda_ipc_consumer/setup.sh index 82e16c5485..d2e14ff875 100755 --- a/examples/camera_streamer/cuda_ipc_consumer/setup.sh +++ b/examples/camera_streamer/cuda_ipc_consumer/setup.sh @@ -41,8 +41,11 @@ else "$PYTHON_EXE" -m pip check fi +echo "setup.sh: building slot marker module" +IPC_PROTOCOL_PYTHON="$PYTHON_EXE" "${HERE}/../ipc_protocol/build.sh" + echo "setup.sh: verifying imports" -"$PYTHON_EXE" - <<'PY' +IPC_PARENT="$(cd "${HERE}/.." && pwd)" "$PYTHON_EXE" - <<'PY' import cupy import cv2 import numpy @@ -50,6 +53,12 @@ import numpy print(f"numpy={numpy.__version__}") print(f"cupy={cupy.__version__}") print(f"opencv={cv2.__version__}") + +import os +import sys + +sys.path.append(os.environ["IPC_PARENT"]) +import ipc_protocol # noqa: E402,F401 PY echo diff --git a/examples/camera_streamer/cuda_ipc_consumer/tests/conftest.py b/examples/camera_streamer/cuda_ipc_consumer/tests/conftest.py new file mode 100644 index 0000000000..e9e346be09 --- /dev/null +++ b/examples/camera_streamer/cuda_ipc_consumer/tests/conftest.py @@ -0,0 +1,9 @@ +# SPDX-FileCopyrightText: Copyright (c) 2026 NVIDIA CORPORATION & AFFILIATES. All rights reserved. +# SPDX-License-Identifier: Apache-2.0 + +from pathlib import Path +import sys + +CONSUMER_ROOT = Path(__file__).resolve().parents[1] +sys.path.insert(0, str(CONSUMER_ROOT)) +sys.path.insert(0, str(CONSUMER_ROOT.parent)) diff --git a/examples/camera_streamer/cuda_ipc_consumer/tests/test_slot_validation.py b/examples/camera_streamer/cuda_ipc_consumer/tests/test_slot_validation.py new file mode 100644 index 0000000000..365698b528 --- /dev/null +++ b/examples/camera_streamer/cuda_ipc_consumer/tests/test_slot_validation.py @@ -0,0 +1,155 @@ +# SPDX-FileCopyrightText: Copyright (c) 2026 NVIDIA CORPORATION & AFFILIATES. All rights reserved. +# SPDX-License-Identifier: Apache-2.0 +"""CudaIpcClient's slot write-generation handshake against a fake publisher (no GPU).""" + +import json +import socket +import threading + +import pytest + +from consumer import CudaIpcClient +from ipc_protocol import SlotMarkers + +FEATURES = ["slot_generation", "slot_write_generation"] + + +class _FakePublisher: + def __init__(self, path, hello, subscribed): + self.server = socket.socket(socket.AF_UNIX, socket.SOCK_STREAM) + self.server.bind(path) + self.server.listen(1) + self.thread = threading.Thread( + target=self._serve, args=(hello, subscribed), daemon=True + ) + self.thread.start() + + def _serve(self, hello, subscribed): + conn, _ = self.server.accept() + with conn: + conn.sendall(json.dumps(hello).encode() + b"\n") + buf = b"" + while b"\n" not in buf: + chunk = conn.recv(4096) + if not chunk: + return + buf += chunk + if subscribed is not None: + conn.sendall(json.dumps(subscribed).encode() + b"\n") + conn.settimeout(2) + try: + conn.recv(1) + except OSError: + pass + + def close(self): + self.server.close() + self.thread.join(timeout=5) + + +@pytest.fixture +def markers(): + region = SlotMarkers.create("/consumer_test", [2, 1]) + yield region + region.close() + + +def _descriptor(region, streams=None): + return { + "name": region.name, + "size": region.size, + "layout_version": region.layout_version, + "epoch": region.epoch, + "stream_indexes": streams or {"left": 0, "right": 1}, + } + + +@pytest.fixture +def client_for(tmp_path, monkeypatch): + created = [] + + def make(hello, subscribed): + path = str(tmp_path / "pub.sock") + publisher = _FakePublisher(path, hello, subscribed) + client = CudaIpcClient(path) + monkeypatch.setattr(client, "_open_streams", lambda _subscribed: None) + created.append((publisher, client)) + return client + + yield make + for publisher, client in created: + client.close() + publisher.close() + + +def _hello(features=FEATURES): + return {"type": "hello", "version": 2, "features": features, "streams": []} + + +def test_refuses_a_hello_without_slot_write_generation(client_for, markers): + client = client_for( + _hello(["slot_generation"]), + {"type": "subscribed", "slot_markers": _descriptor(markers), "streams": []}, + ) + with pytest.raises(RuntimeError, match="slot write generations"): + client.connect() + assert client.markers is None + + +def test_refuses_a_subscribed_without_slot_markers(client_for): + client = client_for(_hello(), {"type": "subscribed", "streams": []}) + with pytest.raises(RuntimeError, match="slot write generations"): + client.connect() + assert client.markers is None + + +def test_refuses_a_subscribed_with_null_slot_markers(client_for): + client = client_for( + _hello(), {"type": "subscribed", "slot_markers": None, "streams": []} + ) + with pytest.raises(RuntimeError, match="slot write generations"): + client.connect() + + +def test_refuses_markers_of_a_stale_epoch(client_for, markers): + descriptor = _descriptor(markers) + descriptor["epoch"] ^= 1 + client = client_for( + _hello(), {"type": "subscribed", "slot_markers": descriptor, "streams": []} + ) + with pytest.raises(RuntimeError): + client.connect() + assert client.markers is None + + +def test_slot_unchanged_follows_the_shared_marker(client_for, markers): + client = client_for( + _hello(), + {"type": "subscribed", "slot_markers": _descriptor(markers), "streams": []}, + ) + client.connect() + generation = markers.begin_write(0, 1) + assert client.slot_unchanged("left", 1, generation) + markers.begin_write(0, 1) + assert not client.slot_unchanged("left", 1, generation) + # Streams map through stream_indexes, not by name order. + other = markers.begin_write(1, 0) + assert client.slot_unchanged("right", 0, other) + assert not client.slot_unchanged("right", 0, other - 1) + with pytest.raises(KeyError): + client.slot_unchanged("missing", 0, 0) + + +def test_close_closes_the_region(client_for, markers): + client = client_for( + _hello(), + {"type": "subscribed", "slot_markers": _descriptor(markers), "streams": []}, + ) + client.connect() + attached = client.markers + assert attached is not None + client.close() + assert client.markers is None + with pytest.raises(RuntimeError, match="closed"): + attached.load(0, 0) + client.close() # idempotent diff --git a/examples/camera_streamer/ipc_protocol/.gitignore b/examples/camera_streamer/ipc_protocol/.gitignore new file mode 100644 index 0000000000..2c1d2a737d --- /dev/null +++ b/examples/camera_streamer/ipc_protocol/.gitignore @@ -0,0 +1,3 @@ +build/ +_slot_markers*.so +__pycache__/ diff --git a/examples/camera_streamer/ipc_protocol/CMakeLists.txt b/examples/camera_streamer/ipc_protocol/CMakeLists.txt new file mode 100644 index 0000000000..f12a7c2d6a --- /dev/null +++ b/examples/camera_streamer/ipc_protocol/CMakeLists.txt @@ -0,0 +1,33 @@ +# SPDX-FileCopyrightText: Copyright (c) 2026 NVIDIA CORPORATION & AFFILIATES. All rights reserved. +# SPDX-License-Identifier: Apache-2.0 +# +# CPU-only slot marker module shared by camera_receiver and the CUDA IPC consumers. The .so lands next to +# __init__.py so the package imports without an install step. + +cmake_minimum_required(VERSION 3.20) +project(camera_ipc_protocol LANGUAGES CXX) + +set(CMAKE_CXX_STANDARD 17) +set(CMAKE_CXX_STANDARD_REQUIRED ON) +set(CMAKE_POSITION_INDEPENDENT_CODE ON) + +find_package(Python3 REQUIRED COMPONENTS Interpreter Development.Module) + +# pybind11 is pip-installed into the active Python environment. +execute_process( + COMMAND ${Python3_EXECUTABLE} -c "import pybind11; print(pybind11.get_cmake_dir())" + OUTPUT_VARIABLE pybind11_DIR + OUTPUT_STRIP_TRAILING_WHITESPACE + RESULT_VARIABLE _pybind11_rc +) +if(NOT _pybind11_rc EQUAL 0) + message(FATAL_ERROR "pybind11 not found. `uv pip install pybind11` into the active venv.") +endif() +find_package(pybind11 REQUIRED CONFIG) + +pybind11_add_module(_slot_markers MODULE slot_markers_bindings.cpp) +target_include_directories(_slot_markers PRIVATE ${CMAKE_CURRENT_SOURCE_DIR}/inc) +target_link_libraries(_slot_markers PRIVATE rt) +target_compile_options(_slot_markers PRIVATE -Wall -Wextra) + +set_target_properties(_slot_markers PROPERTIES LIBRARY_OUTPUT_DIRECTORY ${CMAKE_CURRENT_SOURCE_DIR}) diff --git a/examples/camera_streamer/ipc_protocol/README.md b/examples/camera_streamer/ipc_protocol/README.md new file mode 100644 index 0000000000..0bb8403118 --- /dev/null +++ b/examples/camera_streamer/ipc_protocol/README.md @@ -0,0 +1,90 @@ + + +# CUDA IPC slot write generations + +`camera_receiver` decodes frames into a ring of GPU slots and shares them with +same-host readers over CUDA IPC. It rewrites a slot `ring_depth` pictures after +announcing it and never waits for a reader, and the replacement notice only +arrives after the new write, so a reader cannot learn from the socket that its +copy overlapped a rewrite. This module adds one shared write-generation marker +per slot so the reader can find out after its copy has finished. + +| Role | Process | What it does | +| --- | --- | --- | +| Slot writer | `camera_receiver` | Advances a slot's marker, writes the slot, announces that generation. | +| Slot reader | `cuda_ipc_consumer`, `camera_livekit_bridge`, any application | Copies a notified slot into memory it owns, then checks the marker before using the copy. | + +## Protocol + +- The writer owns one POSIX shared-memory region (`slot_markers.hpp`, mode `0600`, + unpredictable name, fresh epoch per run) holding one 64-bit atomic per + stream and slot. `_slot_markers` is its Python binding; the header is the single + implementation Python and C++ share. +- The marker counts write attempts. The writer increments it, for every stream + the attempt writes, before launching the first GPU operation that may touch the + slot, and keeps the result. A failed attempt publishes nothing and the marker + is never restored, so earlier notices for that slot stay invalid. +- A frame notice's `slot_generation` is the marker value of its completed write. + Generations skip values when attempts fail, so a gap is not a lost picture; the + frame sequence counts those. +- `hello.features` lists `slot_write_generation`, and `subscribed.slot_markers` + carries the region's `name`, `size`, `layout_version`, `epoch` and + `stream_indexes`. A reader that needs intact pictures refuses a publisher + without the feature and maps the region only if its size, layout version and + epoch match. +- Reader: copy the notified slot into memory it owns, wait until every GPU read of + the slot has completed, load the marker, and keep the copy only if it equals the + notified generation. Loading it before the copy only saves work. A reader that + skips the check, or an older reader that ignores `slot_markers`, can still + receive a picture mixing two frames; it is outside this guarantee. + The egocap capture server's GMSL feed reader still decides with a ring-distance + heuristic and does not use the markers yet. + +## Ordering contract + +The writer's `begin_write` is a sequentially consistent `fetch_add` followed by a +sequentially consistent fence on a lock-free 64-bit atomic in shared memory, and +it runs on the CPU before the first CUDA call that can write the slot. The reader's +`load` is a sequentially consistent load after its stream has finished. The +writer announces a generation only after every worker has waited for its own GPU +stream; on failure it drains the device before the next attempt. + +If a write overlapped any part of a read, the write's launch preceded the end of +the read, and the increment preceded the launch, so the reader's load sees the +increment or a later one and the generation differs. A write that begins after +the reader's load cannot change a copy that already finished. The 64-bit counter +cannot repeat within a run, a new run has a new region and epoch, and unsupported +platforms refuse to initialise rather than fall back to non-atomic access. This +holds for a plain copy and for a kernel that reads the slot, provided each has +finished before the load. + +## Status: interim protection + +CUDA's memory model makes an unsynchronized read and write of the same bytes a +data race with undefined behavior, and CUDA documents no bound on the effect for +a copy or kernel whose source is modified concurrently. This design relies on +the race only changing the reader's private copy, which the marker check +discards. The tests exercise that and the check has never accepted a mismatched +picture in them, but it is not proven from the memory model. + +It is an interim measure: it makes every detected overlap visible and drops the +picture, and it narrows the window a reader can be hurt in, but it is not a +documented guarantee. The proper fix is for the writer to exclude overlapping +access, for example short reader reservations that the writer honours before +reusing a slot; that is planned as follow-up work and would replace the marker +check. Until then, treat a picture that passed the check as very likely intact, +not as proven intact. + +## Build + +```bash +./build.sh # needs a C++17 compiler, CMake and pybind11 +IPC_PROTOCOL_PYTHON=/path/to/python ./build.sh +``` + +`camera_receiver/setup.sh` and `cuda_ipc_consumer/setup.sh` run it with their own +environment. The module file name carries the interpreter's ABI tag, so each +interpreter builds in its own tree. diff --git a/examples/camera_streamer/ipc_protocol/__init__.py b/examples/camera_streamer/ipc_protocol/__init__.py new file mode 100644 index 0000000000..9d245600b3 --- /dev/null +++ b/examples/camera_streamer/ipc_protocol/__init__.py @@ -0,0 +1,27 @@ +# SPDX-FileCopyrightText: Copyright (c) 2026 NVIDIA CORPORATION & AFFILIATES. All rights reserved. +# SPDX-License-Identifier: Apache-2.0 +"""Write-attempt markers shared by camera_receiver and its CUDA IPC readers.""" + +from __future__ import annotations + +try: + from ._slot_markers import ( # type: ignore[import-not-found] + LAYOUT_VERSION, + MAX_SLOTS, + MAX_STREAMS, + REGION_SIZE, + SlotMarkers, + ) +except ImportError as e: + raise ImportError( + "camera_streamer slot marker module not built. Run " + "`ipc_protocol/build.sh` from the camera_streamer directory." + ) from e + +__all__ = [ + "LAYOUT_VERSION", + "MAX_SLOTS", + "MAX_STREAMS", + "REGION_SIZE", + "SlotMarkers", +] diff --git a/examples/camera_streamer/ipc_protocol/build.sh b/examples/camera_streamer/ipc_protocol/build.sh new file mode 100755 index 0000000000..824e1c4603 --- /dev/null +++ b/examples/camera_streamer/ipc_protocol/build.sh @@ -0,0 +1,37 @@ +#!/usr/bin/env bash +# SPDX-FileCopyrightText: Copyright (c) 2026 NVIDIA CORPORATION & AFFILIATES. All rights reserved. +# SPDX-License-Identifier: Apache-2.0 +# +# Builds the slot marker module. The .so lands next to __init__.py so the package imports straight from the source +# tree. Needs only a C++17 compiler and pybind11; no CUDA. +set -euo pipefail + +here="$(cd "$(dirname "$0")" && pwd)" +python_exe="${IPC_PROTOCOL_PYTHON:-${CAMERA_RECEIVER_PYTHON:-python3}}" + +if ! command -v "$python_exe" >/dev/null 2>&1 && [[ ! -x "$python_exe" ]]; then + echo "build.sh: no Python at $python_exe" >&2 + echo "build.sh: override with IPC_PROTOCOL_PYTHON=/path/to/python" >&2 + exit 1 +fi + +if ! "$python_exe" -c "import pybind11" 2>/dev/null; then + echo "build.sh: installing pybind11 into the Python environment..." >&2 + "$python_exe" -m pip install pybind11 +fi + +# The module's file name carries the interpreter's ABI tag, so each interpreter builds in its own tree. +build_dir="${here}/build/$("$python_exe" -c 'import sys; print(f"py{sys.version_info[0]}{sys.version_info[1]}")')" + +generator=() +if command -v ninja >/dev/null 2>&1; then + generator=(-G Ninja) +fi + +cmake -S "${here}" -B "${build_dir}" "${generator[@]}" \ + -DCMAKE_BUILD_TYPE=Release \ + -DPython3_EXECUTABLE="$(command -v "$python_exe")" +cmake --build "${build_dir}" --parallel + +echo +echo "build.sh: built → ${here}/_slot_markers*.so" diff --git a/examples/camera_streamer/ipc_protocol/inc/ipc_protocol/slot_markers.hpp b/examples/camera_streamer/ipc_protocol/inc/ipc_protocol/slot_markers.hpp new file mode 100644 index 0000000000..c1e73e5dee --- /dev/null +++ b/examples/camera_streamer/ipc_protocol/inc/ipc_protocol/slot_markers.hpp @@ -0,0 +1,321 @@ +// SPDX-FileCopyrightText: Copyright (c) 2026 NVIDIA CORPORATION & AFFILIATES. All rights reserved. +// SPDX-License-Identifier: Apache-2.0 +// +// Write-attempt markers for the CUDA IPC pixel slots that camera_receiver (the slot writer) shares with its readers. +// The writer advances a slot's marker before it touches the slot's pixels; a reader loads it again after its copy +// has finished and accepts the copy only if the marker still equals the generation the frame notice named. +// +// The operations are sequentially consistent process-shared atomics. Their ordering against GPU work is the caller's +// duty: advance the marker before launching the first write, and load it only after the GPU reads have completed. +#pragma once + +#include +#include + +#include +#include +#include +#include +#include +#include +#include +#include +#include +#include +#include +#include +#include +#include + +namespace camera_ipc +{ + +inline constexpr std::uint32_t kMarkerMagic = 0x314b4d53u; // "SMK1" +inline constexpr std::uint32_t kMarkerLayoutVersion = 1; +inline constexpr std::uint32_t kMaxStreams = 16; +inline constexpr std::uint32_t kMaxSlots = 32; +// A marker never wraps: a writer that reaches this restarts under a new region and epoch instead. +inline constexpr std::uint64_t kMaxGeneration = 1ull << 62; + +static_assert(std::atomic::is_always_lock_free, "slot markers need lock-free 64-bit atomics"); +static_assert(std::atomic::is_always_lock_free, "slot markers need lock-free 32-bit atomics"); + +struct alignas(64) MarkerCell +{ + std::atomic generation; +}; + +struct alignas(64) MarkerHeader +{ + std::uint32_t magic; + std::uint32_t layout_version; + std::uint64_t epoch; + std::uint32_t total_size; + std::uint32_t stream_count; + std::uint32_t slot_count[kMaxStreams]; + std::atomic ready; +}; + +struct MarkerRegion +{ + MarkerHeader header; + MarkerCell cells[kMaxStreams][kMaxSlots]; +}; + +class SlotMarkers +{ +public: + // Creates and initialises the region. The name is unique per call and the object is private to the user. + static SlotMarkers create(const std::string& name_prefix, const std::vector& slot_counts) + { + require_lock_free(); + if (slot_counts.empty() || slot_counts.size() > kMaxStreams) + { + throw std::invalid_argument("slot markers: stream count must be 1.." + std::to_string(kMaxStreams)); + } + for (std::uint32_t count : slot_counts) + { + if (count < 1 || count > kMaxSlots) + { + throw std::invalid_argument("slot markers: slots per stream must be 1.." + std::to_string(kMaxSlots)); + } + } + + std::random_device entropy; + const std::uint64_t epoch = random_u64(entropy); + char suffix[40]; + std::snprintf(suffix, sizeof(suffix), "_%d_%016llx", static_cast(::getpid()), + static_cast(random_u64(entropy))); + const std::string name = name_prefix + suffix; + + const int fd = ::shm_open(name.c_str(), O_CREAT | O_EXCL | O_RDWR, 0600); + if (fd < 0) + { + throw std::runtime_error("slot markers: shm_open(" + name + ") failed: " + std::strerror(errno)); + } + if (::fchmod(fd, 0600) != 0 || ::ftruncate(fd, sizeof(MarkerRegion)) != 0) + { + const std::string what = std::strerror(errno); + ::close(fd); + ::shm_unlink(name.c_str()); + throw std::runtime_error("slot markers: sizing " + name + " failed: " + what); + } + void* mapped = ::mmap(nullptr, sizeof(MarkerRegion), PROT_READ | PROT_WRITE, MAP_SHARED, fd, 0); + ::close(fd); + if (mapped == MAP_FAILED) + { + const std::string what = std::strerror(errno); + ::shm_unlink(name.c_str()); + throw std::runtime_error("slot markers: mmap(" + name + ") failed: " + what); + } + + // The mapping is zero-filled; construct the atomics in place and publish `ready` last. + auto* region = new (mapped) MarkerRegion(); + region->header.magic = kMarkerMagic; + region->header.layout_version = kMarkerLayoutVersion; + region->header.epoch = epoch; + region->header.total_size = static_cast(sizeof(MarkerRegion)); + region->header.stream_count = static_cast(slot_counts.size()); + for (std::size_t i = 0; i < slot_counts.size(); ++i) + { + region->header.slot_count[i] = slot_counts[i]; + } + region->header.ready.store(1); + return SlotMarkers(region, name, true); + } + + // Maps a region a writer advertised. The advertised size, layout version and epoch must all match the object. + static SlotMarkers attach(const std::string& name, std::uint64_t size, std::uint32_t layout_version, std::uint64_t epoch) + { + require_lock_free(); + if (layout_version != kMarkerLayoutVersion || size != sizeof(MarkerRegion)) + { + throw std::runtime_error("slot markers: unsupported layout (version " + std::to_string(layout_version) + + ", size " + std::to_string(size) + ")"); + } + const int fd = ::shm_open(name.c_str(), O_RDWR, 0); + if (fd < 0) + { + throw std::runtime_error("slot markers: shm_open(" + name + ") failed: " + std::strerror(errno)); + } + struct stat info + { + }; + if (::fstat(fd, &info) != 0 || static_cast(info.st_size) != size) + { + ::close(fd); + throw std::runtime_error("slot markers: " + name + " has the wrong size"); + } + void* mapped = ::mmap(nullptr, sizeof(MarkerRegion), PROT_READ | PROT_WRITE, MAP_SHARED, fd, 0); + ::close(fd); + if (mapped == MAP_FAILED) + { + throw std::runtime_error("slot markers: mmap(" + name + ") failed: " + std::strerror(errno)); + } + auto* region = static_cast(mapped); + const MarkerHeader& header = region->header; + bool sane = header.ready.load() == 1 && header.magic == kMarkerMagic && + header.layout_version == kMarkerLayoutVersion && header.epoch == epoch && + header.total_size == sizeof(MarkerRegion) && header.stream_count >= 1 && + header.stream_count <= kMaxStreams; + for (std::uint32_t i = 0; sane && i < header.stream_count; ++i) + { + sane = header.slot_count[i] >= 1 && header.slot_count[i] <= kMaxSlots; + } + if (!sane) + { + ::munmap(mapped, sizeof(MarkerRegion)); + throw std::runtime_error("slot markers: " + name + " is not the advertised region"); + } + return SlotMarkers(region, name, false); + } + + SlotMarkers(const SlotMarkers&) = delete; + SlotMarkers& operator=(const SlotMarkers&) = delete; + SlotMarkers(SlotMarkers&& other) noexcept + : region_(std::exchange(other.region_, nullptr)), name_(std::move(other.name_)), owner_(other.owner_) + { + } + SlotMarkers& operator=(SlotMarkers&& other) noexcept + { + if (this != &other) + { + close(); + region_ = std::exchange(other.region_, nullptr); + name_ = std::move(other.name_); + owner_ = other.owner_; + } + return *this; + } + ~SlotMarkers() + { + close(); + } + + // Unmaps the region; the creator also removes its name so no new reader can attach. + void close() noexcept + { + if (region_ == nullptr) + { + return; + } + ::munmap(region_, sizeof(MarkerRegion)); + region_ = nullptr; + if (owner_) + { + ::shm_unlink(name_.c_str()); + } + } + + const std::string& name() const + { + return name_; + } + static constexpr std::uint64_t region_size() + { + return sizeof(MarkerRegion); + } + std::uint64_t epoch() const + { + return region().header.epoch; + } + std::uint32_t layout_version() const + { + return region().header.layout_version; + } + std::uint32_t stream_count() const + { + return region().header.stream_count; + } + std::uint32_t slot_count(std::uint32_t stream) const + { + check_stream(stream); + return region().header.slot_count[stream]; + } + + // Writer: records a write attempt and returns its generation. Call before the first GPU operation that may touch + // the slot's pixels, and keep the result to publish if the attempt succeeds. Failed attempts are never undone. + std::uint64_t begin_write(std::uint32_t stream, std::uint32_t slot) + { + std::atomic& marker = cell_at(stream, slot).generation; + const std::uint64_t generation = marker.fetch_add(1) + 1; + if (generation >= kMaxGeneration) + { + throw std::runtime_error("slot markers: generation space exhausted; restart under a new region"); + } + // The increment is globally visible before any later launch, including device doorbell writes. + std::atomic_thread_fence(std::memory_order_seq_cst); + return generation; + } + + // Reader: the slot's current generation. Load it only after every GPU read of the slot has completed. + std::uint64_t load(std::uint32_t stream, std::uint32_t slot) const + { + return cell_at(stream, slot).generation.load(); + } + + // Reader: whether no write has begun since `generation` was announced. + bool unchanged(std::uint32_t stream, std::uint32_t slot, std::uint64_t generation) const + { + return load(stream, slot) == generation; + } + +private: + SlotMarkers(MarkerRegion* region, std::string name, bool owner) + : region_(region), name_(std::move(name)), owner_(owner) + { + } + + static void require_lock_free() + { + std::atomic probe64{ 0 }; + std::atomic probe32{ 0 }; + if (!probe64.is_lock_free() || !probe32.is_lock_free()) + { + throw std::runtime_error("slot markers: this platform has no lock-free process-shared atomics"); + } + } + + static std::uint64_t random_u64(std::random_device& entropy) + { + std::uint64_t value = 0; + while (value == 0) + { + value = (static_cast(entropy()) << 32) ^ entropy(); + } + return value; + } + + void check_stream(std::uint32_t stream) const + { + if (stream >= region().header.stream_count) + { + throw std::out_of_range("slot markers: stream index out of range"); + } + } + + MarkerCell& cell_at(std::uint32_t stream, std::uint32_t slot) const + { + check_stream(stream); + if (slot >= region().header.slot_count[stream]) + { + throw std::out_of_range("slot markers: slot index out of range"); + } + return region().cells[stream][slot]; + } + + MarkerRegion& region() const + { + if (region_ == nullptr) + { + throw std::runtime_error("slot markers: the region is closed"); + } + return *region_; + } + + MarkerRegion* region_; + std::string name_; + bool owner_; +}; + +} // namespace camera_ipc diff --git a/examples/camera_streamer/ipc_protocol/slot_markers_bindings.cpp b/examples/camera_streamer/ipc_protocol/slot_markers_bindings.cpp new file mode 100644 index 0000000000..a43d66b51e --- /dev/null +++ b/examples/camera_streamer/ipc_protocol/slot_markers_bindings.cpp @@ -0,0 +1,37 @@ +// SPDX-FileCopyrightText: Copyright (c) 2026 NVIDIA CORPORATION & AFFILIATES. All rights reserved. +// SPDX-License-Identifier: Apache-2.0 +// +// Thin Python binding over the slot markers. The operations live in the header, shared with the C++ readers. + +#include "ipc_protocol/slot_markers.hpp" + +#include +#include + +namespace py = pybind11; +using camera_ipc::SlotMarkers; + +PYBIND11_MODULE(_slot_markers, m) +{ + m.doc() = "Write-attempt markers for camera_receiver's CUDA IPC pixel slots"; + + m.attr("LAYOUT_VERSION") = camera_ipc::kMarkerLayoutVersion; + m.attr("REGION_SIZE") = SlotMarkers::region_size(); + m.attr("MAX_STREAMS") = camera_ipc::kMaxStreams; + m.attr("MAX_SLOTS") = camera_ipc::kMaxSlots; + + py::class_(m, "SlotMarkers") + .def_static("create", &SlotMarkers::create, py::arg("name_prefix"), py::arg("slot_counts")) + .def_static("attach", &SlotMarkers::attach, py::arg("name"), py::arg("size"), py::arg("layout_version"), + py::arg("epoch")) + .def("close", &SlotMarkers::close) + .def_property_readonly("name", &SlotMarkers::name) + .def_property_readonly("size", [](const SlotMarkers&) { return SlotMarkers::region_size(); }) + .def_property_readonly("epoch", &SlotMarkers::epoch) + .def_property_readonly("layout_version", &SlotMarkers::layout_version) + .def_property_readonly("stream_count", &SlotMarkers::stream_count) + .def("slot_count", &SlotMarkers::slot_count, py::arg("stream")) + .def("begin_write", &SlotMarkers::begin_write, py::arg("stream"), py::arg("slot")) + .def("load", &SlotMarkers::load, py::arg("stream"), py::arg("slot")) + .def("unchanged", &SlotMarkers::unchanged, py::arg("stream"), py::arg("slot"), py::arg("generation")); +} diff --git a/examples/camera_streamer/ipc_protocol/tests/conftest.py b/examples/camera_streamer/ipc_protocol/tests/conftest.py new file mode 100644 index 0000000000..5dbf7a9380 --- /dev/null +++ b/examples/camera_streamer/ipc_protocol/tests/conftest.py @@ -0,0 +1,8 @@ +# SPDX-FileCopyrightText: Copyright (c) 2026 NVIDIA CORPORATION & AFFILIATES. All rights reserved. +# SPDX-License-Identifier: Apache-2.0 + +from pathlib import Path +import sys + +STREAMER_ROOT = Path(__file__).resolve().parents[2] +sys.path.insert(0, str(STREAMER_ROOT)) diff --git a/examples/camera_streamer/ipc_protocol/tests/test_gpu_slot_integrity.py b/examples/camera_streamer/ipc_protocol/tests/test_gpu_slot_integrity.py new file mode 100644 index 0000000000..a5b3a5b1ff --- /dev/null +++ b/examples/camera_streamer/ipc_protocol/tests/test_gpu_slot_integrity.py @@ -0,0 +1,730 @@ +# SPDX-FileCopyrightText: Copyright (c) 2026 NVIDIA CORPORATION & AFFILIATES. All rights reserved. +# SPDX-License-Identifier: Apache-2.0 +"""GPU acceptance tests: an accepted picture always matches its notice's frame identity. + +The writer (``CudaIpcFramePublisher`` plus test kernels) runs in a spawned child process, because +CUDA IPC handles cannot be opened in the exporting process; the test process is the reader +(``CudaIpcClient``). Pixels are a pure function of the frame id, recomputed in numpy here, and +GPU gates (stream host functions) hold a reader's copy in flight while the writer overwrites a +slot. +""" + +from __future__ import annotations + +import collections +import faulthandler +import multiprocessing +import os +import queue +import random +import shutil +import statistics +import sys +import tempfile +import threading +import time +import traceback +from pathlib import Path + +import numpy as np +import pytest + +_HERE = Path(__file__).resolve() +_STREAMER_ROOT = _HERE.parents[2] +_REPO_ROOT = _HERE.parents[4] +for _p in ( + _STREAMER_ROOT, + _STREAMER_ROOT / "camera_receiver", + _STREAMER_ROOT / "cuda_ipc_consumer", +): + if str(_p) not in sys.path: + sys.path.insert(0, str(_p)) + +try: + import cupy as cp + + _GPU_REASON = ( + None if cp.cuda.runtime.getDeviceCount() > 0 else "no CUDA device present" + ) +except Exception as _exc: # noqa: BLE001 - any import/driver failure means skip + cp = None + _GPU_REASON = f"CuPy/CUDA unavailable: {_exc}" + +try: + import ipc_protocol # noqa: F401 + + _MARKER_REASON = None +except ImportError as _exc: + _MARKER_REASON = f"ipc_protocol not built for this interpreter: {_exc}" + +pytestmark = pytest.mark.skipif( + _GPU_REASON is not None or _MARKER_REASON is not None, + reason=_GPU_REASON or _MARKER_REASON or "", +) + +ROWS, COLS = 96, 128 # 128x64 luma rows + 32 chroma rows +BANDS = 4 +CMD_TIMEOUT_S = 90.0 +GATE_TIMEOUT_S = 10.0 + + +def expected_pixels(fid: int, rows: int = ROWS, cols: int = COLS) -> np.ndarray: + """Pixel pattern of frame ``fid``; every row of every plane carries the id.""" + r = np.arange(rows, dtype=np.int64)[:, None] + c = np.arange(cols, dtype=np.int64)[None, :] + return ((fid * 37 + (fid >> 8) * 11 + r * 5 + c) % 251).astype(np.uint8) + + +def expected_box(fid: int) -> np.ndarray: + """What the pair-averaging kernel reader produces for frame ``fid``.""" + v = expected_pixels(fid).astype(np.int32).reshape(ROWS, COLS // 2, 2) + avg = ((v[:, :, 0] + v[:, :, 1] + 1) >> 1).astype(np.uint8) + return np.repeat(avg, 2, axis=1) + + +def timestamp_for(seq: int) -> int: + return 1_000_000_000 + seq * 33_333_333 + + +# --------------------------------------------------------------------------- writer process + + +def _writer_main(cmd_q, rsp_q, cfg) -> None: + """Writer process: publisher plus test write kernels, driven by commands.""" + try: + import cupy as wcp + + from cuda_ipc import CudaIpcFramePublisher + + wcp.cuda.set_allocator( + None + ) # raw cudaMalloc so every slot is its own IPC allocation + write = wcp.ElementwiseKernel( + "int64 fid, int32 W", + "uint8 out", + "int r = i / W; int c = i % W;" + "out = (unsigned char)((fid * 37 + (fid >> 8) * 11 + (long long)r * 5 + c) % 251);", + "test_write_pattern", + ) + stream = wcp.cuda.Stream(non_blocking=True) + pub = CudaIpcFramePublisher(socket_path=cfg["socket"], queue_size=512) + bufs: dict[str, list] = {} + for name, rows, cols, ring in cfg["streams"]: + bufs[name] = [wcp.zeros((rows, cols), dtype=wcp.uint8) for _ in range(ring)] + pub.register_stream(name, cols, rows * 2 // 3, "nv12", 0, bufs[name]) + pub.start() + rsp_q.put(("ok", {"socket": cfg["socket"]})) + except BaseException: # noqa: BLE001 + rsp_q.put(("err", traceback.format_exc())) + return + + def write_slot(name, slot, fid, rows=None): + arr = bufs[name][slot] + view = arr if rows is None else arr[:rows] + with stream: + write(fid, arr.shape[1], view) + stream.synchronize() + + try: + while True: + cmd, args = cmd_q.get() + try: + if cmd == "stop": + break + if cmd == "write_many": + # items: (stream, slot, fid, rows_or_None, publish) + gens = [pub.begin_write(it[0], it[1]) for it in args["items"]] + for it in args["items"]: + write_slot(it[0], it[1], it[2], it[3]) + for it, g in zip(args["items"], gens): + if it[4]: + pub.publish(it[0], it[1], g, it[2], timestamp_for(it[2])) + rsp_q.put(("ok", gens)) + elif cmd == "burst": + name, ring = args["stream"], len(bufs[args["stream"]]) + t0 = time.perf_counter() + for fid in range(args["first"], args["first"] + args["n"]): + slot = fid % ring + g = pub.begin_write(name, slot) + write_slot(name, slot, fid) + pub.publish(name, slot, g, fid, timestamp_for(fid)) + rsp_q.put(("ok", {"elapsed_s": time.perf_counter() - t0})) + elif cmd == "bench": + name, ring = args["stream"], len(bufs[args["stream"]]) + lat = [] + t0 = time.perf_counter() + for fid in range(args["n"]): + t1 = time.perf_counter() + slot = fid % ring + g = pub.begin_write(name, slot) if args["begin"] else 0 + write_slot(name, slot, fid) + pub.publish(name, slot, g, fid, timestamp_for(fid)) + lat.append(time.perf_counter() - t1) + total = time.perf_counter() - t0 + lat.sort() + rsp_q.put( + ( + "ok", + { + "fps": args["n"] / total, + "mean_us": 1e6 * sum(lat) / len(lat), + "p50_us": 1e6 * lat[len(lat) // 2], + "p99_us": 1e6 * lat[int(len(lat) * 0.99)], + }, + ) + ) + else: + rsp_q.put(("err", f"unknown command {cmd}")) + except BaseException: # noqa: BLE001 + rsp_q.put(("err", traceback.format_exc())) + finally: + pub.stop() + + +class Writer: + """Parent-side handle on a writer child process.""" + + def __init__(self, streams, workdir: Path) -> None: + ctx = multiprocessing.get_context("spawn") + self.cmd_q = ctx.Queue() + self.rsp_q = ctx.Queue() + self.socket = str(Path(tempfile.mkdtemp(dir=workdir)) / "s.sock") + self.proc = ctx.Process( + target=_writer_main, + args=(self.cmd_q, self.rsp_q, {"socket": self.socket, "streams": streams}), + daemon=True, + ) + self.proc.start() + self.result("startup") + + def result(self, what: str, timeout: float = CMD_TIMEOUT_S): + deadline = time.monotonic() + timeout + while time.monotonic() < deadline: + try: + status, payload = self.rsp_q.get(timeout=0.25) + except queue.Empty: + if not self.proc.is_alive(): + raise RuntimeError(f"writer died during {what}") from None + continue + if status != "ok": + raise RuntimeError(f"writer failed during {what}:\n{payload}") + return payload + raise TimeoutError(f"writer timed out during {what}") + + def poll_result(self): + """Non-blocking: the pending response or None.""" + try: + status, payload = self.rsp_q.get_nowait() + except queue.Empty: + return None + if status != "ok": + raise RuntimeError(f"writer failed:\n{payload}") + return payload + + def send(self, cmd: str, **args) -> None: + self.cmd_q.put((cmd, args)) + + def call(self, cmd: str, **args): + self.send(cmd, **args) + return self.result(cmd) + + def write_many(self, *items): + return self.call("write_many", items=list(items)) + + def close(self) -> None: + try: + if self.proc.is_alive(): + self.cmd_q.put(("stop", {})) + self.proc.join(10) + finally: + if self.proc.is_alive(): + self.proc.terminate() + self.proc.join(5) + if self.proc.is_alive(): + self.proc.kill() + shutil.rmtree(Path(self.socket).parent, ignore_errors=True) + + +# --------------------------------------------------------------------------- reader side + + +class Reader: + """Test-process reader: a CudaIpcClient plus a notice buffer.""" + + def __init__(self, writer: Writer, streams=None) -> None: + from consumer import CudaIpcClient + + self.client = CudaIpcClient(writer.socket, streams) + self.client.connect() + self.notices: collections.deque = collections.deque() + self.stream = cp.cuda.Stream(non_blocking=True) + + def pump(self, timeout_s: float = 0.05) -> None: + msgs = self.client.read_messages(timeout_s) + assert msgs is not None, "publisher closed the socket" + self.notices.extend(m for m in msgs if m.get("type") == "frame") + + def next_notice(self, stream: str | None = None, timeout_s: float = 10.0) -> dict: + deadline = time.monotonic() + timeout_s + while time.monotonic() < deadline: + for i, n in enumerate(self.notices): + if stream is None or n["stream"] == stream: + del self.notices[i] + return n + self.pump(0.05) + raise TimeoutError("no frame notice arrived") + + def expect_no_notice(self, wait_s: float = 0.4) -> None: + end = time.monotonic() + wait_s + while time.monotonic() < end: + self.pump(0.05) + assert not self.notices, f"unexpected notices {list(self.notices)}" + + def array(self, notice: dict): + return self.client.slots[(notice["stream"], notice["slot"])].array + + def unchanged(self, notice: dict) -> bool: + return self.client.slot_unchanged( + notice["stream"], notice["slot"], notice["slot_generation"] + ) + + def copy_picture(self, notice: dict) -> np.ndarray: + """Copy into reader-owned memory on the reader stream and wait for all GPU work.""" + with self.stream: + dst = cp.empty_like(self.array(notice)) + dst[...] = self.array(notice) + self.stream.synchronize() + return cp.asnumpy(dst) + + def read_checked(self, notice: dict) -> tuple[bool, np.ndarray]: + pic = self.copy_picture(notice) + return self.unchanged(notice), pic + + def close(self) -> None: + self.client.close() + + +class Gate: + """Holds a CUDA stream behind a host function until the test opens it.""" + + def __init__(self) -> None: + self.reached = threading.Event() + self.opened = threading.Event() + self.after_ran = threading.Event() + + def _block(self, _arg) -> None: + self.reached.set() + self.opened.wait(GATE_TIMEOUT_S) + + def _after(self, _arg) -> None: + self.after_ran.set() + + def enqueue(self, stream) -> None: + stream.launch_host_func(self._block, None) + + def enqueue_probe(self, stream) -> None: + """Queue a flag behind everything already queued; it stays unset while closed.""" + stream.launch_host_func(self._after, None) + + def wait_reached(self) -> None: + assert self.reached.wait(GATE_TIMEOUT_S), "gate never reached" + + def assert_closed(self, stream) -> None: + time.sleep(0.15) + assert not self.after_ran.is_set(), "work behind a closed gate already ran" + assert not stream.done, "stream finished while its gate was closed" + + def open(self) -> None: + self.opened.set() + + +@pytest.fixture(autouse=True) +def _watchdog(): + faulthandler.dump_traceback_later(240, exit=True) + yield + faulthandler.cancel_dump_traceback_later() + + +@pytest.fixture +def workdir(): + root = _REPO_ROOT / "tmp" + root.mkdir(exist_ok=True) + path = Path(tempfile.mkdtemp(prefix="gpu_slot_", dir=root)) + yield path + shutil.rmtree(path, ignore_errors=True) + + +@pytest.fixture +def make_writer(workdir): + made: list = [] + + def factory(streams): + w = Writer(streams, workdir) + made.append(w) + return w + + yield factory + for w in made: + w.close() + + +@pytest.fixture +def make_reader(): + made: list = [] + + def factory(writer, streams=None): + r = Reader(writer, streams) + made.append(r) + return r + + yield factory + for r in made: + r.close() + + +# --------------------------------------------------------------------------- scenarios + + +def _check_identity(notice: dict, pic: np.ndarray) -> None: + assert notice["timestamp_ns"] == timestamp_for(notice["seq"]) + np.testing.assert_array_equal(pic, expected_pixels(notice["seq"])) + + +def test_baseline_no_overlap(make_writer, make_reader): + ring = 6 + w = make_writer([("cam", ROWS, COLS, ring)]) + r = make_reader(w) + accepted = 0 + for fid in range(1, 2 * ring + 1): # two laps, every slot rewritten + slot = fid % ring + w.write_many(("cam", slot, fid, None, True)) + n = r.next_notice("cam") + assert (n["seq"], n["slot"]) == (fid, slot) + ok, pic = r.read_checked(n) + assert ok + _check_identity(n, pic) + accepted += 1 + assert accepted == 2 * ring + + +def _gated_full_copy(r: Reader, w: Writer, notice, overwrite_fid, check=True): + """Copy ``notice``'s slot behind a gate; overwrite the slot (no notice) while it is held.""" + gate = Gate() + gate.enqueue(r.stream) + with r.stream: + dst = cp.empty_like(r.array(notice)) + dst[...] = r.array(notice) + gate.enqueue_probe(r.stream) + gate.wait_reached() + gate.assert_closed(r.stream) + if overwrite_fid is not None: + w.write_many(("cam", notice["slot"], overwrite_fid, None, False)) + gate.open() + r.stream.synchronize() + assert gate.after_ran.wait(GATE_TIMEOUT_S) + pic = cp.asnumpy(dst) + unchanged = r.unchanged(notice) + return (unchanged if check else True), pic + + +@pytest.mark.parametrize("check", [True, False], ids=["checked", "negative_control"]) +def test_overwrite_before_copy_completes(make_writer, make_reader, check): + w = make_writer([("cam", ROWS, COLS, 3)]) + r = make_reader(w) + # Control: same gated path with no overwrite is accepted and exact. + w.write_many(("cam", 0, 100, None, True)) + n0 = r.next_notice("cam") + accepted, pic = _gated_full_copy(r, w, n0, None) + assert accepted + _check_identity(n0, pic) + + w.write_many(("cam", 1, 200, None, True)) + n = r.next_notice("cam") + accepted, pic = _gated_full_copy(r, w, n, 201, check=check) + r.expect_no_notice() # B's notice is withheld + np.testing.assert_array_equal(pic, expected_pixels(201)) # the copy holds B + if check: + assert not accepted, "overwritten slot was accepted" + else: + # Negative control: with the marker check off the wrong picture is accepted. + assert accepted + assert not np.array_equal(pic, expected_pixels(n["seq"])) + + +def _banded_reader(r: Reader, w: Writer, notice, overwrite_fid, kernel: bool): + """Read the slot in BANDS row bands; overwrite it between band 2 and 3.""" + gate = Gate() + src = r.array(notice) + band = ROWS // BANDS + box = cp.ElementwiseKernel( + "raw uint8 x", + "uint8 y", + "y = (unsigned char)(((int)x[i] + (int)x[i ^ 1] + 1) >> 1);", + "test_box_pairs", + ) + with r.stream: + dst = cp.empty_like(src) + for b in range(BANDS): + if b == 2: + gate.enqueue(r.stream) + s, d = src[b * band : (b + 1) * band], dst[b * band : (b + 1) * band] + if kernel: + box(s, d) + else: + d[...] = s + gate.enqueue_probe(r.stream) + gate.wait_reached() + gate.assert_closed(r.stream) + if overwrite_fid is not None: + w.write_many(("cam", notice["slot"], overwrite_fid, None, False)) + gate.open() + r.stream.synchronize() + assert gate.after_ran.wait(GATE_TIMEOUT_S) + return cp.asnumpy(dst) + + +@pytest.mark.parametrize("kernel", [False, True], ids=["copy", "box_kernel"]) +@pytest.mark.parametrize("check", [True, False], ids=["checked", "negative_control"]) +def test_genuine_overlap_mixes_frames(make_writer, make_reader, kernel, check): + ref = expected_box if kernel else expected_pixels + w = make_writer([("cam", ROWS, COLS, 3)]) + r = make_reader(w) + # Control: kernel/copy path without overlap is exact (validates expected values). + w.write_many(("cam", 0, 10, None, True)) + n0 = r.next_notice("cam") + pic0 = _banded_reader(r, w, n0, None, kernel) + assert r.unchanged(n0) + np.testing.assert_array_equal(pic0, ref(10)) + + w.write_many(("cam", 1, 20, None, True)) + n = r.next_notice("cam") + pic = _banded_reader(r, w, n, 21, kernel) + r.expect_no_notice() + band = ROWS // BANDS + from_a = [ + np.array_equal( + pic[b * band : (b + 1) * band], ref(20)[b * band : (b + 1) * band] + ) + for b in range(BANDS) + ] + from_b = [ + np.array_equal( + pic[b * band : (b + 1) * band], ref(21)[b * band : (b + 1) * band] + ) + for b in range(BANDS) + ] + print(f"\n[overlap kernel={kernel}] bands from A={from_a} from B={from_b}") + assert from_a == [True, True, False, False] + assert from_b == [False, False, True, True] # a real mixture of two frames + assert not np.array_equal(pic, ref(20)) and not np.array_equal(pic, ref(21)) + accepted = r.unchanged(n) if check else True + if check: + assert not accepted + else: + assert accepted # defect reproduced when the check is disabled + + +def test_single_stream_partial_failure_rejects_earlier_notice(make_writer, make_reader): + w = make_writer([("cam", ROWS, COLS, 3)]) + r = make_reader(w) + w.write_many(("cam", 2, 50, None, True)) + a = r.next_notice("cam") + gens = w.write_many( + ("cam", 2, 51, ROWS // 3, False) + ) # touches rows, never completes + assert gens[0] > a["slot_generation"] + r.expect_no_notice() + ok, pic = r.read_checked(a) + assert not ok + third = ROWS // 3 + assert np.array_equal( + pic[:third], expected_pixels(51)[:third] + ) # the slot really is torn + assert np.array_equal(pic[third:], expected_pixels(50)[third:]) + # A later completed write gets a fresh generation and is accepted; A stays rejected. + w.write_many(("cam", 2, 52, None, True)) + c = r.next_notice("cam") + ok, pic = r.read_checked(c) + assert ok + _check_identity(c, pic) + assert not r.unchanged(a) + assert c["slot_generation"] > gens[0] + + +def test_stereo_pair_one_eye_fails(make_writer, make_reader): + w = make_writer([("left", ROWS, COLS, 3), ("right", ROWS, COLS, 3)]) + r = make_reader(w) + w.write_many(("left", 0, 60, None, True), ("right", 0, 61, None, True)) + a_l, a_r = r.next_notice("left"), r.next_notice("right") + for n in (a_l, a_r): + ok, pic = r.read_checked(n) + assert ok + _check_identity(n, pic) + # One attempt writes both eyes into slot 0: left completes, right fails partway. + w.write_many(("left", 0, 70, None, True), ("right", 0, 71, ROWS // 2, False)) + b_l = r.next_notice("left") + r.expect_no_notice() # no notice for the failed eye + ok, pic = r.read_checked(b_l) + assert ok + _check_identity(b_l, pic) + for old in (a_l, a_r): + ok, _pic = r.read_checked(old) + assert not ok, f"earlier {old['stream']} notice accepted after the attempt" + + +def _process(r: Reader, n: dict, tally: dict) -> None: + pic = r.copy_picture(n) + if not r.unchanged(n): + tally["discarded"] += 1 + return + tally["accepted"] += 1 + tally["accepted_seqs"].append(n["seq"]) + assert n["slot"] == n["seq"] % 3 + assert n["timestamp_ns"] == timestamp_for(n["seq"]) + if not np.array_equal(pic, expected_pixels(n["seq"])): + tally["mismatch"] += 1 + + +def _tally() -> dict: + return dict(accepted=0, discarded=0, mismatch=0, dropped=0, accepted_seqs=[]) + + +def test_burst_with_stalled_reader(make_writer, make_reader): + w = make_writer([("cam", ROWS, COLS, 3)]) + r = make_reader(w) + n_frames = 240 + # Reader stalled (never reads the socket); writer is unpaced and must not wait. + t0 = time.monotonic() + res = w.call("burst", stream="cam", first=1, n=n_frames) + wall = time.monotonic() - t0 + print( + f"\n[burst] {n_frames} frames, writer {res['elapsed_s']:.3f}s " + f"({n_frames / res['elapsed_s']:.0f} fps) with a stalled reader, wall {wall:.2f}s" + ) + assert res["elapsed_s"] < 30.0 + time.sleep(0.5) # stall + tally = _tally() + seen = 0 + while seen < n_frames: + n = r.next_notice("cam") + seen += 1 + _process(r, n, tally) + print(f"[burst late drain] {tally}") + assert tally["mismatch"] == 0 + assert tally["accepted"] == 3 # only the latest picture of each slot survives + assert sorted(tally["accepted_seqs"]) == [n_frames - 2, n_frames - 1, n_frames] + assert tally["accepted"] + tally["discarded"] == n_frames + + +def test_burst_with_delayed_and_dropped_notices(make_writer, make_reader): + w = make_writer([("cam", ROWS, COLS, 3)]) + r = make_reader(w) + rng = random.Random(1234) + tally = _tally() + n_frames = 900 + w.send("burst", stream="cam", first=1, n=n_frames) + res = None + live = 0 + deadline = time.monotonic() + 60 + while res is None and time.monotonic() < deadline: + r.pump(0.01) + while r.notices and res is None: + n = r.notices.popleft() + live += 1 + roll = rng.random() + if roll < 0.3: + tally["dropped"] += 1 + elif roll < 0.5: + time.sleep(0.003) # delayed past further rewrites + _process(r, n, tally) + else: + _process(r, n, tally) + res = w.poll_result() + if res is None: + res = w.result("burst") + live_accepted = tally["accepted"] + time.sleep(0.5) # stall, then drain the rest late with no drops + while True: + r.pump(0.2) + if not r.notices: + break + while r.notices: + _process(r, r.notices.popleft(), tally) + print( + f"\n[delayed/dropped] writer {res['elapsed_s']:.3f}s; live={live} " + f"live_accepted={live_accepted} total={tally}" + ) + assert tally["mismatch"] == 0 + assert ( + tally["accepted"] > live_accepted + ) # final late drain accepts the newest pictures + assert res["elapsed_s"] < 60.0 + + +# --------------------------------------------------------------------------- measurements + +# Manual measurements, opt-in: SLOT_MARKER_MEASUREMENTS=1 pytest -s -k measure +_measure = pytest.mark.skipif( + os.environ.get("SLOT_MARKER_MEASUREMENTS") != "1", + reason="manual measurement; set SLOT_MARKER_MEASUREMENTS=1 to run", +) + + +@_measure +def test_measure_marker_call_cost(): + from ipc_protocol import SlotMarkers + + m = SlotMarkers.create("/slotit_bench", [1]) + try: + n = 1_000_000 + t = time.perf_counter_ns() + for _ in range(n): + m.begin_write(0, 0) + bw = (time.perf_counter_ns() - t) / n + t = time.perf_counter_ns() + for _ in range(n): + m.load(0, 0) + ld = (time.perf_counter_ns() - t) / n + t = time.perf_counter_ns() + for _ in range(n): + m.unchanged(0, 0, 1) + un = (time.perf_counter_ns() - t) / n + t = time.perf_counter_ns() + for _ in range(n): + pass + base = (time.perf_counter_ns() - t) / n + print( + f"\n[marker ns/call incl. python call overhead] begin_write={bw:.0f} " + f"load={ld:.0f} unchanged={un:.0f} empty-loop={base:.0f}" + ) + assert m.load(0, 0) == n + finally: + m.close() + + +@_measure +@pytest.mark.parametrize( + "rows,cols,n,label", + [(ROWS, COLS, 3000, "128x64 NV12"), (1984 * 3 // 2, 2560, 300, "2560x1984 NV12")], +) +def test_measure_writer_cost_with_and_without_begin_write( + make_writer, make_reader, rows, cols, n, label +): + w = make_writer([("cam", rows, cols, 3)]) + r = make_reader(w) # attached and stalled: never reads + w.call("bench", stream="cam", n=20, begin=True) # warm-up + out = {} + for rep in range(2): + for begin in (False, True): + out[(begin, rep)] = w.call("bench", stream="cam", n=n, begin=begin) + for (begin, rep), v in out.items(): + print( + f"\n[bench {label} begin_write={begin} rep={rep}] {v['fps']:.0f} fps " + f"mean={v['mean_us']:.1f}us p50={v['p50_us']:.1f}us p99={v['p99_us']:.1f}us" + ) + del r + mean_without = statistics.mean(v["mean_us"] for (b, _), v in out.items() if not b) + mean_with = statistics.mean(v["mean_us"] for (b, _), v in out.items() if b) + print( + f"[bench {label}] mean per-frame: without={mean_without:.1f}us with={mean_with:.1f}us" + ) diff --git a/examples/camera_streamer/ipc_protocol/tests/test_slot_markers.py b/examples/camera_streamer/ipc_protocol/tests/test_slot_markers.py new file mode 100644 index 0000000000..c8f2a9de67 --- /dev/null +++ b/examples/camera_streamer/ipc_protocol/tests/test_slot_markers.py @@ -0,0 +1,270 @@ +# SPDX-FileCopyrightText: Copyright (c) 2026 NVIDIA CORPORATION & AFFILIATES. All rights reserved. +# SPDX-License-Identifier: Apache-2.0 +"""Slot marker contract, exercised across real processes.""" + +import multiprocessing +import os +from pathlib import Path +import stat + +import pytest + +from ipc_protocol import ( + LAYOUT_VERSION, + MAX_SLOTS, + MAX_STREAMS, + REGION_SIZE, + SlotMarkers, +) + +SHM_DIR = Path("/dev/shm") + + +def _descriptor(markers): + return (markers.name, markers.size, markers.layout_version, markers.epoch) + + +def _increment_worker(descriptor, stream, slot, count, results): + markers = SlotMarkers.attach(*descriptor) + try: + results.put([markers.begin_write(stream, slot) for _ in range(count)]) + finally: + markers.close() + + +def _begin_once(descriptor, stream, slot, out): + markers = SlotMarkers.attach(*descriptor) + out.put(markers.begin_write(stream, slot)) + markers.close() + + +def _load_once(descriptor, stream, slot, out): + markers = SlotMarkers.attach(*descriptor) + out.put(markers.load(stream, slot)) + markers.close() + + +def _attach_outcome(descriptor, out): + try: + SlotMarkers.attach(*descriptor).close() + out.put("attached") + except RuntimeError as error: + out.put(f"refused: {error}") + + +@pytest.fixture +def ctx(): + return multiprocessing.get_context("spawn") + + +@pytest.fixture +def region(): + markers = SlotMarkers.create("/ipc_protocol_test", [3, 2]) + yield markers + markers.close() + + +def test_child_increment_is_observed_by_parent_and_vice_versa(ctx, region): + out = ctx.Queue() + child = ctx.Process(target=_begin_once, args=(_descriptor(region), 0, 1, out)) + child.start() + assert out.get(timeout=30) == 1 + child.join(timeout=30) + assert region.load(0, 1) == 1 + + assert region.begin_write(0, 1) == 2 + child = ctx.Process(target=_load_once, args=(_descriptor(region), 0, 1, out)) + child.start() + assert out.get(timeout=30) == 2 + child.join(timeout=30) + # Other slots and streams are untouched. + assert region.load(0, 0) == 0 + assert region.load(1, 1) == 0 + + +def test_concurrent_processes_get_unique_consecutive_generations(ctx, region): + processes, per_process = 6, 2000 + results = ctx.Queue() + workers = [ + ctx.Process( + target=_increment_worker, + args=(_descriptor(region), 1, 0, per_process, results), + ) + for _ in range(processes) + ] + for worker in workers: + worker.start() + batches = [results.get(timeout=120) for _ in workers] + for worker in workers: + worker.join(timeout=30) + assert worker.exitcode == 0 + returned = [value for batch in batches for value in batch] + assert len(returned) == processes * per_process + assert len(set(returned)) == len(returned) + assert sorted(returned) == list(range(1, processes * per_process + 1)) + for batch in batches: + assert batch == sorted(batch) + assert region.load(1, 0) == processes * per_process + + +def test_attach_accepts_the_advertised_region(region): + attached = SlotMarkers.attach(*_descriptor(region)) + try: + assert attached.stream_count == 2 + assert [attached.slot_count(0), attached.slot_count(1)] == [3, 2] + assert attached.epoch == region.epoch + assert attached.size == REGION_SIZE + assert attached.layout_version == LAYOUT_VERSION + finally: + attached.close() + + +@pytest.mark.parametrize( + "field, mutate", + [ + ("size", lambda d: (d[0], d[1] + 64, d[2], d[3])), + ("smaller size", lambda d: (d[0], d[1] - 64, d[2], d[3])), + ("layout_version", lambda d: (d[0], d[1], d[2] + 1, d[3])), + ("epoch", lambda d: (d[0], d[1], d[2], d[3] ^ 1)), + ("missing name", lambda d: (d[0] + "_absent", d[1], d[2], d[3])), + ], +) +def test_attach_refuses_mismatched_descriptor(region, field, mutate): + with pytest.raises(RuntimeError): + SlotMarkers.attach(*mutate(_descriptor(region))) + + +def test_attach_refuses_wrong_size_object_and_unready_header(): + name = f"ipc_protocol_test_raw_{os.getpid()}" + path = SHM_DIR / name + try: + # Right size but never initialised: the header was never marked ready. + path.write_bytes(b"\0" * REGION_SIZE) + with pytest.raises(RuntimeError, match="not the advertised region"): + SlotMarkers.attach("/" + name, REGION_SIZE, LAYOUT_VERSION, 1) + # Object whose size differs from the advertised one. + path.write_bytes(b"\0" * (REGION_SIZE // 2)) + with pytest.raises(RuntimeError, match="wrong size"): + SlotMarkers.attach("/" + name, REGION_SIZE, LAYOUT_VERSION, 1) + finally: + path.unlink(missing_ok=True) + + +def test_attach_in_a_fresh_process_reports_refusal(ctx, region): + out = ctx.Queue() + bad_epoch = _descriptor(region)[:3] + (region.epoch ^ 1,) + child = ctx.Process(target=_attach_outcome, args=(bad_epoch, out)) + child.start() + assert out.get(timeout=30).startswith("refused") + child.join(timeout=30) + + +@pytest.mark.parametrize("stream, slot", [(2, 0), (0, 3), (1, 2), (99, 0), (0, 99)]) +def test_out_of_range_indexes_raise(region, stream, slot): + with pytest.raises(IndexError): + region.begin_write(stream, slot) + with pytest.raises(IndexError): + region.load(stream, slot) + with pytest.raises(IndexError): + region.unchanged(stream, slot, 0) + # A refused write advanced nothing. + assert all( + region.load(s, k) == 0 for s in range(2) for k in range(region.slot_count(s)) + ) + + +def test_negative_indexes_are_refused(region): + with pytest.raises((IndexError, TypeError, OverflowError)): + region.begin_write(-1, 0) + with pytest.raises((IndexError, TypeError, OverflowError)): + region.begin_write(0, -1) + + +def test_slot_count_out_of_range_raises(region): + with pytest.raises(IndexError): + region.slot_count(2) + + +@pytest.mark.parametrize( + "counts", + [[], [0], [1, 0], [MAX_SLOTS + 1], [1] * (MAX_STREAMS + 1)], +) +def test_create_refuses_bad_stream_or_slot_counts(counts): + with pytest.raises(ValueError): + SlotMarkers.create("/ipc_protocol_test", counts) + + +def test_create_accepts_the_documented_limits(): + markers = SlotMarkers.create("/ipc_protocol_test", [MAX_SLOTS] * MAX_STREAMS) + try: + assert markers.begin_write(MAX_STREAMS - 1, MAX_SLOTS - 1) == 1 + finally: + markers.close() + + +def test_region_object_is_private_and_named_uniquely(): + first = SlotMarkers.create("/ipc_protocol_test", [1]) + second = SlotMarkers.create("/ipc_protocol_test", [1]) + try: + assert first.name != second.name + assert first.epoch != second.epoch + for markers in (first, second): + assert markers.name.startswith("/ipc_protocol_test_") + path = SHM_DIR / markers.name.lstrip("/") + assert stat.S_IMODE(path.stat().st_mode) == 0o600 + assert path.stat().st_size == REGION_SIZE + finally: + first.close() + second.close() + + +def test_creator_close_removes_the_name_and_is_idempotent(region): + descriptor = _descriptor(region) + reader = SlotMarkers.attach(*descriptor) + path = SHM_DIR / region.name.lstrip("/") + assert path.exists() + region.begin_write(0, 0) + region.close() + region.close() + assert not path.exists() + with pytest.raises(RuntimeError): + SlotMarkers.attach(*descriptor) + # An already attached reader keeps its mapping and its last view. + assert reader.load(0, 0) == 1 + reader.close() + reader.close() + + +def test_closed_region_raises_on_use(region): + reader = SlotMarkers.attach(*_descriptor(region)) + reader.close() + for call in ( + lambda: reader.begin_write(0, 0), + lambda: reader.load(0, 0), + lambda: reader.unchanged(0, 0, 0), + lambda: reader.epoch, + lambda: reader.stream_count, + lambda: reader.slot_count(0), + ): + with pytest.raises(RuntimeError, match="closed"): + call() + + +def test_reader_close_does_not_remove_the_name(region): + reader = SlotMarkers.attach(*_descriptor(region)) + reader.close() + again = SlotMarkers.attach(*_descriptor(region)) + again.close() + + +def test_unchanged_tracks_every_write_attempt(region): + generation = region.begin_write(1, 1) + assert region.unchanged(1, 1, generation) + region.begin_write(1, 1) + assert not region.unchanged(1, 1, generation) + + +def test_generation_exhaustion_limit_is_not_exposed(): + pytest.skip( + "kMaxGeneration (2**62) is not exposed by the module and cannot be reached by incrementing; not tested" + )