> For the complete documentation index, see [llms.txt](https://docs.rumi.systems/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.rumi.systems/performance/benchmark-suite/modules/messaging-module.md).

# Messaging Module

The Messaging module benchmarks the SMA (Simple Messaging Architecture) layer, which provides publish-subscribe messaging abstractions on top of the link layer.

## Overview

The SMA layer adds messaging semantics including:

* Channel-based pub/sub
* Message routing
* Quality of Service (QoS) levels
* Multicast support

This benchmark measures the overhead of these abstractions compared to raw link layer performance.

## Test Programs

### Sender

**Class**: `com.neeve.perf.sma.Sender`

Publishes messages to a channel.

### Receiver

**Class**: `com.neeve.perf.sma.Receiver`

Subscribes to and receives messages from a channel.

## Command-Line Parameters

### Common Parameters (Both Sender and Receiver)

| Short | Long                   | Required | Default       | Description                             |
| ----- | ---------------------- | -------- | ------------- | --------------------------------------- |
| `-u`  | `--username`           | Yes      | -             | Bus binding username                    |
| `-d`  | `--descriptor`         | Yes      | -             | Messaging bus connection descriptor     |
| `-c`  | `--testCount`          | No       | 3000000       | Number of messages (< 1 for unlimited)  |
| `-r`  | `--testRate`           | Yes      | 100000        | Send rate (< 1 for unlimited)           |
| `-k`  | `--channelKey`         | No       | null          | Channel key                             |
| `-f`  | `--channelFilter`      | No       | null          | Channel filter                          |
| `-q`  | `--channelQos`         | No       | Guaranteed    | Delivery QOS (Guaranteed or BestEffort) |
| `-e`  | `--encoding`           | No       | rumi.protobuf | Encoding type                           |
| `-i`  | `--printIntervalStats` | No       | false         | Output stats at periodic intervals      |

### Sender-Specific Parameters

| Short | Long                    | Default | Description                                     |
| ----- | ----------------------- | ------- | ----------------------------------------------- |
| `-p`  | `--dontPopulateMessage` | false   | Don't populate message content (timestamp only) |
| `-a`  | `--cpuAffinityMask`     | null    | CPU affinity mask for sending thread            |

## Running Benchmarks

### Basic Pub/Sub Test

**On Receiver Machine**:

```bash
$JAVA_HOME/bin/java -cp "libs/*" com.neeve.perf.sma.Receiver \
  -u receiver \
  -d "tcp://0.0.0.0:5000" \
  -k test.channel \
  -c 1000000 \
  -r 100000
```

**On Sender Machine**:

```bash
$JAVA_HOME/bin/java -cp "libs/*" com.neeve.perf.sma.Sender \
  -u sender \
  -d "tcp://receiver.example.com:5000" \
  -k test.channel \
  -c 1000000 \
  -r 100000
```

### Pub/Sub Test Over MQTT

The messaging benchmark is provider agnostic: the bus binding is selected by the scheme of the `-d` descriptor at runtime. The distribution bundles the MQTT binding, so an `mqtt://` descriptor works out of the box against any MQTT 5 broker.

Because the MQTT binding supports `BestEffort` delivery only, MQTT runs must pass `-q BestEffort`. The default `-q Guaranteed` is rejected by the binding.

**On the Receiver**:

```bash
$JAVA_HOME/bin/java -cp "libs/*" com.neeve.perf.sma.Receiver \
  -u receiver \
  -d "mqtt://broker.example.com:1883" \
  -q BestEffort \
  -k test/channel \
  -c 1000000 \
  -r 100000
```

**On the Sender**:

```bash
$JAVA_HOME/bin/java -cp "libs/*" com.neeve.perf.sma.Sender \
  -u sender \
  -d "mqtt://broker.example.com:1883" \
  -q BestEffort \
  -k test/channel \
  -c 1000000 \
  -r 100000
```

{% hint style="warning" %}
MQTT QoS 0 does not retain or queue messages for a subscriber that is not currently connected, so start the receiver and let its subscription establish before starting the sender. Messages published before the receiver subscribes are lost.
{% endhint %}

## Interpreting Results

The SMA layer adds minimal overhead over the link layer:

* **Link Layer**: \~10µs
* **SMA Layer**: \~12-15µs
* **Overhead**: \~2-5µs for routing and QoS

## Quality of Service

### Guaranteed Delivery

Ensures all messages are delivered in order:

```bash
-q Guaranteed
```

**Characteristics**:

* Reliable delivery
* In-order processing
* Flow control
* Slightly higher latency

### Best Effort

Allows message loss for lower latency:

```bash
-q BestEffort
```

**Characteristics**:

* Lower latency
* Higher throughput
* May lose messages under load

## Next Steps

* Review [Link Module](/performance/benchmark-suite/modules/link-module.md) for transport layer benchmarks
* Review [AEP Module](/performance/benchmark-suite/modules/aep-module.md) for end-to-end benchmarks
* Return to [Benchmark Suite](/performance/benchmark-suite.md) for other modules