embedmq - GitLite

KO | EN

gitlite — search

#javascript #python #hacktoberfest #react #typescript #android #linux #nodejs #java #kubernetes #security #mcp #ios #openai

embedmq

(★ 121)

A minimalist, zero-dependency inter-thread messaging API for ANY embedded project | 极简、零依赖，适用于任何嵌入式项目的跨线程通信API

File Explorer

Download Latest Version (.zip)

- - ci.yml
- - benchmark.png
- API.md
- API_CN.md
- BUILD.md
- BUILD_CN.md
- DESIGN.md
- DESIGN_CN.md
- basic.c
- basic_cpp.cpp
- benchmark.c
- embedmq.h
- embedmq.hpp
- - embedmq_pal.c
- - embedmq_pal.c
- - embedmq_pal.c
- embedmq_pal.h
- - CMakeLists.txt
  - FreeRTOSConfig.h
  - main.c
- embedmq.c
- embedmq_hash.c
- embedmq_internal.h
- embedmq_queue.c
- test_embedmq.c
- test_embedmq_cpp.cpp
.gitignore
AGENTS.md
CLAUDE.md
CMakeLists.txt
LICENSE
README.md
README_CN.md

# Installation Guide

1. Get the code

git clone https://github.com/w4ysonch/embedmq

Downloads the entire project code from GitHub to your computer.

cd embedmq

Moves into the project folder you just downloaded.

2. CMake

Medium Recommended

Prerequisites

Git Needed to download the project code from GitHub.
CMake The tool used to generate build configuration.
C/C++ 컴파일러 Windows needs Visual Studio (Community edition, free), macOS needs Xcode Command Line Tools, Linux needs the gcc/g++ package.

cmake -B build -DCMAKE_BUILD_TYPE=Release && cmake --build build && ./build/benchmark

Type this command into your terminal and run it.

cmake -B build && cmake --build build && ./build/test_embedmq

Type this command into your terminal and run it.

cmake -B build-none -DEMBEDMQ_PAL=none -DEMBEDMQ_BUILD_TESTS=OFF && cmake --build build-none

Type this command into your terminal and run it.

cmake -B build-frt -DEMBEDMQ_BUILD_FREERTOS_SIM=ON && cmake --build build-frt

Type this command into your terminal and run it.

✅ Check that an executable was created inside the build folder, then run it directly (e.g. ./build/app_name).

Pulled directly from this repo's README.

// repository documentation

Was this content helpful?

★ 0 (0 ratings)

<div align="center">

# embedmq

### A single API for thread-to-thread message dispatch — across Linux threads, RTOS tasks, and bare-metal superloops

[![Version](https://img.shields.io/github/v/release/w4ysonch/embedmq?color=blue&label=version)](https://github.com/w4ysonch/embedmq/releases)
[![Platform](https://img.shields.io/badge/platform-Linux%20%7C%20RTOS%20%7C%20bare--metal-lightgrey.svg)](https://raw.githubusercontent.com/w4ysonch/embedmq/main/)
![CI](https://github.com/w4ysonch/embedmq/actions/workflows/ci.yml/badge.svg)

**[中文 ->](README_CN.md)**

---

</div>

## Why embedmq?

In embedded systems, threads need to notify each other constantly: a sensor reads new data, WiFi connects, a button is pressed, a timer fires. With FreeRTOS, you end up hand-rolling a Queue struct for every pair of tasks. On bare metal, your superloop drowns in `if (flag1) ... if (flag2) ...`. On Linux, modules hold direct pointers to each other and a change in one ripples everywhere.

embedmq collapses all of this into 3 functions — `create`, `register`, `post`. You decide **who posts what** and **who handles what**. The library handles the queue, the mutex, the semaphore, and the dispatch.

- **Linux threads, no need for DBus** — Hardware monitor thread, network thread, config thread — each posts its own events, registers for the ones it cares about. One header + one PAL file, link `-lpthread`. Zero external deps, no heavy framework just for thread comms.

- **FreeRTOS tasks, no more hand-rolled Queues** — Your sensor task does one thing: `post("sensor.temp", &data, sizeof(data))`. Your UI task does one thing: `register("sensor.temp", on_temp, NULL)`. Neither knows the other's TaskHandle or queue handle.

- **Bare-metal superloops, no more `if (flag)` sprawl** — Timer ISR posts `"tick.10ms"`, button ISR posts `"button.press"`, ADC callback posts `"adc.done"`. Your main loop calls `embedmq_poll(q)` once to dispatch everything. No new flag → no new if-block in main.

- **One API, three platforms** — Linux uses pthread + POSIX semaphore. FreeRTOS uses counting semaphore + Task. Bare metal uses C11 atomic lock + `poll()`. Switch platforms by swapping one PAL file. Core code, public header, and calling convention stay identical.

- **Hash once, zero string ops at runtime** — A name is FNV-1a hashed to a `uint32_t` UUID at registration and inserted into a sorted array. Dispatch binary-searches integers. Cache the UUID and call `post_id()` in tight loops — the hot path has no string comparison, one semaphore op, one memcpy into the ring buffer.

- **Zero malloc after init** — `create_static()` places all internal state inside a caller-provided BSS buffer. After creation, the heap is untouched. Built for MCUs that forbid dynamic allocation past startup.

| vs | **embedmq** | DBus | ZeroMQ | hand-rolled queue |
|---|---|---|---|---|
| Dependencies | none | daemon + glib | libzmq | none |
| Scope | intra-process threads | cross-process | cross-network | intra-process |
| Platform | Linux / RTOS / bare-metal | Linux only | all | all |
| Runtime dispatch | **integer compare** | string | string | manual |
| Thread-safe post | ✅ built-in | ✅ | ✅ | manual |
| Zero heap | ✅ | ❌ | ❌ | manual |

embedmq is for **intra-process**, thread-to-thread message dispatch. It is not for cross-process IPC, network RPC, or single-threaded synchronous code.

---

## Quick start

```c
embedmq_t *q = embedmq_create(NULL);
embedmq_register(q, "battery.changed", on_battery, NULL);
embedmq_post(q, "battery.changed", &info, sizeof(info));
```

### Dynamic mode (Linux / heap available)

```c
#include "embedmq.h"

typedef struct { int level; float voltage; } battery_t;

static void on_battery(const void *data, size_t size, void *ctx)
{
    const battery_t *b = data;
    printf("battery: %d%% %.2fV\n", b->level, b->voltage);
}

int main(void)
{
    embedmq_t *q = embedmq_create(NULL);  /* NULL = use defaults */
    embedmq_register(q, "battery.changed", on_battery, NULL);

battery_t b = { .level = 85, .voltage = 4.05f };
    embedmq_post(q, "battery.changed", &b, sizeof(b));

embedmq_destroy(q);  /* blocks until all pending messages are dispatched */
}
```

### Static mode (zero heap — MCU / RTOS)

```c
#include "embedmq.h"

static embedmq_config_t cfg = {
    .queue_size   = 2048,
    .max_msg_size = 64,
    .max_handlers = 8,
};

static uint8_t mq_buf[4096]; /* size with embedmq_mem_size(&cfg) */
static embedmq_t *q;

void app_init(void)
{
    q = embedmq_create_static(mq_buf, sizeof(mq_buf), &cfg);
    embedmq_register(q, "sensor.update", on_sensor, NULL);
}

/* Thread-safe: call from any task */
void sensor_task(void)
{
    sensor_data_t d = read_sensor();
    embedmq_post(q, "sensor.update", &d, sizeof(d));
}
```

### Hot-path variant (skip the hash on every post)

```c
/* Hash once at startup, cache the UUID */
uint32_t uuid = embedmq_uuid("touch.point");

/* Tight loop — no string hashing */
while (reading) {
    touch_t t = read_touch();
    embedmq_post_id(q, uuid, &t, sizeof(t));
}
```

### No-OS / bare-metal (superloop-driven)

```c
/* Build with -DEMBEDMQ_PAL_NONE */
embedmq_t *q = embedmq_create(&cfg);
embedmq_register(q, "tick", on_tick, NULL);

while (1) {
    embedmq_post(q, "tick", NULL, 0);
    embedmq_poll(q);   /* drain all pending messages */
    sleep_until_next_tick();
}
```

### C++ wrapper (lambda + RAII)

```cpp
#include "embedmq.hpp"

embedmq::MQ q;

q.subscribe("battery.changed", [](const void *data, size_t size) {
    const auto *b = static_cast<const BatteryInfo *>(data);
    printf("level=%d\n", b->level);
});

q.publish("battery.changed", &info, sizeof(info));

// Hot path: cache UUID
uint32_t uuid = embedmq::MQ::uuid("battery.changed");
q.publish_id(uuid, &info, sizeof(info));

// Destructor calls embedmq_destroy() automatically (RAII)
```

---

## Architecture

### Dispatch flow

```mermaid
flowchart LR
    classDef producer fill:#2d6a4f,stroke:#52b788,color:#fff
    classDef buffer   fill:#1d3557,stroke:#457b9d,color:#fff
    classDef sync     fill:#7b2d8b,stroke:#c77dff,color:#fff
    classDef consumer fill:#6d3b47,stroke:#e07a5f,color:#fff
    classDef handler  fill:#3d405b,stroke:#81b29a,color:#fff

P1(["Producer A"]):::producer
    P2(["Producer B"]):::producer
    RB[/"Ring Buffer<br/>[uuid · len · payload]"/]:::buffer
    SEM(["Semaphore"]):::sync
    CT(["Consumer Thread"]):::consumer
    HT[/"Handler Table<br/>sorted by UUID"/]:::consumer
    H1(["Handler X"]):::handler
    H2(["Handler Y"]):::handler

P1 -- "embedmq_post()<br/>mutex + memcpy" --> RB
    P2 -- "embedmq_post_id()<br/>mutex + memcpy" --> RB
    P1 -- "sem_give" --> SEM
    P2 -- "sem_give" --> SEM
    SEM -- "sem_take<br/>(blocks)" --> CT
    RB -- "emq_ring_read()<br/>binary search" --> CT
    CT -- "dispatch" --> HT
    HT --> H1
    HT --> H2
```

### Static mode memory layout

```mermaid
block-beta
  columns 4
  A["struct embedmq_s<br/>(control block)"]:1
  B["handler table<br/>N × {uuid,fn,ctx}"]:1
  C["ring buffer<br/>queue_size bytes"]:1
  D["dispatch buf<br/>max_msg_size bytes"]:1

style A fill:#457b9d,stroke:#a8dadc,color:#fff
  style B fill:#52b788,stroke:#b7e4c7,color:#fff
  style C fill:#e07a5f,stroke:#f2cc8f,color:#fff
  style D fill:#81b29a,stroke:#b7e4c7,color:#fff
```

---

## Performance

Measured on x86-64 Linux, Release build, single producer + consumer:

| Benchmark | Result |
|---|---|
| `embedmq_post()` throughput | **~2.9M msgs/sec** |
| `embedmq_post_id()` throughput (UUID cached) | **~3.4M msgs/sec** |
| End-to-end latency avg (post → handler) | **~38 µs** |
| End-to-end latency min | **~9 µs** |
| `embedmq_uuid()` hash speed | **~45M hashes/sec** (~22 ns/hash) |

![benchmark](https://raw.githubusercontent.com/w4ysonch/embedmq/main/docs/images/benchmark.png)

```bash
cmake -B build -DCMAKE_BUILD_TYPE=Release && cmake --build build && ./build/benchmark
```

---

## API overview

```c
/* Create / destroy */
embedmq_t *embedmq_create(const embedmq_config_t *cfg);
embedmq_t *embedmq_create_static(void *mem, size_t mem_size, const embedmq_config_t *cfg);
size_t     embedmq_mem_size(const embedmq_config_t *cfg);
void       embedmq_destroy(embedmq_t *q);

/* Register handlers (do this at startup, before any posts) */
int embedmq_register(embedmq_t *q, const char *name, embedmq_handler_fn fn, void *ctx);

/* Post messages (thread-safe, non-blocking, any thread) */
int embedmq_post(embedmq_t *q, const char *name, const void *data, size_t size);
int embedmq_post_id(embedmq_t *q, uint32_t uuid, const void *data, size_t size);

/* Utilities */
uint32_t embedmq_uuid(const char *name);  /* stateless pure hash */
int      embedmq_poll(embedmq_t *q);      /* bare-metal superloop driver */
```

**Return codes:** `EMBEDMQ_OK (0)` · `EMBEDMQ_FULL (-2)` · `EMBEDMQ_EXIST (-4)` · `EMBEDMQ_INVAL (-5)`

**Configuration** (`embedmq_config_t`, pass `NULL` for defaults):

| Field | Default | Description |
|---|---|---|
| `queue_size` | 8192 | Total ring buffer bytes |
| `max_msg_size` | 1024 | Max payload per message |
| `max_handlers` | 64 | Max registered event names |
| `thread_priority` | 0 | Consumer thread priority (0 = OS default) |

> Full API docs (threading rules, lifecycle): **[docs/API.md](docs/API.md)** · Design notes: **[docs/DESIGN.md](docs/DESIGN.md)**

---

## Building

```bash
# Linux (default)
cmake -B build && cmake --build build && ./build/test_embedmq

# Bare-metal / no-OS
cmake -B build-none -DEMBEDMQ_PAL=none -DEMBEDMQ_BUILD_TESTS=OFF && cmake --build build-none

# FreeRTOS POSIX simulator test (auto-fetches FreeRTOS-Kernel)
cmake -B build-frt -DEMBEDMQ_BUILD_FREERTOS_SIM=ON && cmake --build build-frt
./build-frt/sim/freertos/test_embedmq_freertos
```

Without CMake: copy `src/embedmq.c`, `src/embedmq_hash.c`, `src/embedmq_queue.c`, and the matching `pal/<xxx>/embedmq_pal.c` into your project. Add `-Iinclude -Ipal` to compiler flags. Link `-lpthread` for the Linux PAL.

> Full build guide: **[docs/BUILD.md](docs/BUILD.md)**

---

## Platform support

| PAL | File | Notes |
|---|---|---|
| Linux | `pal/linux/embedmq_pal.c` | pthread + POSIX counting semaphore |
| FreeRTOS | `pal/freertos/embedmq_pal.c` | counting semaphore + task; continuously verified on the POSIX simulator in CI |
| Bare-metal | `pal/none/embedmq_pal.c` | C11 atomic spinlock; drive with `embedmq_poll()` |

> The FreeRTOS PAL verification covers semaphore wakeup, mutex, task create/exit, and dispatch correctness. It does not exercise real-hardware timing or ISR context.

---

## License

MIT