From ec188ab08a55f70513bcc0dbf504971ac3c2a684 Mon Sep 17 00:00:00 2001 From: Farbod Motlagh Date: Fri, 13 Nov 2026 16:52:38 -0800 Subject: [PATCH 1/2] feat(camera): add camera_endpoint, which serves a publisher to readers Endpoint puts a Publisher on a socket and speaks the camera_wire messages: it tells each reader what is published, and on a subscription sends the group's pool descriptors and from then on its frame events. One thread accepts readers and handles the handshake, subscriptions and releases. Frame events are not sent from it: they are encoded and sent on the publishing thread, inside Publisher::publish, with a send that does not block, so nothing sits between a frame set being published and its event being on the socket. A closed connection ends the reader's subscription and returns every frame set it held, whether the reader exited or was killed. A reader that breaks the protocol is dropped without affecting the others. Co-Authored-By: Claude Signed-off-by: Farbod Motlagh --- src/core/CMakeLists.txt | 1 + src/core/camera_endpoint/AGENTS.md | 15 + src/core/camera_endpoint/CMakeLists.txt | 6 + src/core/camera_endpoint/README.md | 49 +++ src/core/camera_endpoint/cpp/CMakeLists.txt | 27 ++ src/core/camera_endpoint/cpp/endpoint.cpp | 397 +++++++++++++++++ .../cpp/inc/camera_endpoint/endpoint.hpp | 65 +++ tests/cpp/core/CMakeLists.txt | 1 + tests/cpp/core/camera_endpoint/CMakeLists.txt | 22 + .../core/camera_endpoint/test_endpoint.cpp | 416 ++++++++++++++++++ 10 files changed, 999 insertions(+) create mode 100644 src/core/camera_endpoint/AGENTS.md create mode 100644 src/core/camera_endpoint/CMakeLists.txt create mode 100644 src/core/camera_endpoint/README.md create mode 100644 src/core/camera_endpoint/cpp/CMakeLists.txt create mode 100644 src/core/camera_endpoint/cpp/endpoint.cpp create mode 100644 src/core/camera_endpoint/cpp/inc/camera_endpoint/endpoint.hpp create mode 100644 tests/cpp/core/camera_endpoint/CMakeLists.txt create mode 100644 tests/cpp/core/camera_endpoint/test_endpoint.cpp diff --git a/src/core/CMakeLists.txt b/src/core/CMakeLists.txt index 7851685616..bafa5c8a6b 100644 --- a/src/core/CMakeLists.txt +++ b/src/core/CMakeLists.txt @@ -26,6 +26,7 @@ add_subdirectory(camera_core) if(CMAKE_SYSTEM_NAME STREQUAL "Linux") add_subdirectory(camera_ipc) add_subdirectory(camera_wire) + add_subdirectory(camera_endpoint) endif() # Build OXR library (depends on oxr_utils for types) diff --git a/src/core/camera_endpoint/AGENTS.md b/src/core/camera_endpoint/AGENTS.md new file mode 100644 index 0000000000..92ff196bc1 --- /dev/null +++ b/src/core/camera_endpoint/AGENTS.md @@ -0,0 +1,15 @@ + + +# Agent notes — `camera_endpoint` + +**CRITICAL (non-optional):** Before editing this package, complete the mandatory **`AGENTS.md` preflight** in [`../../../AGENTS.md`](../../../AGENTS.md) (read every applicable `AGENTS.md` on your paths, not just this file). + +Read [`README.md`](README.md) for what runs on which thread before changing it. + +- **Nothing sits between publish and the socket.** A frame event is encoded and sent inside `send_event`, on the publishing thread. Do not add a queue or a thread hop there, and do not log per frame. +- **`send_event` holds the publisher's lock.** It must not take another lock, block or call the publisher. That lock is also what serialises each connection's event encoder. +- **Unsubscribe before a connection is destroyed.** `Publisher::unsubscribe` returning is the guarantee that no `send_event` is running or will start for that sink. +- **A reader is untrusted.** Whatever it sends can at most get it dropped; it must not stop the thread or affect other readers. diff --git a/src/core/camera_endpoint/CMakeLists.txt b/src/core/camera_endpoint/CMakeLists.txt new file mode 100644 index 0000000000..8ce91de360 --- /dev/null +++ b/src/core/camera_endpoint/CMakeLists.txt @@ -0,0 +1,6 @@ +# SPDX-FileCopyrightText: Copyright (c) 2026 NVIDIA CORPORATION & AFFILIATES. All rights reserved. +# SPDX-License-Identifier: Apache-2.0 + +cmake_minimum_required(VERSION 3.20) + +add_subdirectory(cpp) diff --git a/src/core/camera_endpoint/README.md b/src/core/camera_endpoint/README.md new file mode 100644 index 0000000000..a32ab763c4 --- /dev/null +++ b/src/core/camera_endpoint/README.md @@ -0,0 +1,49 @@ + + +# Camera interface: the endpoint + +The camera plugin's side of the conversation with readers. It puts a +[`camera_core`](../camera_core) `Publisher` on a socket ([`camera_ipc`](../camera_ipc)) and +speaks the messages of [`camera_wire`](../camera_wire). + +```cpp +Publisher publisher; +const GroupId head = publisher.add_group(description); +HostPool left(slots, bytes, "head.left"), right(slots, bytes, "head.right"); + +Endpoint endpoint(publisher, socket_path); +endpoint.set_group_memory(head, { left.descriptor(), right.descriptor() }); +endpoint.start(); +// ... the backend acquires slots, writes pixels and publishes; readers come and go ... +``` + +## What runs where + +- **One thread of its own** accepts readers and handles what they send: the handshake, + subscriptions and releases. It sleeps in `poll` until a reader sends something. +- **Frame events are sent from the thread that publishes**, straight from + `Publisher::publish`, with a send that does not block. There is no queue and no hand-over + to another thread between a frame set being published and its event being on the socket. + The event that follows a release is sent from the endpoint's thread for the same reason. +- A reader's subscription takes effect before the answer to it is sent, so a `Frame` can + reach the reader ahead of `Subscribed`. + +## When a reader goes away + +A closed connection is the signal, whether the reader exited, crashed or was killed. Its +subscription ends and every frame set it held goes back to the pool. A reader that sends +bytes that are not a message, or a message only a plugin sends, is dropped the same way; +other readers are not affected. + +## Logging + +`isaaccapture.camera_endpoint.Endpoint` logs readers arriving, subscribing, being refused and +leaving. Nothing is logged per frame. + +## Tests + +`tests/cpp/core/camera_endpoint`, run with `ctest -L camera_endpoint`. They are tagged `unit` +and play the reader's part with the socket and the codec directly. diff --git a/src/core/camera_endpoint/cpp/CMakeLists.txt b/src/core/camera_endpoint/cpp/CMakeLists.txt new file mode 100644 index 0000000000..4bcdfb1e78 --- /dev/null +++ b/src/core/camera_endpoint/cpp/CMakeLists.txt @@ -0,0 +1,27 @@ +# SPDX-FileCopyrightText: Copyright (c) 2026 NVIDIA CORPORATION & AFFILIATES. All rights reserved. +# SPDX-License-Identifier: Apache-2.0 + +cmake_minimum_required(VERSION 3.20) + +find_package(Threads REQUIRED) + +# The plugin's side of the conversation with readers: serves a Publisher's groups over a socket. +add_library(camera_endpoint STATIC + endpoint.cpp +) + +target_include_directories(camera_endpoint INTERFACE + $ +) + +target_link_libraries(camera_endpoint + PUBLIC + camera::camera_core + PRIVATE + camera::camera_ipc + camera::camera_wire + log_bridge::log_bridge_core + Threads::Threads +) + +add_library(camera::camera_endpoint ALIAS camera_endpoint) diff --git a/src/core/camera_endpoint/cpp/endpoint.cpp b/src/core/camera_endpoint/cpp/endpoint.cpp new file mode 100644 index 0000000000..380265eff9 --- /dev/null +++ b/src/core/camera_endpoint/cpp/endpoint.cpp @@ -0,0 +1,397 @@ +// SPDX-FileCopyrightText: Copyright (c) 2026 NVIDIA CORPORATION & AFFILIATES. All rights reserved. +// SPDX-License-Identifier: Apache-2.0 + +#include "inc/camera_endpoint/endpoint.hpp" + +#include +#include +#include +#include +#include + +#include +#include +#include +#include +#include +#include +#include +#include +#include +#include +#include +#include +#include +#include +#include +#include +#include +#include +#include + +namespace core::camera +{ + +namespace +{ + +// One reader. As an EventSink it is called by the publisher, on whichever thread publishes or +// releases, with the publisher's lock held; everything else runs on the endpoint's thread. +class Connection final : public EventSink +{ +public: + explicit Connection(MessageSocket connected) : socket(std::move(connected)) + { + } + + bool send_event(SubscriptionId /*subscription*/, const FrameEvent& event) noexcept override + { + try + { + return socket.send(m_event_encoder.encode(event)) == SendStatus::SENT; + } + catch (const std::exception&) + { + return false; // the reader gets a later frame set, or its closed socket is noticed + } + } + + MessageSocket socket; + std::string name = "unnamed"; + bool greeted = false; + SubscriptionId subscription = 0; + +private: + WireEncoder m_event_encoder; // used inside send_event only, which the publisher's lock serialises +}; + +const char* name_of(DeliveryOrder order) +{ + switch (order) + { + case DeliveryOrder::NEWEST: + return "newest"; + case DeliveryOrder::IN_ORDER: + return "in order"; + default: + return "default order"; + } +} + +} // namespace + +class Endpoint::Impl +{ +public: + Impl(Publisher& publisher, const std::string& path) + : m_publisher(publisher), + m_listener(path), + m_wake(::eventfd(0, EFD_CLOEXEC | EFD_NONBLOCK)), + m_buffer(MAX_WIRE_MESSAGE_BYTES), + m_logger(isaaccapture::Logger::get("isaaccapture.camera_endpoint.Endpoint")) + { + if (!m_wake.valid()) + { + throw std::system_error(errno, std::generic_category(), "creating the camera endpoint's wake-up descriptor"); + } + } + + ~Impl() + { + stop(); + } + + void set_group_memory(GroupId group, std::vector descriptors) + { + if (m_thread.joinable()) + { + throw std::logic_error("a camera group's memory is named before the endpoint starts"); + } + const GroupDescription description = m_publisher.group_description(group); + if (descriptors.size() != description.streams.size()) + { + throw std::invalid_argument("camera group '" + description.id + "' needs one descriptor per stream"); + } + m_memory[group] = std::move(descriptors); + } + + void start() + { + if (m_thread.joinable()) + { + return; + } + m_stopping = false; + m_thread = std::thread([this] { run(); }); + m_logger->info("serving cameras on '{}'", m_listener.path()); + } + + void stop() + { + if (!m_thread.joinable()) + { + return; + } + m_stopping = true; + const std::uint64_t one = 1; + // Cannot fail in a way that matters: the counter only overflows after 2^64 wake-ups. + [[maybe_unused]] const ssize_t written = ::write(m_wake.get(), &one, sizeof(one)); + m_thread.join(); + } + + std::size_t reader_count() const + { + return m_reader_count.load(); + } + +private: + void run() + { + std::vector waits; + while (!m_stopping) + { + waits.assign({ { m_wake.get(), POLLIN, 0 }, { m_listener.descriptor(), POLLIN, 0 } }); + for (const auto& connection : m_connections) + { + waits.push_back({ connection->socket.descriptor(), POLLIN, 0 }); + } + if (::poll(waits.data(), waits.size(), -1) < 0) + { + if (errno == EINTR) + { + continue; + } + m_logger->error("camera endpoint stops serving: poll failed with errno {}", errno); + break; + } + + // Back to front, so dropping a connection leaves the indices still to visit alone. + for (std::size_t i = m_connections.size(); i-- > 0;) + { + if (waits[i + 2].revents != 0 && !serve(*m_connections[i])) + { + drop(i); + } + } + if ((waits[1].revents & POLLIN) != 0) + { + accept_readers(); + } + } + while (!m_connections.empty()) + { + drop(m_connections.size() - 1); + } + // Empty the wake-up counter, so that serving can start again. + std::uint64_t wakes = 0; + [[maybe_unused]] const ssize_t drained = ::read(m_wake.get(), &wakes, sizeof(wakes)); + } + + void accept_readers() + { + try + { + while (auto socket = m_listener.accept(std::chrono::milliseconds(0))) + { + m_connections.push_back(std::make_unique(std::move(*socket))); + m_reader_count = m_connections.size(); + } + } + catch (const std::exception& error) + { + m_logger->warn("could not accept a camera reader: {}", error.what()); + } + } + + // Ends the reader's subscription before its sink goes away. unsubscribe() returns only once + // no send_event is running or can start for it. + void drop(std::size_t index) + { + Connection& connection = *m_connections[index]; + if (connection.subscription != 0) + { + m_publisher.unsubscribe(connection.subscription); + } + m_logger->info("camera reader '{}' is gone", connection.name); + m_connections.erase(m_connections.begin() + static_cast(index)); + m_reader_count = m_connections.size(); + } + + // Handles everything the reader has sent. Returns false when the connection is to be dropped. + bool serve(Connection& connection) + { + try + { + for (;;) + { + const ReceivedMessage received = connection.socket.receive(m_buffer, std::chrono::milliseconds(0)); + if (received.status == ReceiveStatus::TIMEOUT) + { + return true; + } + if (received.status == ReceiveStatus::CLOSED) + { + return false; + } + const WireMessage message = decode_wire_message({ m_buffer.data(), received.bytes }); + if (!handle(connection, message)) + { + return false; + } + } + } + catch (const std::exception& error) + { + m_logger->warn("dropping camera reader '{}': {}", connection.name, error.what()); + return false; + } + } + + bool handle(Connection& connection, const WireMessage& message) + { + if (const auto* hello = std::get_if(&message)) + { + return greet(connection, *hello); + } + if (const auto* subscribe = std::get_if(&message)) + { + if (!connection.greeted) + { + m_logger->warn("dropping a camera reader that subscribed before it said hello"); + return false; + } + return answer(connection, *subscribe); + } + if (const auto* release = std::get_if(&message)) + { + if (connection.subscription != 0) + { + m_publisher.release(connection.subscription, release->lease_id); + } + return true; + } + if (std::holds_alternative(message)) + { + return true; // from a newer reader; not for this build + } + m_logger->warn("dropping camera reader '{}': it sent a message only a plugin sends", connection.name); + return false; + } + + bool greet(Connection& connection, const HelloMessage& hello) + { + connection.name = hello.reader_name.empty() ? "unnamed" : hello.reader_name; + WelcomeMessage welcome; + if (hello.protocol_version != WIRE_PROTOCOL_VERSION) + { + welcome.error = "this camera plugin speaks protocol version " + std::to_string(WIRE_PROTOCOL_VERSION) + + " and the reader version " + std::to_string(hello.protocol_version); + m_logger->warn("refusing camera reader '{}': {}", connection.name, welcome.error); + (void)send(connection, m_encoder.encode(welcome)); + return false; + } + const std::size_t group_count = m_publisher.group_count(); + for (std::size_t i = 0; i < group_count; ++i) + { + welcome.groups.push_back(m_publisher.group_description(static_cast(i))); + } + connection.greeted = true; + m_logger->info("camera reader '{}' connected", connection.name); + return send(connection, m_encoder.encode(welcome)); + } + + bool answer(Connection& connection, const SubscribeMessage& subscribe) + { + SubscribedMessage reply; + std::span descriptors; + const std::optional group = m_publisher.find_group(subscribe.group); + if (connection.subscription != 0) + { + reply.error = "a connection carries one subscription; open another connection for a second group"; + } + else if (!group) + { + reply.error = "the camera plugin publishes no group '" + subscribe.group + "'"; + } + else if (!m_memory.contains(*group)) + { + reply.error = "camera group '" + subscribe.group + "' has no memory a reader can map"; + } + else + { + // From here on the publisher may send this reader frame events at any moment, so a + // Frame can reach it before the Subscribed below. + const SubscribeResult result = m_publisher.subscribe(connection, *group, subscribe.options); + if (result) + { + connection.subscription = result.id; + reply.group = m_publisher.group_description(*group); + descriptors = m_memory.at(*group); + } + else + { + reply.error = result.error; + } + } + + if (reply.error.empty()) + { + m_logger->info("camera reader '{}' subscribed to '{}' (window {}, {})", connection.name, subscribe.group, + subscribe.options.window, name_of(subscribe.options.order)); + } + else + { + m_logger->warn("refusing camera reader '{}': {}", connection.name, reply.error); + } + return send(connection, m_encoder.encode(reply), descriptors); + } + + static bool send(Connection& connection, std::span bytes, std::span descriptors = {}) + { + return connection.socket.send(bytes, descriptors) == SendStatus::SENT; + } + + Publisher& m_publisher; + MessageListener m_listener; + UniqueFd m_wake; + std::map> m_memory; + + std::thread m_thread; + std::atomic m_stopping{ false }; + std::atomic m_reader_count{ 0 }; + + // The endpoint's thread only. + std::vector> m_connections; + std::vector m_buffer; + WireEncoder m_encoder; + + std::shared_ptr m_logger; +}; + +Endpoint::Endpoint(Publisher& publisher, const std::string& path) : m_impl(std::make_unique(publisher, path)) +{ +} + +Endpoint::~Endpoint() = default; + +void Endpoint::set_group_memory(GroupId group, std::vector descriptors) +{ + m_impl->set_group_memory(group, std::move(descriptors)); +} + +void Endpoint::start() +{ + m_impl->start(); +} + +void Endpoint::stop() +{ + m_impl->stop(); +} + +std::size_t Endpoint::reader_count() const +{ + return m_impl->reader_count(); +} + +} // namespace core::camera diff --git a/src/core/camera_endpoint/cpp/inc/camera_endpoint/endpoint.hpp b/src/core/camera_endpoint/cpp/inc/camera_endpoint/endpoint.hpp new file mode 100644 index 0000000000..3d68fa052f --- /dev/null +++ b/src/core/camera_endpoint/cpp/inc/camera_endpoint/endpoint.hpp @@ -0,0 +1,65 @@ +// SPDX-FileCopyrightText: Copyright (c) 2026 NVIDIA CORPORATION & AFFILIATES. All rights reserved. +// SPDX-License-Identifier: Apache-2.0 + +#pragma once + +#include + +#include +#include +#include +#include + +namespace core::camera +{ + +/** + * @brief Serves a Publisher's groups to readers in other processes. + * + * Listens on a socket file. Each reader is told what is published; when it subscribes it is + * sent the group's pool descriptors and from then on the group's frame events. A reader that + * goes away, cleanly or not, has every frame set it held taken back. + */ +class Endpoint +{ +public: + /** + * @brief Start listening on `path`. Readers are answered once start() has been called. + * @param publisher Must outlive the endpoint. + * @throws std::system_error if another process listens on the path or it cannot be bound. + */ + Endpoint(Publisher& publisher, const std::string& path); + + // Stops serving. + ~Endpoint(); + + Endpoint(const Endpoint&) = delete; + Endpoint& operator=(const Endpoint&) = delete; + + /** + * @brief Name what a reader maps for a group: one descriptor per stream, in stream order, + * for the stream's pool. The endpoint does not own them; they stay open while it serves. + * A group without them cannot be subscribed to. + * @throws std::logic_error after start(). + * @throws std::out_of_range for a group the publisher does not have. + * @throws std::invalid_argument if the count does not match the group's streams. + */ + void set_group_memory(GroupId group, std::vector descriptors); + + void start(); + + /** + * @brief Stop serving: every subscription ends and every reader sees its connection close. + * Does nothing if the endpoint is not serving. + */ + void stop(); + + // Readers connected right now. + std::size_t reader_count() const; + +private: + class Impl; + std::unique_ptr m_impl; +}; + +} // namespace core::camera diff --git a/tests/cpp/core/CMakeLists.txt b/tests/cpp/core/CMakeLists.txt index 35bbcad055..803dfcffbf 100644 --- a/tests/cpp/core/CMakeLists.txt +++ b/tests/cpp/core/CMakeLists.txt @@ -18,6 +18,7 @@ add_subdirectory(camera_core) if(CMAKE_SYSTEM_NAME STREQUAL "Linux") add_subdirectory(camera_ipc) add_subdirectory(camera_wire) + add_subdirectory(camera_endpoint) endif() if(BUILD_OVXR_CAMERA_QUADS) diff --git a/tests/cpp/core/camera_endpoint/CMakeLists.txt b/tests/cpp/core/camera_endpoint/CMakeLists.txt new file mode 100644 index 0000000000..5a8373c671 --- /dev/null +++ b/tests/cpp/core/camera_endpoint/CMakeLists.txt @@ -0,0 +1,22 @@ +# SPDX-FileCopyrightText: Copyright (c) 2026 NVIDIA CORPORATION & AFFILIATES. All rights reserved. +# SPDX-License-Identifier: Apache-2.0 + +cmake_minimum_required(VERSION 3.20) + +find_package(Threads REQUIRED) + +add_executable(camera_endpoint_tests + test_endpoint.cpp +) + +# The tests play the reader's part with the socket and the codec themselves. +target_link_libraries(camera_endpoint_tests PRIVATE + camera::camera_endpoint + camera::camera_ipc + camera::camera_wire + Catch2::Catch2WithMain + Threads::Threads +) + +message(STATUS "camera_endpoint_tests target enabled with Catch2") +catch_discover_tests(camera_endpoint_tests ADD_TAGS_AS_LABELS) diff --git a/tests/cpp/core/camera_endpoint/test_endpoint.cpp b/tests/cpp/core/camera_endpoint/test_endpoint.cpp new file mode 100644 index 0000000000..fb92b8611b --- /dev/null +++ b/tests/cpp/core/camera_endpoint/test_endpoint.cpp @@ -0,0 +1,416 @@ +// SPDX-FileCopyrightText: Copyright (c) 2026 NVIDIA CORPORATION & AFFILIATES. All rights reserved. +// SPDX-License-Identifier: Apache-2.0 + +#include +#include +#include +#include +#include +#include + +#include +#include +#include +#include +#include +#include +#include +#include +#include +#include +#include +#include +#include +#include +#include +#include +#include + +using namespace core::camera; +using namespace std::chrono_literals; +using Catch::Matchers::ContainsSubstring; + +namespace +{ + +constexpr std::uint32_t WIDTH = 64; +constexpr std::uint32_t HEIGHT = 48; +constexpr std::uint32_t SLOTS = 8; + +class TemporaryDirectory +{ +public: + TemporaryDirectory() + { + std::string pattern = (std::filesystem::temp_directory_path() / "camera_endpoint_XXXXXX").string(); + REQUIRE(::mkdtemp(pattern.data()) != nullptr); + m_path = pattern; + } + + ~TemporaryDirectory() + { + std::error_code ignored; + std::filesystem::remove_all(m_path, ignored); + } + + std::string socket_path() const + { + return (m_path / "cameras.sock").string(); + } + +private: + std::filesystem::path m_path; +}; + +GroupDescription gray_group(const std::string& id, std::size_t streams) +{ + GroupDescription group; + group.id = id; + for (std::size_t i = 0; i < streams; ++i) + { + StreamDescription stream; + stream.id = id + "/" + std::to_string(i); + stream.pixel_format = PixelFormat::GRAY8; + stream.width = WIDTH; + stream.height = HEIGHT; + stream.plane_count = 1; + stream.planes[0].stride_bytes = WIDTH; + stream.slot_bytes = WIDTH * HEIGHT; + stream.slot_count = SLOTS; + stream.frame_rate = 60.0; + group.streams.push_back(stream); + } + return group; +} + +// A plugin in miniature: a stereo group and a single camera, in host memory, behind an endpoint. +struct Served +{ + TemporaryDirectory directory; + Publisher publisher; + GroupId head = publisher.add_group(gray_group("head", 2)); + GroupId wrist = publisher.add_group(gray_group("wrist", 1)); + HostPool left{ SLOTS, WIDTH* HEIGHT, "test_left" }; + HostPool right{ SLOTS, WIDTH* HEIGHT, "test_right" }; + HostPool hand{ SLOTS, WIDTH* HEIGHT, "test_wrist" }; + Endpoint endpoint{ publisher, directory.socket_path() }; + + Served() + { + endpoint.set_group_memory(head, { left.descriptor(), right.descriptor() }); + endpoint.set_group_memory(wrist, { hand.descriptor() }); + endpoint.start(); + } + + // Publishes one stereo frame set whose every pixel is `value`. + std::uint64_t publish(std::uint8_t value) + { + std::vector images(2); + HostPool* pools[] = { &left, &right }; + for (std::size_t i = 0; i < 2; ++i) + { + const auto slot = publisher.acquire_slot(head, i); + REQUIRE(slot.has_value()); + std::fill(pools[i]->slot(*slot).begin(), pools[i]->slot(*slot).end(), std::byte{ value }); + images[i].slot = *slot; + } + return publisher.publish(head, images, {}); + } +}; + +// The reader's part, played with the socket and the codec directly. +struct Reader +{ + struct Received + { + ReceiveStatus status = ReceiveStatus::TIMEOUT; + WireMessage message; + std::vector descriptors; + }; + + explicit Reader(const Served& served) : socket(MessageSocket::connect(served.directory.socket_path())) + { + } + + template + void send(const Message& message) + { + REQUIRE(socket.send(encoder.encode(message)) == SendStatus::SENT); + } + + Received receive(std::chrono::milliseconds timeout = 2s) + { + Received result; + ReceivedMessage received = socket.receive(buffer, timeout); + result.status = received.status; + if (received.status == ReceiveStatus::MESSAGE) + { + result.message = decode_wire_message({ buffer.data(), received.bytes }); + result.descriptors = std::move(received.descriptors); + } + return result; + } + + template + Message expect(std::chrono::milliseconds timeout = 2s) + { + Received received = receive(timeout); + REQUIRE(received.status == ReceiveStatus::MESSAGE); + REQUIRE(std::holds_alternative(received.message)); + return std::get(std::move(received.message)); + } + + WelcomeMessage hello(const std::string& name = "test reader") + { + send(HelloMessage{ .reader_name = name }); + return expect(); + } + + // Subscribes and returns the answer with the pool descriptors that came with it. + std::pair> subscribe(const std::string& group, ReaderOptions options = {}) + { + send(SubscribeMessage{ group, options }); + Received received = receive(); + REQUIRE(received.status == ReceiveStatus::MESSAGE); + REQUIRE(std::holds_alternative(received.message)); + return { std::get(std::move(received.message)), std::move(received.descriptors) }; + } + + MessageSocket socket; + WireEncoder encoder; + std::vector buffer = std::vector(MAX_WIRE_MESSAGE_BYTES); +}; + +bool wait_until(const std::function& condition, std::chrono::milliseconds timeout = 2s) +{ + const auto deadline = std::chrono::steady_clock::now() + timeout; + while (!condition()) + { + if (std::chrono::steady_clock::now() > deadline) + { + return false; + } + std::this_thread::sleep_for(1ms); + } + return true; +} + +} // namespace + +TEST_CASE("a reader is told what is published", "[unit][camera_endpoint]") +{ + Served served; + Reader reader(served); + + const WelcomeMessage welcome = reader.hello(); + REQUIRE(welcome.error.empty()); + REQUIRE(welcome.protocol_version == WIRE_PROTOCOL_VERSION); + REQUIRE(welcome.groups.size() == 2); + REQUIRE(welcome.groups[0].id == "head"); + REQUIRE(welcome.groups[0].streams.size() == 2); + REQUIRE(welcome.groups[0].streams[1].id == "head/1"); + REQUIRE(welcome.groups[0].streams[1].width == WIDTH); + REQUIRE(welcome.groups[1].id == "wrist"); + REQUIRE(wait_until([&] { return served.endpoint.reader_count() == 1; })); +} + +TEST_CASE("a reader that speaks another protocol version is refused", "[unit][camera_endpoint]") +{ + Served served; + Reader reader(served); + + reader.send(HelloMessage{ .protocol_version = WIRE_PROTOCOL_VERSION + 1, .reader_name = "from the future" }); + const WelcomeMessage welcome = reader.expect(); + REQUIRE_THAT(welcome.error, ContainsSubstring("protocol version")); + REQUIRE(welcome.groups.empty()); + REQUIRE(reader.receive().status == ReceiveStatus::CLOSED); +} + +TEST_CASE("a subscriber maps the pools and is sent frame sets", "[unit][camera_endpoint]") +{ + Served served; + Reader reader(served); + reader.hello(); + + auto [subscribed, descriptors] = reader.subscribe("head"); + REQUIRE(subscribed.error.empty()); + REQUIRE(subscribed.group.id == "head"); + REQUIRE(descriptors.size() == 2); + const HostPoolView left(std::move(descriptors[0]), SLOTS, WIDTH * HEIGHT); + const HostPoolView right(std::move(descriptors[1]), SLOTS, WIDTH * HEIGHT); + + served.publish(0x11); + const FrameEvent first = reader.expect(); + REQUIRE(first.sequence == 1); + REQUIRE(first.image_count == 2); + REQUIRE(first.skipped == 0); + REQUIRE(first.timeline.published_ns != TIME_UNKNOWN); + REQUIRE(first.timeline.sent_ns >= first.timeline.published_ns); + REQUIRE(left.slot(first.images[0].slot).front() == std::byte{ 0x11 }); + REQUIRE(right.slot(first.images[1].slot).back() == std::byte{ 0x11 }); + + // A window of one holds one frame set; the next comes with the release, and is the newest. + served.publish(0x22); + served.publish(0x33); + REQUIRE(reader.receive(20ms).status == ReceiveStatus::TIMEOUT); + REQUIRE(left.slot(first.images[0].slot).front() == std::byte{ 0x11 }); // still held, so not rewritten + + reader.send(ReleaseMessage{ first.lease_id }); + const FrameEvent newest = reader.expect(); + REQUIRE(newest.sequence == 3); + REQUIRE(newest.skipped == 1); + REQUIRE(left.slot(newest.images[0].slot).front() == std::byte{ 0x33 }); +} + +TEST_CASE("a subscription that cannot be served is refused and the connection stays usable", "[unit][camera_endpoint]") +{ + Served served; + Reader reader(served); + reader.hello(); + + auto [unknown, no_descriptors] = reader.subscribe("chest"); + REQUIRE_THAT(unknown.error, ContainsSubstring("no group 'chest'")); + REQUIRE(no_descriptors.empty()); + + auto [too_large, none] = reader.subscribe("head", { .window = SLOTS }); + REQUIRE_THAT(too_large.error, ContainsSubstring("does not fit the pool")); + REQUIRE(none.empty()); + + auto [accepted, descriptors] = reader.subscribe("wrist"); + REQUIRE(accepted.error.empty()); + REQUIRE(descriptors.size() == 1); + + auto [second, extra] = reader.subscribe("head"); + REQUIRE_THAT(second.error, ContainsSubstring("one subscription")); + REQUIRE(extra.empty()); +} + +TEST_CASE("a reader that disappears returns what it held", "[unit][camera_endpoint]") +{ + Served served; + { + Reader reader(served); + reader.hello(); + auto [subscribed, descriptors] = reader.subscribe("head", { .window = 2, .order = DeliveryOrder::IN_ORDER }); + REQUIRE(subscribed.error.empty()); + served.publish(1); + served.publish(2); + REQUIRE(reader.expect().sequence == 1); + REQUIRE(reader.expect().sequence == 2); + REQUIRE(served.endpoint.reader_count() == 1); + // Gone without releasing either frame set. + } + REQUIRE(wait_until([&] { return served.endpoint.reader_count() == 0; })); + + // With the held slots back, capture runs through the whole pool again and again. + for (std::uint8_t i = 0; i < 3 * SLOTS; ++i) + { + served.publish(i); + } + REQUIRE(served.publisher.stats(served.head).no_free_slot == 0); + + // And the room in the pool is there for the next reader. + Reader next(served); + next.hello(); + auto [again, descriptors] = next.subscribe("head", { .window = 2, .order = DeliveryOrder::IN_ORDER }); + REQUIRE(again.error.empty()); +} + +TEST_CASE("a reader that breaks the protocol is dropped and the others are not", "[unit][camera_endpoint]") +{ + Served served; + Reader good(served); + good.hello(); + auto [subscribed, descriptors] = good.subscribe("head"); + REQUIRE(subscribed.error.empty()); + + Reader garbage(served); + const std::vector noise(32, std::byte{ 0x5a }); + REQUIRE(garbage.socket.send(noise) == SendStatus::SENT); + REQUIRE(garbage.receive().status == ReceiveStatus::CLOSED); + + Reader impostor(served); + impostor.hello(); + impostor.send(WelcomeMessage{}); + REQUIRE(impostor.receive().status == ReceiveStatus::CLOSED); + + Reader impatient(served); + impatient.send(SubscribeMessage{ "head", {} }); + REQUIRE(impatient.receive().status == ReceiveStatus::CLOSED); + + REQUIRE(wait_until([&] { return served.endpoint.reader_count() == 1; })); + served.publish(7); + REQUIRE(good.expect().sequence == 1); +} + +TEST_CASE("readers do not slow each other", "[unit][camera_endpoint]") +{ + Served served; + Reader stalled(served); + stalled.hello(); + REQUIRE(stalled.subscribe("head").first.error.empty()); + Reader live(served); + live.hello(); + REQUIRE(live.subscribe("head").first.error.empty()); + + // One reader never releases; the other still gets every frame set. + for (std::uint64_t sequence = 1; sequence <= 5; ++sequence) + { + REQUIRE(served.publish(static_cast(sequence)) == sequence); + const FrameEvent event = live.expect(); + REQUIRE(event.sequence == sequence); + REQUIRE(event.skipped == 0); + // Whether the release is seen before or after the next publish, that frame set is next. + live.send(ReleaseMessage{ event.lease_id }); + } + REQUIRE(stalled.expect().sequence == 1); + REQUIRE(stalled.receive(20ms).status == ReceiveStatus::TIMEOUT); +} + +TEST_CASE("stopping the endpoint closes every reader, and it can serve again", "[unit][camera_endpoint]") +{ + Served served; + Reader reader(served); + reader.hello(); + REQUIRE(reader.subscribe("head").first.error.empty()); + + served.endpoint.stop(); + REQUIRE(reader.receive().status == ReceiveStatus::CLOSED); + REQUIRE(served.endpoint.reader_count() == 0); + served.endpoint.stop(); // nothing to stop + + served.endpoint.start(); + Reader next(served); + REQUIRE(next.hello().groups.size() == 2); + REQUIRE(next.subscribe("head").first.error.empty()); + served.publish(9); + REQUIRE(next.expect().sequence == 1); +} + +TEST_CASE("a group needs its memory named before readers can subscribe", "[unit][camera_endpoint]") +{ + TemporaryDirectory directory; + Publisher publisher; + const GroupId head = publisher.add_group(gray_group("head", 2)); + HostPool pool(SLOTS, WIDTH * HEIGHT, "test"); + Endpoint endpoint(publisher, directory.socket_path()); + + REQUIRE_THROWS_AS(endpoint.set_group_memory(head, { pool.descriptor() }), std::invalid_argument); + REQUIRE_THROWS_AS(endpoint.set_group_memory(head + 1, {}), std::out_of_range); + endpoint.start(); + REQUIRE_THROWS_AS(endpoint.set_group_memory(head, { pool.descriptor(), pool.descriptor() }), std::logic_error); + + MessageSocket socket = MessageSocket::connect(directory.socket_path()); + WireEncoder encoder; + std::vector buffer(MAX_WIRE_MESSAGE_BYTES); + REQUIRE(socket.send(encoder.encode(HelloMessage{})) == SendStatus::SENT); + REQUIRE(socket.receive(buffer, 2s).status == ReceiveStatus::MESSAGE); + REQUIRE(socket.send(encoder.encode(SubscribeMessage{ "head", {} })) == SendStatus::SENT); + const ReceivedMessage received = socket.receive(buffer, 2s); + REQUIRE(received.status == ReceiveStatus::MESSAGE); + const WireMessage answer = decode_wire_message({ buffer.data(), received.bytes }); + REQUIRE_THAT(std::get(answer).error, ContainsSubstring("no memory a reader can map")); + + // Another endpoint cannot take the same path while this one lives. + REQUIRE_THROWS_AS(Endpoint(publisher, directory.socket_path()), std::system_error); +} From 8fb524a1e9b100bfe6c0b9894a61f09bad546e34 Mon Sep 17 00:00:00 2001 From: Farbod Motlagh Date: Fri, 13 Nov 2026 17:17:17 -0800 Subject: [PATCH 2/2] fix(camera): a stopped endpoint gives up its path stop() ended the endpoint's thread but kept the listening socket, so a reader that connected afterwards was accepted by the kernel and then waited for an answer nobody would send. stop() now closes the listener, which removes the socket file and releases the path: a reader that tries to connect is refused at once. start() takes the path again. Co-Authored-By: Claude Signed-off-by: Farbod Motlagh --- src/core/camera_endpoint/cpp/endpoint.cpp | 19 ++++++++++++++----- .../cpp/inc/camera_endpoint/endpoint.hpp | 9 +++++++-- .../core/camera_endpoint/test_endpoint.cpp | 3 +++ 3 files changed, 24 insertions(+), 7 deletions(-) diff --git a/src/core/camera_endpoint/cpp/endpoint.cpp b/src/core/camera_endpoint/cpp/endpoint.cpp index 380265eff9..652a06afaf 100644 --- a/src/core/camera_endpoint/cpp/endpoint.cpp +++ b/src/core/camera_endpoint/cpp/endpoint.cpp @@ -85,7 +85,8 @@ class Endpoint::Impl public: Impl(Publisher& publisher, const std::string& path) : m_publisher(publisher), - m_listener(path), + m_path(path), + m_listener(std::in_place, path), m_wake(::eventfd(0, EFD_CLOEXEC | EFD_NONBLOCK)), m_buffer(MAX_WIRE_MESSAGE_BYTES), m_logger(isaaccapture::Logger::get("isaaccapture.camera_endpoint.Endpoint")) @@ -121,9 +122,13 @@ class Endpoint::Impl { return; } + if (!m_listener) + { + m_listener.emplace(m_path); + } m_stopping = false; m_thread = std::thread([this] { run(); }); - m_logger->info("serving cameras on '{}'", m_listener.path()); + m_logger->info("serving cameras on '{}'", m_path); } void stop() @@ -137,6 +142,9 @@ class Endpoint::Impl // Cannot fail in a way that matters: the counter only overflows after 2^64 wake-ups. [[maybe_unused]] const ssize_t written = ::write(m_wake.get(), &one, sizeof(one)); m_thread.join(); + // Without the listener a reader that tries to connect is refused at once, instead of + // waiting in a queue nobody serves. + m_listener.reset(); } std::size_t reader_count() const @@ -150,7 +158,7 @@ class Endpoint::Impl std::vector waits; while (!m_stopping) { - waits.assign({ { m_wake.get(), POLLIN, 0 }, { m_listener.descriptor(), POLLIN, 0 } }); + waits.assign({ { m_wake.get(), POLLIN, 0 }, { m_listener->descriptor(), POLLIN, 0 } }); for (const auto& connection : m_connections) { waits.push_back({ connection->socket.descriptor(), POLLIN, 0 }); @@ -191,7 +199,7 @@ class Endpoint::Impl { try { - while (auto socket = m_listener.accept(std::chrono::milliseconds(0))) + while (auto socket = m_listener->accept(std::chrono::milliseconds(0))) { m_connections.push_back(std::make_unique(std::move(*socket))); m_reader_count = m_connections.size(); @@ -352,7 +360,8 @@ class Endpoint::Impl } Publisher& m_publisher; - MessageListener m_listener; + std::string m_path; + std::optional m_listener; // absent between stop() and the next start() UniqueFd m_wake; std::map> m_memory; diff --git a/src/core/camera_endpoint/cpp/inc/camera_endpoint/endpoint.hpp b/src/core/camera_endpoint/cpp/inc/camera_endpoint/endpoint.hpp index 3d68fa052f..7183340c5a 100644 --- a/src/core/camera_endpoint/cpp/inc/camera_endpoint/endpoint.hpp +++ b/src/core/camera_endpoint/cpp/inc/camera_endpoint/endpoint.hpp @@ -46,11 +46,16 @@ class Endpoint */ void set_group_memory(GroupId group, std::vector descriptors); + /** + * @brief Serve readers. After a stop() this takes the path again. + * @throws std::system_error if another process took the path meanwhile. + */ void start(); /** - * @brief Stop serving: every subscription ends and every reader sees its connection close. - * Does nothing if the endpoint is not serving. + * @brief Stop serving: every subscription ends, every reader sees its connection close, and + * the path is given up, so a reader that tries to connect is refused at once. Does nothing + * if the endpoint is not serving. */ void stop(); diff --git a/tests/cpp/core/camera_endpoint/test_endpoint.cpp b/tests/cpp/core/camera_endpoint/test_endpoint.cpp index fb92b8611b..d99eba0ad5 100644 --- a/tests/cpp/core/camera_endpoint/test_endpoint.cpp +++ b/tests/cpp/core/camera_endpoint/test_endpoint.cpp @@ -379,6 +379,9 @@ TEST_CASE("stopping the endpoint closes every reader, and it can serve again", " REQUIRE(served.endpoint.reader_count() == 0); served.endpoint.stop(); // nothing to stop + // A stopped endpoint refuses a reader at once; it does not leave it waiting for an answer. + REQUIRE_THROWS_AS(MessageSocket::connect(served.directory.socket_path()), std::system_error); + served.endpoint.start(); Reader next(served); REQUIRE(next.hello().groups.size() == 2);