zmq.rs Documentation

zmq.rs is a native Rust implementation of ZeroMQ designed to leverage Rust's async ecosystem. It provides a high-performance asynchronous messaging library that implements the ZMTP protocol.

Note: This implementation does not currently cover the full ZeroMQ feature set.

Supported Transport Types

• TCP
• IPC (Unix only)

Supported Socket Patterns

• Request/Response: REQ, REP, DEALER, ROUTER
• Publish/Subscribe: PUB, SUB, XPUB, XSUB
• Pipeline: PUSH, PULL

When running benchmarks, use a stable and searchable Run ID format to allow for quick human scanning. The recommended pattern is:

<host>-<profile>-<candidate-sha>-<YYYYMMDDTHHMMSSZ>

Examples:

• macbook-standard-16ae7d1-20260514T190000Z
• c7g-4xlarge-standard-16ae7d1-20260514T190000Z

Note that the manifest.json file within the run directory already captures detailed metadata including git SHAs, tool versions, OS, CPU metadata, profile, transports, implementations, runtimes, and OMQ revision.

The zeromq crate supports both tokio and async-std runtimes. To facilitate compatibility, the crate provides async_helpers.

While async_helpers is available to help bridge the two runtimes, most users do not need to use it. Instead, you should use the standard entry point macros for your chosen runtime:

• For tokio: Use #[tokio::main]
• For async-std: Use #[async_std::main]

When reporting performance results in GitHub discussions or Pull Request comments, include the following information to ensure reproducibility and clarity:

1. The summary.md table.
2. The candidate git SHA (found in manifest.json).
3. The host CPU/OS (found in manifest.json).
4. The archive location and its SHA256 checksum.
5. Any non-default flags used during the run (e.g., --toolchain).

For distributed agent runs, it is recommended to store archives outside the repository (e.g., GitHub Actions artifacts or an S3 bucket).

You can run any example provided in the repository using the standard cargo run command. By default, examples use the tokio asynchronous runtime.

To run an example with the default tokio runtime:

cargo run --example <example_name>

To run an example using the async-std runtime instead, you must disable the default features and explicitly enable the async-std-runtime feature:

cargo run --example <example_name> --no-default-features --features async-std-runtime

The library supports three different async runtimes, which are selected using Cargo feature flags. tokio is the default runtime.

To use a different runtime, you must disable the default features and explicitly select the desired runtime feature.

• tokio: Default runtime (enabled via tokio-runtime).
• async-std: Enabled via async-std-runtime.
• async-dispatcher: Enabled via async-dispatcher-runtime.

To run benchmarks on your local machine, you must first install the libzmq development headers for your operating system.

• Linux: Use apt-get to install libzmq3-dev.
• macOS: Use brew to install zeromq.

After installation, you can run benchmarks using cargo bench.

# Linux
sudo apt-get install libzmq3-dev

# macOS
brew install zeromq

Performance results are stored in target/perf-runs/<run-id>/. To share these results across machines, pull requests, or issue comments, use the package_perf_run.py script to create a compressed archive.

By default, the archive includes manifest.json, results.jsonl, summary.md, and summary.html. If you need raw Criterion directories or external benchmark outputs for debugging, use the --include-artifacts flag, but note that these archives will be significantly larger.

The Endpoint enum currently supports the following transport types:

• TCP: Requires a Host and a Port (u16). Formatted as tcp://<host>:<port>. IPv6 addresses are wrapped in brackets in the string representation, e.g., tcp://[::1]:34567.
• IPC: Requires an optional PathBuf. Formatted as ipc://<path>.