sapi_ipc_request_reply.h File Reference

IPC Request-Reply Pattern (RPC-style communication). More...

#include "safeapi/utils/status/sapi_status.h"
#include "safeapi/utils/types/sapi_types.h"
#include "sapi_ipc.h"

Include dependency graph for sapi_ipc_request_reply.h:

This graph shows which files directly or indirectly include this file:

Go to the source code of this file.

Data Structures
struct	sapi_ipc_rr_server_config_t
	Configuration for request-reply server. More...
struct	sapi_ipc_rr_request_t
	Incoming request with context for sending reply. More...
struct	sapi_ipc_rr_client_config_t
	Configuration for request-reply client. More...

Typedefs
typedef struct sapi_ipc_rr_server_s *	sapi_ipc_rr_server_t
	Request-Reply server channel handle.
typedef struct sapi_ipc_rr_client_s *	sapi_ipc_rr_client_t
	Request-reply client handle.

Functions
sapi_status_t	sapi_ipc_rr_server_create (sapi_ipc_rr_server_t *handle_out, const sapi_ipc_rr_server_config_t *config)
	Create a request-reply server channel.
sapi_status_t	sapi_ipc_rr_receive_request (sapi_ipc_rr_server_t server, sapi_ipc_rr_request_t *request_out, sapi_duration_ms_t timeout_ms)
	Receive a request (blocking with timeout).
sapi_status_t	sapi_ipc_rr_send_reply (sapi_ipc_rr_server_t server, uint32_t request_id, const void *reply_data, size_t reply_size)
	Send reply to a request.
sapi_status_t	sapi_ipc_rr_server_destroy (sapi_ipc_rr_server_t server)
	Destroy request-reply server.
sapi_status_t	sapi_ipc_rr_client_create (sapi_ipc_rr_client_t *handle_out, const sapi_ipc_rr_client_config_t *config)
	Create a request-reply client connection.
sapi_status_t	sapi_ipc_rr_request (sapi_ipc_rr_client_t client, const void *request_data, size_t request_size, void *reply_out, size_t reply_size, sapi_duration_ms_t timeout_ms)
	Send request and wait for reply (blocking with timeout).
sapi_status_t	sapi_ipc_rr_client_destroy (sapi_ipc_rr_client_t client)
	Destroy request-reply client connection.

Detailed Description

IPC Request-Reply Pattern (RPC-style communication).

Implements synchronous request-reply communication where a client sends a request and blocks (with timeout) waiting for a reply. Server receives the request, processes it, and sends a reply back.

This is a higher-level abstraction built on the base IPC layer.

Safety Properties:

• Deadlock-free (timeout prevents indefinite blocking)
• Request IDs prevent reply mismatches
• Explicit error on timeout (no silent hangs)
• Type-safe message handling

Use Case:

• Train controller queries signal database for current signal state
• Dispatcher requests route information from route manager
• Any synchronous RPC pattern

Definition in file sapi_ipc_request_reply.h.

Typedef Documentation

sapi_ipc_rr_server_t

typedef struct sapi_ipc_rr_server_s* sapi_ipc_rr_server_t

Request-Reply server channel handle.

Definition at line 42 of file sapi_ipc_request_reply.h.

sapi_ipc_rr_client_t

typedef struct sapi_ipc_rr_client_s* sapi_ipc_rr_client_t

Request-reply client handle.

Definition at line 149 of file sapi_ipc_request_reply.h.

Function Documentation

sapi_ipc_rr_server_create()

sapi_status_t sapi_ipc_rr_server_create	(	sapi_ipc_rr_server_t *	handle_out,
		const sapi_ipc_rr_server_config_t *	config )

Create a request-reply server channel.

Parameters

handle_out	Receives server handle (not NULL)
config	Server configuration (not NULL)

Returns

SAPI_STATUS_OK or error

Example:

sapi_ipc_rr_server_config_t config = {
    .name = "signal-server",
    .request_size = sizeof(signal_query_t),
    .reply_size = sizeof(signal_reply_t),
    .queue_depth = 10
};
sapi_ipc_rr_server_t server;
sapi_ipc_rr_server_create(&server, &config);

Local makros Local types declarations Local variables declarations Global variables declarations Local function declarations Global functions

Definition at line 25 of file sapi_ipc_request_reply.c.

sapi_ipc_rr_receive_request()

sapi_status_t sapi_ipc_rr_receive_request	(	sapi_ipc_rr_server_t	server,
		sapi_ipc_rr_request_t *	request_out,
		sapi_duration_ms_t	timeout_ms )

Receive a request (blocking with timeout).

Parameters

server	Server handle (not NULL)
request_out	Receives request and context (not NULL)
timeout_ms	Max wait time; 0 = poll, UINT32_MAX = infinite

Returns

SAPI_STATUS_OK on success SAPI_STATUS_TIMEOUT if no request arrived within timeout SAPI_STATUS_INVALID_PARAM on invalid handle/buffer

Example:

sapi_ipc_rr_request_t request;
if (sapi_ipc_rr_receive_request(server, &request, 1000) == SAPI_STATUS_OK) {
    // Process request...
    signal_query_t *query = (signal_query_t *)request.request_data;
    // Send reply...
}

Definition at line 50 of file sapi_ipc_request_reply.c.

sapi_ipc_rr_send_reply()

sapi_status_t sapi_ipc_rr_send_reply	(	sapi_ipc_rr_server_t	server,
		uint32_t	request_id,
		const void *	reply_data,
		size_t	reply_size )

Send reply to a request.

Parameters

server	Server handle (not NULL)
request_id	ID from the request being replied to
reply_data	Reply payload (not NULL)
reply_size	Size of reply (must match configured size)

Returns

SAPI_STATUS_OK on success SAPI_STATUS_ERROR if reply fails SAPI_STATUS_TIMEOUT if client has given up waiting

Example:

signal_reply_t reply = {
    .signal_state = SIGNAL_GREEN,
    .track_speed = 80
};
sapi_ipc_rr_send_reply(server, request.request_id, &reply, sizeof(reply));

Definition at line 62 of file sapi_ipc_request_reply.c.

sapi_ipc_rr_server_destroy()

sapi_status_t sapi_ipc_rr_server_destroy

(

sapi_ipc_rr_server_t

server

)

Destroy request-reply server.

Parameters

server

Server handle (not NULL)

Returns

SAPI_STATUS_OK on success

Definition at line 77 of file sapi_ipc_request_reply.c.

sapi_ipc_rr_client_create()

sapi_status_t sapi_ipc_rr_client_create	(	sapi_ipc_rr_client_t *	handle_out,
		const sapi_ipc_rr_client_config_t *	config )

Create a request-reply client connection.

Parameters

handle_out	Receives client handle (not NULL)
config	Client configuration (not NULL)

Returns

SAPI_STATUS_OK on success SAPI_STATUS_ERROR if server not found

Example:

sapi_ipc_rr_client_config_t config = {
    .server_name = "signal-server",
    .request_size = sizeof(signal_query_t),
    .reply_size = sizeof(signal_reply_t)
};
sapi_ipc_rr_client_t client;
sapi_ipc_rr_client_create(&client, &config);

Definition at line 87 of file sapi_ipc_request_reply.c.

sapi_ipc_rr_request()

sapi_status_t sapi_ipc_rr_request	(	sapi_ipc_rr_client_t	client,
		const void *	request_data,
		size_t	request_size,
		void *	reply_out,
		size_t	reply_size,
		sapi_duration_ms_t	timeout_ms )

Send request and wait for reply (blocking with timeout).

This is the main client operation: send request, block waiting for reply.

Parameters

client	Client handle (not NULL)
request_data	Request to send (not NULL)
request_size	Size of request
reply_out	Destination buffer for reply (not NULL)
reply_size	Max size of reply buffer
timeout_ms	Max wait time for reply; 0 = poll, UINT32_MAX = infinite

Returns

SAPI_STATUS_OK on success (reply received) SAPI_STATUS_TIMEOUT if no reply within timeout SAPI_STATUS_ERROR if server rejected request SAPI_STATUS_INVALID_PARAM on bad arguments

Example:

signal_query_t query = {.train_id = 1, .location = 500};
signal_reply_t reply;
 
sapi_status_t status = sapi_ipc_rr_request(
    client,
    &query, sizeof(query),
    &reply, sizeof(reply),
    5000  // Wait up to 5 seconds for reply
);
 
if (status == SAPI_STATUS_OK) {
    printf("Signal state: %d\n", reply.signal_state);
} else if (status == SAPI_STATUS_TIMEOUT) {
    printf("Server did not reply in time\n");
}

Definition at line 110 of file sapi_ipc_request_reply.c.

sapi_ipc_rr_client_destroy()

sapi_status_t sapi_ipc_rr_client_destroy

(

sapi_ipc_rr_client_t

client

)

Destroy request-reply client connection.

Parameters

client

Client handle (not NULL)

Returns

SAPI_STATUS_OK on success

Definition at line 128 of file sapi_ipc_request_reply.c.