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

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
1 change: 1 addition & 0 deletions src/core/camera_reader/AGENTS.md
Original file line number Diff line number Diff line change
Expand Up @@ -11,4 +11,5 @@ SPDX-License-Identifier: Apache-2.0
- **No copies and no conversions here.** A view is the plugin's buffer. Pixel conversion, if a consumer wants it, is a separate step on top.
- **A frame set outlives its reader safely.** Both share one state object; keep it that way rather than making `FrameSet` point back at the reader.
- **Releasing must never throw or block.** It runs in destructors, possibly on another thread; a plugin that is gone takes its frames back by itself.
- **Between `fork` and `exec`, system calls only.** The program that links the reader may have threads holding locks at that moment, so the launcher prepares everything before it forks. It also never touches the host's signal handlers, and starts the plugin detached so that nothing is left for the host to reap.
- **The plugin is trusted for content, not for bounds.** Check a frame event against the group before handing out views.
7 changes: 7 additions & 0 deletions src/core/camera_reader/README.md
Original file line number Diff line number Diff line change
Expand Up @@ -31,6 +31,13 @@ while (auto frames = reader.next(std::chrono::seconds(1)))
endpoint, the group does not exist, or the subscription does not fit the pool.
- **Which plugin.** By default the reader looks for this user's plugin on its default
endpoint. A `PluginLocation` names another instance of the plugin, or a socket path.
- **If no plugin is running, the reader starts one** and waits for it: the `camera_plugin`
next to the program, or on `PATH`, or the one named in `PluginLocation`. The plugin started
this way belongs to nobody, serves any other reader that comes along, and exits by itself
once no reader has been connected for a while (30 seconds unless told otherwise). When
several readers start one at the same moment, one plugin gets the endpoint and serves them
all. Set `start_if_absent` to false to be told instead; a plugin behind an explicit socket
path is never started.
- **One reader reads one group.** For two groups, open two readers; `descriptor()` lets an
application wait on several at once.
- A `FrameSet` may be given back from another thread than the one that calls `next`, and
Expand Down
2 changes: 2 additions & 0 deletions src/core/camera_reader/cpp/CMakeLists.txt
Original file line number Diff line number Diff line change
Expand Up @@ -6,6 +6,8 @@ cmake_minimum_required(VERSION 3.20)
# What an application links to read cameras from the camera plugin.
add_library(camera_reader STATIC
camera_reader.cpp
plugin_launcher.cpp
plugin_launcher.hpp
)

target_include_directories(camera_reader INTERFACE
Expand Down
144 changes: 116 additions & 28 deletions src/core/camera_reader/cpp/camera_reader.cpp
Original file line number Diff line number Diff line change
Expand Up @@ -3,6 +3,8 @@

#include "inc/camera_reader/camera_reader.hpp"

#include "plugin_launcher.hpp"

#include <camera_ipc/endpoint_path.hpp>
#include <camera_ipc/host_pool.hpp>
#include <camera_ipc/message_socket.hpp>
Expand All @@ -14,6 +16,7 @@
#include <deque>
#include <exception>
#include <mutex>
#include <poll.h>
#include <system_error>
#include <utility>
#include <variant>
Expand Down Expand Up @@ -55,30 +58,8 @@ std::optional<Received> receive(MessageSocket& socket, std::span<std::byte> buff
}
}

MessageSocket connect_to(const PluginLocation& plugin)
{
if (!plugin.endpoint.empty() && !plugin.instance.empty())
{
throw CameraReaderError("a camera plugin is named by its endpoint or by its instance, not both");
}
std::string endpoint = plugin.endpoint;
try
{
if (endpoint.empty())
{
endpoint = default_endpoint_path(plugin.instance);
}
return MessageSocket::connect(endpoint);
}
catch (const std::system_error& error)
{
throw CameraReaderError("no camera plugin answers on '" + endpoint + "': " + error.code().message());
}
catch (const std::invalid_argument& error)
{
throw CameraReaderError(error.what());
}
}
// How long a plugin that this reader started gets until it answers.
constexpr std::chrono::seconds START_TIMEOUT(20);

// Says hello and returns what the plugin publishes.
std::vector<GroupDescription> greet(MessageSocket& socket, WireEncoder& encoder, std::span<std::byte> buffer)
Expand Down Expand Up @@ -110,6 +91,114 @@ std::vector<GroupDescription> greet(MessageSocket& socket, WireEncoder& encoder,
}
}

// A connection that got through the handshake.
struct Greeted
{
MessageSocket socket;
std::vector<GroupDescription> groups;
};

// Whether the plugin behind `alive` is gone, waiting up to `wait` to find out.
bool plugin_is_gone(const UniqueFd& alive, std::chrono::milliseconds wait)
{
pollfd entry = { alive.get(), POLLIN, 0 };
return ::poll(&entry, 1, static_cast<int>(wait.count())) > 0;
}

// Starts a plugin for `endpoint` and connects to it once it serves.
Greeted start_and_connect(const PluginLocation& plugin,
const std::string& endpoint,
WireEncoder& encoder,
std::span<std::byte> buffer)
{
const std::string nobody = "no camera plugin answers on '" + endpoint + "'";
const std::string executable = find_plugin_executable(plugin.executable);
if (executable.empty())
{
throw CameraReaderError(
nobody + ", and there is no camera_plugin to start" +
(plugin.executable.empty() ? " next to this program or on PATH" : " at '" + plugin.executable + "'"));
}
std::vector<std::string> arguments = { "--exit-when-idle=" + std::to_string(plugin.exit_when_idle_seconds) };
if (!plugin.instance.empty())
{
arguments.push_back("--instance=" + plugin.instance);
}
UniqueFd alive;
try
{
alive = launch_plugin(executable, arguments);
}
catch (const std::system_error& error)
{
throw CameraReaderError(nobody + ", and '" + executable + "' could not be started: " + error.code().message());
}

// Another reader may have started a plugin at the same moment. Only one of the two plugins
// gets the endpoint, so this one being gone does not mean nobody serves: keep trying.
const auto deadline = std::chrono::steady_clock::now() + START_TIMEOUT;
std::string last_failure = "it did not start serving";
bool gone = false;
while (std::chrono::steady_clock::now() < deadline)
{
try
{
MessageSocket socket = MessageSocket::connect(endpoint);
std::vector<GroupDescription> groups = greet(socket, encoder, buffer);
return { std::move(socket), std::move(groups) };
}
catch (const CameraReaderError& error)
{
last_failure = error.what();
}
catch (const std::system_error&)
{
if (gone)
{
break; // the plugin ended and still nobody listens
}
}
gone = gone || plugin_is_gone(alive, std::chrono::milliseconds(20));
if (gone)
{
last_failure = "it stopped before it served; its log says why";
}
}
throw CameraReaderError(nobody + ". '" + executable + "' was started for it, but " + last_failure);
}

// Connects to the plugin, starting one first when that is wanted and needed, and says hello.
Greeted connect_to(const PluginLocation& plugin, WireEncoder& encoder, std::span<std::byte> buffer)
{
if (!plugin.endpoint.empty() && !plugin.instance.empty())
{
throw CameraReaderError("a camera plugin is named by its endpoint or by its instance, not both");
}
std::string endpoint = plugin.endpoint;
try
{
if (endpoint.empty())
{
endpoint = default_endpoint_path(plugin.instance);
}
MessageSocket socket = MessageSocket::connect(endpoint);
std::vector<GroupDescription> groups = greet(socket, encoder, buffer);
return { std::move(socket), std::move(groups) };
}
catch (const std::system_error& error)
{
if (plugin.endpoint.empty() && plugin.start_if_absent)
{
return start_and_connect(plugin, endpoint, encoder, buffer);
}
throw CameraReaderError("no camera plugin answers on '" + endpoint + "': " + error.code().message());
}
catch (const std::invalid_argument& error)
{
throw CameraReaderError(error.what());
}
}

} // namespace

namespace detail
Expand Down Expand Up @@ -262,17 +351,16 @@ void FrameSet::release() noexcept

std::vector<GroupDescription> CameraReader::list(const PluginLocation& plugin)
{
MessageSocket socket = connect_to(plugin);
WireEncoder encoder;
std::vector<std::byte> buffer(MAX_WIRE_MESSAGE_BYTES);
return greet(socket, encoder, buffer);
return connect_to(plugin, encoder, buffer).groups;
}

CameraReader CameraReader::open(const std::string& group, const ReaderOptions& options, const PluginLocation& plugin)
{
auto state = std::make_shared<detail::ReaderState>(connect_to(plugin));
WireEncoder encoder;
greet(state->socket, encoder, state->buffer);
std::vector<std::byte> handshake_buffer(MAX_WIRE_MESSAGE_BYTES);
auto state = std::make_shared<detail::ReaderState>(connect_to(plugin, encoder, handshake_buffer).socket);

if (state->socket.send(encoder.encode(SubscribeMessage{ group, options })) != SendStatus::SENT)
{
Expand Down
21 changes: 17 additions & 4 deletions src/core/camera_reader/cpp/inc/camera_reader/camera_reader.hpp
Original file line number Diff line number Diff line change
Expand Up @@ -42,11 +42,23 @@ class CameraDisconnected : public CameraReaderError
using CameraReaderError::CameraReaderError;
};

// Which camera plugin to read from. Left empty, it is this user's plugin on this machine.
// Which camera plugin to read from. Left as it is, it is this user's plugin on this machine,
// started if it is not running.
struct PluginLocation
{
std::string endpoint; // a socket path; empty for the default endpoint of `instance`
std::string instance; // a named plugin instance; empty for the default one

// When no plugin answers on a default endpoint, start one and wait for it. A plugin behind
// an explicit `endpoint` is somebody else's to start.
bool start_if_absent = true;

// The camera_plugin to start; empty for the one next to this program, or on PATH.
std::string executable;

// A plugin started this way exits once no reader has been connected for this long;
// 0 keeps it running.
std::uint32_t exit_when_idle_seconds = 30;
};

/**
Expand Down Expand Up @@ -141,14 +153,15 @@ class CameraReader
public:
/**
* @brief What a camera plugin publishes.
* @throws CameraReaderError if no plugin answers or the plugin refuses this reader.
* @throws CameraReaderError if no plugin answers and none could be started, or the plugin
* refuses this reader.
*/
static std::vector<GroupDescription> list(const PluginLocation& plugin = {});

/**
* @brief Subscribe to one group. A reader for a second group is a second CameraReader.
* @throws CameraReaderError if no plugin answers or the plugin refuses the subscription;
* the message says why.
* @throws CameraReaderError if no plugin answers and none could be started, or the plugin
* refuses the subscription; the message says why.
*/
static CameraReader open(const std::string& group,
const ReaderOptions& options = {},
Expand Down
130 changes: 130 additions & 0 deletions src/core/camera_reader/cpp/plugin_launcher.cpp
Original file line number Diff line number Diff line change
@@ -0,0 +1,130 @@
// SPDX-FileCopyrightText: Copyright (c) 2026 NVIDIA CORPORATION & AFFILIATES. All rights reserved.
// SPDX-License-Identifier: Apache-2.0

#include "plugin_launcher.hpp"

#include <sys/syscall.h>
#include <sys/wait.h>

#include <cerrno>
#include <cstdlib>
#include <fcntl.h>
#include <filesystem>
#include <sstream>
#include <system_error>
#include <unistd.h>

namespace core::camera
{

namespace
{

constexpr const char* PLUGIN_EXECUTABLE = "camera_plugin";

bool can_run(const std::filesystem::path& path)
{
std::error_code ignored;
return std::filesystem::is_regular_file(path, ignored) && ::access(path.c_str(), X_OK) == 0;
}

// Closes every descriptor from `first` up except `keep`. Runs between fork and exec, so it
// uses nothing but system calls.
void close_others(int first, int keep, long limit)
{
#ifdef SYS_close_range
if (::syscall(SYS_close_range, static_cast<unsigned>(first), static_cast<unsigned>(keep - 1), 0U) == 0 &&
::syscall(SYS_close_range, static_cast<unsigned>(keep + 1), ~0U, 0U) == 0)
{
return;
}
#endif
for (int fd = first; fd < limit; ++fd)
{
if (fd != keep)
{
::close(fd);
}
}
}

} // namespace

std::string find_plugin_executable(const std::string& preferred)
{
if (!preferred.empty())
{
return can_run(preferred) ? preferred : std::string();
}
std::error_code ignored;
const std::filesystem::path self = std::filesystem::read_symlink("/proc/self/exe", ignored);
if (!self.empty() && can_run(self.parent_path() / PLUGIN_EXECUTABLE))
{
return (self.parent_path() / PLUGIN_EXECUTABLE).string();
}
const char* search = std::getenv("PATH");
std::istringstream directories(search != nullptr ? search : "");
for (std::string directory; std::getline(directories, directory, ':');)
{
if (!directory.empty() && can_run(std::filesystem::path(directory) / PLUGIN_EXECUTABLE))
{
return (std::filesystem::path(directory) / PLUGIN_EXECUTABLE).string();
}
}
return {};
}

UniqueFd launch_plugin(const std::string& executable, const std::vector<std::string>& arguments)
{
// Everything the new process needs is prepared here: after fork() it may only make system
// calls, because other threads of this process may hold locks at that moment.
std::vector<std::string> owned = { executable };
owned.insert(owned.end(), arguments.begin(), arguments.end());
std::vector<char*> argv;
for (std::string& argument : owned)
{
argv.push_back(argument.data());
}
argv.push_back(nullptr);
const long descriptor_limit = ::sysconf(_SC_OPEN_MAX);

// The plugin holds the write end for as long as it lives; nothing is ever written.
int alive[2] = { -1, -1 };
if (::pipe2(alive, O_CLOEXEC) != 0)
{
throw std::system_error(errno, std::generic_category(), "creating a pipe to the camera plugin");
}
UniqueFd reading(alive[0]);
UniqueFd writing(alive[1]);

const pid_t child = ::fork();
if (child < 0)
{
throw std::system_error(errno, std::generic_category(), "starting the camera plugin");
}
if (child == 0)
{
// A session of its own, and a parent that exits at once: the plugin is then adopted by
// the system, which collects it when it ends.
::setsid();
if (::fork() != 0)
{
::_exit(0);
}
const int null = ::open("/dev/null", O_RDWR);
::dup2(null, STDIN_FILENO);
::dup2(null, STDOUT_FILENO);
::dup2(null, STDERR_FILENO);
::fcntl(writing.get(), F_SETFD, 0); // stays open across exec
close_others(STDERR_FILENO + 1, writing.get(), descriptor_limit);
::execv(argv[0], argv.data());
::_exit(127);
}
int status = 0;
while (::waitpid(child, &status, 0) < 0 && errno == EINTR)
{
}
return reading;
}

} // namespace core::camera
Loading
Loading