Skip to content

Commit 8c02991

Browse files
gonzolivelygonzolively
authored
Added inter-container messaging API docs (#29)
1 parent 8994101 commit 8c02991

2 files changed

Lines changed: 277 additions & 0 deletions

File tree

‎docs/reference/apis/container-api/index.md‎

Lines changed: 6 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -14,6 +14,12 @@ Container APIs provide direct interfaces for containers to efficiently interact
1414

1515
Below are the core APIs available for Ocre containers. Each API includes detailed documentation with usage examples, error handling patterns, and best practices.
1616

17+
### Communication
18+
19+
| API | Description|
20+
|-----|-------------|
21+
| **[Inter-Container Messaging](inter-container-messaging)** | Enable secure communication between containers |
22+
1723
### System Interaction
1824

1925
| API | Description |

‎docs/reference/apis/container-api/inter-container-messaging.md‎

Lines changed: 271 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,271 @@
1+
---
2+
title: Inter-Container Messaging
3+
layout: default
4+
parent: Container
5+
has_toc: false
6+
---
7+
8+
# Inter-Container Messaging
9+
{: .no_toc }
10+
11+
The Inter-Container Messaging API enables containers to communicate through a publish-subscribe pattern, allowing for decoupled, asynchronous interactions without direct dependencies.
12+
13+
---
14+
15+
## Table of Contents
16+
{: .no_toc }
17+
18+
Navigate this comprehensive API reference using the links below.
19+
20+
<details close markdown="block">
21+
<summary>
22+
Click to expand
23+
</summary>
24+
{: .text-delta }
25+
1. TOC
26+
{:toc}
27+
</details>
28+
29+
---
30+
31+
## Header File
32+
33+
```c
34+
#include "messaging.h"
35+
```
36+
37+
---
38+
39+
## Types
40+
41+
### Message Structure
42+
43+
A structure defining the format of messages used in inter-container communication.
44+
45+
```c
46+
typedef struct ocre_msg {
47+
uint64_t mid; ///< Message ID - auto-incremented for each message
48+
char *topic; ///< Topic name for the message
49+
char *content_type; ///< Content type of the message (MIME type recommended)
50+
void *payload; ///< Pointer to the message payload
51+
int payload_len; ///< Length of the payload in bytes
52+
} ocre_msg_t;
53+
```
54+
55+
---
56+
57+
## Methods
58+
59+
### Initialize Messaging System
60+
61+
Initializes the inter-container messaging system by setting up a message queue and starting a subscriber thread. If already initialized, the function **logs a warning** but **proceeds without error**.
62+
63+
```c
64+
void ocre_msg_system_init(void);
65+
```
66+
67+
**Returns**:
68+
- None
69+
70+
### Publish Message
71+
72+
Publishes a message to the specified topic.
73+
74+
```c
75+
int ocre_publish_message(wasm_exec_env_t exec_env, char *topic, char *content_type, void *payload, int payload_len);
76+
```
77+
78+
Fails if the messaging system is not initialized, if `topic`, `content_type`, or `payload` is `NULL`/empty, if `payload_len` is `0`, or if the message queue is full.
79+
80+
**Parameters**:
81+
82+
| Name | Type | Description |
83+
| ---- | ---- | ----------- |
84+
| `exec_env` | *wasm_exec_env_t* | Currently unused but required for compatibility with WebAssembly runtime |
85+
| `topic` | *char* | Topic name to publish the message to |
86+
| `content_type` | *char* | Content type of the message (`MIME` type recommended) |
87+
| `payload` | *void* | Pointer to the **message payload buffer** |
88+
| `payload_len` | *int* | Length of the payload in bytes |
89+
90+
**Returns**:
91+
92+
| Value | Description |
93+
| ----- | ----------- |
94+
| `0` | Message published successfully |
95+
| `-1` | Failed to publish message (see error codes) |
96+
97+
### Subscribe to Topic
98+
99+
Subscribes to a topic to receive messages.
100+
101+
```c
102+
int ocre_subscribe_message(wasm_exec_env_t exec_env, char *topic, char *handler_name);
103+
```
104+
105+
**Parameters**:
106+
107+
| Name | Type | Description |
108+
| ---- | ---- | ----------- |
109+
| `exec_env` | *wasm_exec_env_t* | WebAssembly execution environment used to locate the callback function in the WebAssembly module. |
110+
| `topic` | *char* | Topic name to subscribe to |
111+
| `handler_name` | *char* | Name of the callback function to be called when a message is received |
112+
113+
**Returns**:
114+
115+
| Value | Description |
116+
| ----- | ----------- |
117+
| `0` | Subscription successful |
118+
| `-1` | Failed to subscribe (see error codes) |
119+
120+
---
121+
122+
## Error Handling
123+
124+
The Inter-Container Messaging API functions return integer status codes to indicate success or failure. Although all error conditions return the same value (`-1`), different types of errors can occur based on the context and input parameters.
125+
126+
### Error Codes
127+
128+
| Return Value | Description |
129+
|--------------|-------------|
130+
| `0` | Success - The operation completed successfully |
131+
| `-1` | Failure - The operation failed (see error conditions) |
132+
133+
---
134+
135+
Sure — here’s a clean way to combine and tighten what you wrote, keeping the clarity and the important notes:
136+
137+
---
138+
139+
## Examples
140+
141+
The following example demonstrates how to use the Inter-Container Messaging API in Ocre-based containers. Containers communicate asynchronously using a publish-subscribe model, with messages processed in a dedicated subscriber thread managed by the messaging system.
142+
143+
*Two* containers work together:
144+
- The **[Publisher Container](#publisher-container)** sends JSON-formatted temperature readings to the `sensors/temperature` topic every 500 milliseconds.
145+
- The **[Subscriber Container](#subscriber-container)** subscribes to this topic and processes incoming messages.
146+
147+
**Notes**:
148+
- The `wasm_exec_env_t` parameter is required for WebAssembly function signatures but may be unused in some cases (e.g., publishing). In real applications, it is provided by the WASM runtime.
149+
- Use `ocre_sleep` instead of POSIX `sleep`.
150+
- The messaging system automatically handles memory allocation and deallocation for messages passed to callback functions.
151+
152+
---
153+
154+
### Publisher Container
155+
156+
```c
157+
#include <stdio.h>
158+
#include <string.h>
159+
#include "messaging.h"
160+
161+
#define INTERVAL_MS 500
162+
163+
// Initialize the messaging system
164+
static int init_messaging(void) {
165+
ocre_msg_system_init();
166+
printf("Messaging system initialized\n");
167+
return 0;
168+
}
169+
170+
// Publish temperature data
171+
static void publish_temperature(void) {
172+
char *topic = "sensors/temperature";
173+
char *content_type = "application/json";
174+
char payload[64];
175+
176+
static float temp = 22.5;
177+
snprintf(payload, sizeof(payload), "{\"temperature\": %.1f, \"unit\": \"celsius\"}", temp);
178+
temp += 0.1;
179+
int payload_len = strlen(payload) + 1; // Include null terminator
180+
181+
int ret = ocre_publish_message(NULL, topic, content_type, payload, payload_len);
182+
if (ret == 0) {
183+
printf("Published temperature data to %s\n", topic);
184+
} else {
185+
printf("Failed to publish temperature data: %d\n", ret);
186+
}
187+
}
188+
189+
// Application entry point
190+
int main(void) {
191+
// Set STDIO to line buffering
192+
setvbuf(stdout, NULL, _IOLBF, 0);
193+
194+
// Initialize messaging
195+
if (init_messaging() != 0) {
196+
printf("Failed to initialize messaging\n");
197+
return -1;
198+
}
199+
200+
// Publish data periodically
201+
while (1) {
202+
publish_temperature();
203+
ocre_sleep(INTERVAL_MS);
204+
}
205+
206+
return 0;
207+
}
208+
```
209+
210+
### Subscriber Container
211+
212+
```c
213+
214+
#include <stdio.h>
215+
#include <string.h>
216+
#include "messaging.h"
217+
218+
// Message handler function (exported for WASM)
219+
__attribute__((export_name("temperature_handler")))
220+
221+
void temperature_handler(wasm_exec_env_t exec_env, ocre_msg_t *msg) {
222+
printf("Received message on topic: %s\n", msg->topic);
223+
printf("Content type: %s\n", msg->content_type);
224+
printf("Payload: %s\n", (char *)msg->payload);
225+
printf("Message ID: %llu\n", msg->mid);
226+
227+
// In a real application, parse the JSON payload and process the data
228+
}
229+
230+
// Initialize the messaging system and subscribe to topics
231+
static int init_messaging(void) {
232+
ocre_msg_system_init();
233+
printf("Messaging system initialized\n");
234+
235+
int ret = ocre_subscribe_message(NULL, "sensors/temperature", "temperature_handler");
236+
if (ret != 0) {
237+
printf("Failed to subscribe: %d\n", ret);
238+
return ret;
239+
}
240+
printf("Subscribed to sensors/temperature\n");
241+
return 0;
242+
}
243+
244+
// Application entry point
245+
int main(void) {
246+
// Set STDIO to line buffering
247+
setvbuf(stdout, NULL, _IOLBF, 0);
248+
249+
// Initialize messaging and subscription
250+
if (init_messaging() != 0) {
251+
printf("Failed to initialize messaging\n");
252+
return -1;
253+
}
254+
255+
// Keep the application running
256+
while (1) {
257+
ocre_sleep(100); // Prevent busy waiting
258+
}
259+
260+
return 0;
261+
}
262+
```
263+
264+
---
265+
266+
## Reference
267+
268+
| Function | Description | Parameters | Return Value | Error Conditions |
269+
|----------|-------------|------------|--------------|------------------|
270+
| [`ocre_msg_system_init`](#initialize-messaging-system) | Initializes the messaging system | None | None | None |
271+
| [`ocre_publish_message`](#publish-message) | Publishes a message to a topic | `exec_env`: WASM execution environment<br/>`topic`: Topic name<br/>`content_type`: MIME type<br/>`payload`: Message content<br/>`payload_len`: Content length | `0`: Success<br/>`-1`: Failure | Topic is `NULL`/empty<br/>Content type is `NULL`/empty<br/>Payload is `NULL` or length is `0`<br/>Message queue is full |

0 commit comments

Comments
 (0)