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
2 changes: 1 addition & 1 deletion src/core/CMakeLists.txt
Original file line number Diff line number Diff line change
Expand Up @@ -22,7 +22,7 @@ add_subdirectory(plugin_manager)
# Camera capture core (standard library only)
add_subdirectory(camera_core)

# Camera frames between processes (shared host memory)
# Camera frames and messages between processes (shared host memory, descriptor passing)
if(CMAKE_SYSTEM_NAME STREQUAL "Linux")
add_subdirectory(camera_ipc)
endif()
Expand Down
3 changes: 3 additions & 0 deletions src/core/camera_ipc/AGENTS.md
Original file line number Diff line number Diff line change
Expand Up @@ -10,6 +10,9 @@ SPDX-License-Identifier: Apache-2.0
Read [`README.md`](README.md) first; it explains why frames cross between processes this way.

- **Linux only.** The module and its tests are added under `CMAKE_SYSTEM_NAME STREQUAL "Linux"`. Platform calls stay here and out of `camera_core`.
- **Frame memory crosses as a file descriptor on the module's Unix socket.** Do not add a messaging or shared-memory library for it; a new kind of memory is a new pool type behind the same connection.
- **Nothing on the capture path waits for a reader.** Sends do not block; a full queue and a closed peer are statuses, not exceptions.
- **A lock file owns the socket path.** Remove a socket file only while holding it, and never remove anything that is not a socket.
- **Readers cannot write.** A pool is sealed before its descriptor leaves the process, and a reader maps it read-only. Do not hand a reader a writable mapping.
- **Derive what both sides can compute.** A pool's layout follows from the slot count and slot size in the stream's description; do not send it separately.
- **Tests need no camera and no GPU**, and carry the `unit` tag.
48 changes: 47 additions & 1 deletion src/core/camera_ipc/README.md
Original file line number Diff line number Diff line change
Expand Up @@ -9,7 +9,7 @@ The process that owns the cameras and the processes that read them are on one ma
module is what crosses between them. Linux only.

[`camera_core`](../camera_core) decides which slot holds which frame; this module provides the
memory behind the slots.
memory behind the slots and the connection that tells a reader which slot to look at.

## Host pool

Expand Down Expand Up @@ -37,6 +37,52 @@ Why an anonymous sealed file and not named shared memory (`shm_open`):
- **Access follows the connection.** Only a process that was handed the descriptor can map the
pool.

## Message socket

`MessageListener` and `MessageSocket` are the connection: a Unix domain socket of the
sequenced-packet kind (`SOCK_SEQPACKET`). The owner listens on a socket file, each reader
connects, and either side sends messages with file descriptors attached.

```cpp
MessageListener listener(path); // the owner
auto reader = listener.accept(timeout);
const int descriptors[] = { pool.descriptor() };
reader->send(description_bytes, descriptors);

MessageSocket socket = MessageSocket::connect(path); // a reader
ReceivedMessage message = socket.receive(buffer, timeout);
HostPoolView view(std::move(message.descriptors[0]), slot_count, slot_bytes);
```

- **Whole messages.** One `send` is one `receive`, in order, so there is no framing to get wrong.
- **Sending never blocks.** If a reader stops draining its queue the sender gets `WOULD_BLOCK`
and moves on; capture never waits for a reader.
- **A dead peer is seen at once.** When a process exits or crashes the other end reads
`CLOSED`, which is how the frames a crashed reader held are taken back.
- **Owner only.** The socket file is created with mode `0600`.
- **One listener per path.** A lock file next to the socket file (`<path>.lock`) decides who
owns the path, so of two processes that start together exactly one listens, and a socket
file left by a crashed process is replaced safely. Anything else found at the path is left
alone. The lock file stays behind, empty.

## Why a socket and shared memory, and not a messaging library

Three things have to cross between the processes: the frame memory, a small event per frame
set, and the news that a peer has gone.

Frame memory is named by a file descriptor: a sealed memory file here, and the same holds for
the buffers of hardware capture and codec stacks (DMA-BUF) and for GPU memory that can be
exported. Attaching a descriptor to a message on a Unix socket is the standard way to hand one
to another process, so a socket is needed whatever else is used. Once it is there it also
carries the events and reports dead peers, which leaves a messaging library nothing to do.

| Considered | Why it is not used |
|---|---|
| iceoryx2 | It moves self-contained data through host memory that it allocates. Frame memory that exists only as a descriptor would still need a socket beside it, and its C++ binding adds a Rust toolchain to the build. |
| CUDA inter-process handles | A way to share one kind of GPU memory, not a way to connect processes: the handle still has to travel over some connection, and host memory and DMA-BUF are not covered. |
| ZeroMQ, gRPC, DDS | They copy the payload or share host memory only, and none of them pass descriptors. |
| PipeWire, GStreamer | The same mechanism underneath, wrapped in a media graph and, for PipeWire, a daemon. A reader here needs neither. |

## Tests

`tests/cpp/core/camera_ipc`, run with `ctest -L camera_ipc`. They are tagged `unit`, so
Expand Down
6 changes: 4 additions & 2 deletions src/core/camera_ipc/cpp/CMakeLists.txt
Original file line number Diff line number Diff line change
Expand Up @@ -3,10 +3,12 @@

cmake_minimum_required(VERSION 3.20)

# How camera frames cross between processes on one machine: pools of shared host memory that
# readers can only map read-only. Linux only.
# How camera frames and messages cross between processes on one machine: pools of shared host
# memory that readers can only map read-only, and a socket that carries whole messages with
# file descriptors. Linux only.
add_library(camera_ipc STATIC
host_pool.cpp
message_socket.cpp
)

target_include_directories(camera_ipc INTERFACE
Expand Down
129 changes: 129 additions & 0 deletions src/core/camera_ipc/cpp/inc/camera_ipc/message_socket.hpp
Original file line number Diff line number Diff line change
@@ -0,0 +1,129 @@
// SPDX-FileCopyrightText: Copyright (c) 2026 NVIDIA CORPORATION & AFFILIATES. All rights reserved.
// SPDX-License-Identifier: Apache-2.0

#pragma once

#include "unique_fd.hpp"

#include <chrono>
#include <cstddef>
#include <optional>
#include <span>
#include <string>
#include <vector>

namespace core::camera
{

// A message carries at most this many descriptors.
inline constexpr std::size_t MAX_DESCRIPTORS_PER_MESSAGE = 64;

enum class SendStatus
{
SENT,
WOULD_BLOCK, // the peer's queue is full; nothing was sent
CLOSED, // the peer is gone
};

enum class ReceiveStatus
{
MESSAGE,
TIMEOUT,
CLOSED, // the peer is gone
};

struct ReceivedMessage
{
ReceiveStatus status = ReceiveStatus::TIMEOUT;
std::size_t bytes = 0; // of the payload, when status is MESSAGE
std::vector<UniqueFd> descriptors; // the ones that came with the message
};

/**
* @brief One end of a connection between two processes on this machine. It carries whole
* messages in order, each with optional file descriptors.
*/
class MessageSocket
{
public:
/**
* @brief Connect to a MessageListener.
* @throws std::system_error if nothing listens on the path.
*/
static MessageSocket connect(const std::string& path);

explicit MessageSocket(UniqueFd fd);

/**
* @brief Send one message. Never blocks.
* @throws std::invalid_argument for an empty payload (it would read as a closed connection)
* or more than MAX_DESCRIPTORS_PER_MESSAGE descriptors.
* @throws std::system_error for a failure other than a full queue or a closed peer.
*/
SendStatus send(std::span<const std::byte> payload, std::span<const int> descriptors = {});

/**
* @brief Wait up to `timeout` for one message and copy its payload into `buffer`.
* @throws std::length_error if the message does not fit the buffer.
* @throws std::system_error for a failure other than a closed peer.
*/
ReceivedMessage receive(std::span<std::byte> buffer, std::chrono::milliseconds timeout);

// For waiting on several sockets at once.
int descriptor() const
{
return m_fd.get();
}

private:
UniqueFd m_fd;
};

/**
* @brief Accepts connections on a socket file. Only processes of the same user can connect.
*
* A lock file next to the socket file (`<path>.lock`) decides which process owns the path, so
* of two processes that start at the same moment exactly one listens. The lock file stays
* behind, empty, for the next listener to lock.
*/
class MessageListener
{
public:
/**
* @brief Start listening on `path`. A socket file left behind by a process that has gone is
* replaced; anything else found at the path is left alone.
* @throws std::system_error with EADDRINUSE if another process listens on the path, with
* EEXIST if the path holds something that is not a socket, or with the cause if the path
* cannot be locked or bound.
*/
explicit MessageListener(const std::string& path);

// Removes the socket file.
~MessageListener();

MessageListener(const MessageListener&) = delete;
MessageListener& operator=(const MessageListener&) = delete;

/**
* @brief Wait up to `timeout` for a connection.
* @return The connection, or nothing on timeout.
*/
std::optional<MessageSocket> accept(std::chrono::milliseconds timeout);

int descriptor() const
{
return m_fd.get();
}

const std::string& path() const
{
return m_path;
}

private:
UniqueFd m_lock; // declared first, so it is released after the socket is closed
UniqueFd m_fd;
std::string m_path;
};

} // namespace core::camera
Loading
Loading