Client IPC API.

Overview

libqb provides a generically reusable very high performance shared memory IPC system for client and service applications. It supports many features including:

Multiple transport implementations
1. Shared memory implementation for very high performance.
2. Unix sockets
A synchronous request/response channel and asynchronous response channel per ipc connection.
User defined private data per IPC connection.
Ability to call a function per service on ipc connection and disconnection.
Authenticated IPC connection with ability for developer to define which UIDs and GIDs are valid at connection time.
Fully abstracted poll system so that any poll library may be used.
User defined selector for determining the proper function to call per service and id.

Security: The ipc system uses default operating system security mechanics to ensure ipc connections are validated. A callback used with qb_ipcs_create() is called for every new ipc connection with the parameters of UID and GID. The callback then determines if the UID and GID are authenticated for communication.

Performance: For performance, QB_IPC_SHM (shared memory) is recommended. It is tuned for very high performance.

Multithreading: There are not many guarantees about the ipc system being thread-safe. It is essential that all sends and all receives are in their own thread, though having separate threads for each is supported.

If you need to send on multiple threads then either use locking around the calls or create a separate connection for each thread.

IPC sockets (Linux only)

On Linux IPC, abstract (non-filesystem) sockets are used by default. If you need to override this (say in a net=host container) and use sockets that reside in the filesystem, then you need to create a file called /etc/libqb/force-filesystem-sockets

this is the default name and can be changed at ./configure time. The file does not need to contain any content, it's not a configuration file as such, just its presence will activate the feature.

Note that this is a global option and read each time a new IPC connection (client or server) is created. So, to avoid having clients that cannot connect to running servers it is STRONGLY recommended to only create or remove this file prior to a system reboot or container restart.

Client API

Lifecycle of an IPC connection.: An IPC connection is made to the server with qb_ipcc_connect(). This function connects to the server and requests channels be created for communication. To disconnect, the client either exits or executes the function qb_ipcc_disconnect().

Synchronous communication: The function qb_ipcc_sendv_recv() sends an iovector request and receives a response.

Asynchronous requests from the client: The function qb_ipcc_sendv() sends an iovector request. The function qb_ipcc_send() sends an message buffer request.

Asynchronous events from the server: The qb_ipcc_event_recv() function receives an out-of-band asynchronous message. The asynchronous messages are queued and can provide very high out-of-band performance. To determine when to call qb_ipcc_event_recv() the qb_ipcc_fd_get() call is used to obtain a file descriptor used in the poll() or select() system calls.

See Also: qbipcc.h

Server API: Server IPC API.

See Also: qbipcs.h