libcamera: libcamera::IPCUnixSocket Class Reference

libcamera v0.7.2 Supporting cameras in Linux since 2019

Loading...
Searching...
No Matches
libcamera::IPCUnixSocket Class Reference

IPC mechanism based on Unix sockets. More...

Collaboration diagram for libcamera::IPCUnixSocket:
[legend]

## Classes
struct | Payload
| Container for an IPC payload. More...

## Public Member Functions
UniqueFD | create ()
| Create an new IPC channel.
int | bind (UniqueFD fd)
| Bind to an existing IPC channel.
void | close ()
| Close the IPC channel.
bool | isBound () const
| Check if the IPC channel is bound.
int | send (const Payload &payload)
| Send a message payload.
int | receive (Payload *payload)
| Receive a message payload.

## Public Attributes
Signal | readyRead
| A Signal emitted when a message is ready to be read.

## Detailed Description

IPC mechanism based on Unix sockets.

The Unix socket IPC allows bidirectional communication between two processes through unnamed Unix sockets. It implements datagram-based communication, transporting entire payloads with guaranteed ordering.

The IPC design is asynchronous, a message is queued to a receiver which gets notified that a message is ready to be consumed by the readyRead signal. The sender of the message gets no notification when a message is delivered nor processed. If such interactions are needed a protocol specific to the users use-case should be implemented on top of the IPC objects.

Establishment of an IPC channel is asymmetrical. The side that initiates communication first instantiates a local side socket and creates the channel with create(). The function returns a file descriptor for the remote side of the channel, which is passed to the remote process through an out-of-band communication method. The remote side then instantiates a socket, and binds it to the other side by passing the file descriptor to bind(). At that point the channel is operation and communication is bidirectional and symmmetrical.

Thread Safety
  This class is thread-bound.

## Member Function Documentation

## ◆ bind()

int libcamera::IPCUnixSocket::bind | ( | UniqueFD | fd | ) |

Bind to an existing IPC channel.

Parameters

  [in] | fd | File descriptor

This function binds the socket instance to an existing IPC channel identified by the file descriptor fd. The file descriptor is obtained from the IPCUnixSocket::create() function.

Returns
  0 on success or a negative error code otherwise

## ◆ close()

void libcamera::IPCUnixSocket::close | ( |  | ) |

Close the IPC channel.

No communication is possible after close() has been called.

## ◆ create()

UniqueFD libcamera::IPCUnixSocket::create | ( |  | ) |

Create an new IPC channel.

This function creates a new IPC channel. The socket instance is bound to the local side of the channel, and the function returns a file descriptor bound to the remote side. The caller is responsible for passing the file descriptor to the remote process, where it can be used with IPCUnixSocket::bind() to bind the remote side socket.

Returns
  A file descriptor. It is valid on success or invalid otherwise.

## ◆ isBound()

bool libcamera::IPCUnixSocket::isBound | ( |  | ) | const

Check if the IPC channel is bound.

Returns
  True if the IPC channel is bound, false otherwise

## ◆ receive()

int libcamera::IPCUnixSocket::receive | ( | Payload * | payload | ) |

Receive a message payload.

Parameters

  [out] | payload | Payload where to write the received message

This function receives the message payload from the IPC channel and writes it to the payload. If no message payload is available, it returns immediately with -EAGAIN. The readyRead signal shall be used to receive notification of message availability.

Todo
  Add state machine to make sure we don't block forever and that a header is always followed by a payload.

Returns
  0 on success or a negative error code otherwise

Return values

  -EAGAIN | No message payload is available
  -ENOTCONN | The socket is not connected (neither create() nor bind() has been called)

## ◆ send()

int libcamera::IPCUnixSocket::send | ( | const Payload & | payload | ) |

Send a message payload.

Parameters

  [in] | payload | Message payload to send

This function queues the message payload for transmission to the other end of the IPC channel. It returns immediately, before the message is delivered to the remote side.

Returns
  0 on success or a negative error code otherwise

The documentation for this class was generated from the following files:

- include/libcamera/internal/ipc_unixsocket.h
- src/libcamera/ipc_unixsocket.cpp