sapi_ipc_pubsub.h File Reference

IPC Publish-Subscribe Pattern (one-to-many broadcasting). 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_pubsub.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_pubsub_topic_config_t
	Configuration for a pub-sub topic. More...
struct	sapi_ipc_pubsub_subscriber_config_t
	Configuration for a subscriber. More...

Typedefs
typedef struct sapi_ipc_pubsub_topic_s *	sapi_ipc_pubsub_topic_t
	Publish-subscribe topic handle.
typedef struct sapi_ipc_pubsub_subscriber_s *	sapi_ipc_pubsub_subscriber_t
	Subscriber handle for receiving from a topic.

Functions
sapi_status_t	sapi_ipc_pubsub_topic_create (sapi_ipc_pubsub_topic_t *topic_out, const sapi_ipc_pubsub_topic_config_t *config)
	Create a publish-subscribe topic.
sapi_status_t	sapi_ipc_pubsub_publish (sapi_ipc_pubsub_topic_t topic, const void *message, size_t message_size)
	Publish a message to all subscribers on a topic.
sapi_status_t	sapi_ipc_pubsub_topic_destroy (sapi_ipc_pubsub_topic_t topic)
	Destroy a publish-subscribe topic.
sapi_status_t	sapi_ipc_pubsub_subscribe (sapi_ipc_pubsub_subscriber_t *subscriber_out, const sapi_ipc_pubsub_subscriber_config_t *config)
	Subscribe to a topic.
sapi_status_t	sapi_ipc_pubsub_receive (sapi_ipc_pubsub_subscriber_t subscriber, void *message_out, size_t message_size, sapi_duration_ms_t timeout_ms)
	Receive a message from subscribed topic (blocking with timeout).
sapi_status_t	sapi_ipc_pubsub_unsubscribe (sapi_ipc_pubsub_subscriber_t subscriber)
	Unsubscribe from a topic.

Detailed Description

IPC Publish-Subscribe Pattern (one-to-many broadcasting).

Implements publish-subscribe communication where one publisher sends messages to multiple subscribers on a topic. Subscribers are registered at initialization time (static, no dynamic registration).

Safety Properties:

• Static subscriber registration (no surprise subscribers)
• Decouples publishers from subscribers
• Bounded queues per subscriber (no unbounded growth)
• Delivery guarantees (at-least-once)
• Type-safe message handling

Use Case:

• Track database publishes state changes (topic="track_status")
• Multiple controllers subscribe: signal manager, speed manager, router
• Each reacts independently without knowing about others

Architecture:

        Publisher
          │
     sapi_ipc_publish()
          │
          ▼
┌──────────────────┐
│  Topic "track"   │
│   (broadcast)    │
└────┬─┬─┬────────┘
     │ │ │
┌────▼─▼─▼────────────────────┐
│ Subscriber Queues            │
├──────────────────────────────┤
│ [Queue] Signal Manager       │
│ [Queue] Speed Manager        │
│ [Queue] Route Manager        │
└──────────────────────────────┘
     │          │         │
     ▼          ▼         ▼
Consumer  Consumer   Consumer

Definition in file sapi_ipc_pubsub.h.

Typedef Documentation

sapi_ipc_pubsub_topic_t

typedef struct sapi_ipc_pubsub_topic_s* sapi_ipc_pubsub_topic_t

Publish-subscribe topic handle.

Definition at line 65 of file sapi_ipc_pubsub.h.

sapi_ipc_pubsub_subscriber_t

typedef struct sapi_ipc_pubsub_subscriber_s* sapi_ipc_pubsub_subscriber_t

Subscriber handle for receiving from a topic.

Definition at line 142 of file sapi_ipc_pubsub.h.

Function Documentation

sapi_ipc_pubsub_topic_create()

sapi_status_t sapi_ipc_pubsub_topic_create	(	sapi_ipc_pubsub_topic_t *	topic_out,
		const sapi_ipc_pubsub_topic_config_t *	config )

Create a publish-subscribe topic.

Topics are created before any publishers or subscribers are attached.

Parameters

topic_out	Receives topic handle (not NULL)
config	Topic configuration (not NULL)

Returns

SAPI_STATUS_OK on success SAPI_STATUS_INVALID_PARAM if config is invalid

Example:

sapi_ipc_pubsub_topic_config_t topic_config = {
    .topic_name = "track_status",
    .message_size = sizeof(track_status_t),
    .max_subscribers = 5
};
sapi_ipc_pubsub_topic_t topic;
sapi_ipc_pubsub_topic_create(&topic, &topic_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_pubsub.c.

sapi_ipc_pubsub_publish()

sapi_status_t sapi_ipc_pubsub_publish	(	sapi_ipc_pubsub_topic_t	topic,
		const void *	message,
		size_t	message_size )

Publish a message to all subscribers on a topic.

Message is delivered to all registered subscribers asynchronously. If a subscriber queue is full, behavior depends on overflow strategy.

Parameters

topic	Topic handle (not NULL)
message	Message to publish (not NULL)
message_size	Size of message

Returns

SAPI_STATUS_OK on success SAPI_STATUS_INVALID_PARAM if arguments invalid SAPI_STATUS_ERROR if delivery failed

Example:

track_status_t status = {
    .track_id = 1,
    .occupancy = OCCUPIED,
    .speed_limit = 40
};
sapi_ipc_pubsub_publish(topic, &status, sizeof(status));

Definition at line 53 of file sapi_ipc_pubsub.c.

sapi_ipc_pubsub_topic_destroy()

sapi_status_t sapi_ipc_pubsub_topic_destroy

(

sapi_ipc_pubsub_topic_t

topic

)

Destroy a publish-subscribe topic.

Parameters

topic

Topic handle (not NULL)

Returns

SAPI_STATUS_OK on success

Definition at line 67 of file sapi_ipc_pubsub.c.

sapi_ipc_pubsub_subscribe()

sapi_status_t sapi_ipc_pubsub_subscribe	(	sapi_ipc_pubsub_subscriber_t *	subscriber_out,
		const sapi_ipc_pubsub_subscriber_config_t *	config )

Subscribe to a topic.

Registers a subscriber to receive messages from a topic. Must be called during initialization, before publishing.

Parameters

subscriber_out	Receives subscriber handle (not NULL)
config	Subscriber configuration (not NULL)

Returns

SAPI_STATUS_OK on success SAPI_STATUS_INVALID_PARAM if config invalid SAPI_STATUS_ERROR if max subscribers reached

Example:

sapi_ipc_pubsub_subscriber_config_t sub_config = {
    .subscriber_name = "signal_manager",
    .topic = track_status_topic,
    .queue_depth = 10
};
sapi_ipc_pubsub_subscriber_t subscriber;
sapi_ipc_pubsub_subscribe(&subscriber, &sub_config);

Definition at line 77 of file sapi_ipc_pubsub.c.

sapi_ipc_pubsub_receive()

sapi_status_t sapi_ipc_pubsub_receive	(	sapi_ipc_pubsub_subscriber_t	subscriber,
		void *	message_out,
		size_t	message_size,
		sapi_duration_ms_t	timeout_ms )

Receive a message from subscribed topic (blocking with timeout).

Parameters

subscriber	Subscriber handle (not NULL)
message_out	Destination buffer for message (not NULL)
message_size	Max size of message buffer
timeout_ms	Max wait time; 0 = poll, UINT32_MAX = infinite

Returns

SAPI_STATUS_OK on success (message received) SAPI_STATUS_TIMEOUT if no message within timeout SAPI_STATUS_INVALID_PARAM on invalid arguments

Example:

track_status_t status;
sapi_status_t result = sapi_ipc_pubsub_receive(
    subscriber,
    &status, sizeof(status),
    1000  // Poll every 1 second
);
 
if (result == SAPI_STATUS_OK) {
    printf("Track %d status: %d\n", status.track_id, status.occupancy);
    // React to status change...
}

Definition at line 95 of file sapi_ipc_pubsub.c.

sapi_ipc_pubsub_unsubscribe()

sapi_status_t sapi_ipc_pubsub_unsubscribe

(

sapi_ipc_pubsub_subscriber_t

subscriber

)

Unsubscribe from a topic.

Parameters

subscriber

Subscriber handle (not NULL)

Returns

SAPI_STATUS_OK on success

Definition at line 108 of file sapi_ipc_pubsub.c.