libcamera  v0.1.0+127-8e215127
Supporting cameras in Linux since 2019
Classes | Public Member Functions | Public Attributes | List of all members
libcamera::IPCUnixSocket Class Reference

IPC mechanism based on Unix sockets. More...

Collaboration diagram for libcamera::IPCUnixSocket:
Collaboration graph


struct  Payload
 Container for an IPC payload. More...

Public Member Functions

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

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.

[in]fdFile 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.

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.

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

◆ isBound()

bool libcamera::IPCUnixSocket::isBound ( ) const

Check if the IPC channel is bound.

True if the IPC channel is bound, false otherwise

◆ receive()

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

Receive a message payload.

[out]payloadPayload 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.

Add state machine to make sure we don't block forever and that a header is always followed by a payload.
0 on success or a negative error code otherwise
Return values
-EAGAINNo message payload is available
-ENOTCONNThe socket is not connected (neither create() nor bind() has been called)

◆ send()

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

Send a message payload.

[in]payloadMessage 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.

0 on success or a negative error code otherwise

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