libcamera::IPCUnixSocket Class Reference

IPC mechanism based on Unix sockets. More...

Collaboration diagram for libcamera::IPCUnixSocket:

Classes
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.

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