omq 0.5.1

Pure Rust OMQ/ZeroMQ. Facade over omq-compio (default) or omq-tokio. Wire-compatible with libzmq.
Documentation 
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89

//! Pure-Rust ZeroMQ. Wire-compatible with libzmq.
//!
//! `omq` is a thin facade that re-exports a backend chosen at build
//! time. The default `compio-backend` feature pulls in
//! [`omq-compio`](https://crates.io/crates/omq-compio), a
//! single-thread io_uring (Linux), IOCP (Windows), or kqueue (macOS)
//! runtime; the alternative
//! `tokio-backend` feature swaps in
//! [`omq-tokio`](https://crates.io/crates/omq-tokio), a multi-thread
//! mio/tokio runtime. The two are mutually exclusive — enabling
//! both is a compile error. The public `Socket` / `Endpoint` /
//! `Options` / `Message` API is identical either way, verified in
//! lockstep by per-backend `coverage_matrix` test suites plus a
//! cross-runtime `interop_compio` ZMTP-on-the-wire test in the
//! repository.
//!
//! # Example
//!
//! ```no_run
//! # async fn run() -> Result<(), Box<dyn std::error::Error>> {
//! use omq::{Endpoint, Message, Options, Socket, SocketType};
//!
//! let pull = Socket::new(SocketType::Pull, Options::default());
//! pull.bind("tcp://127.0.0.1:5555".parse()?).await?;
//!
//! let push = Socket::new(SocketType::Push, Options::default());
//! push.connect("tcp://127.0.0.1:5555".parse()?).await?;
//! push.send(Message::single("hi")).await?;
//!
//! let m = pull.recv().await?;
//! assert_eq!(m.part_bytes(0).unwrap(), &b"hi"[..]);
//! # Ok(()) }
//! ```
//!
//! # Picking a backend
//!
//! ```toml
//! # Default: compio (io_uring on Linux, IOCP on Windows, kqueue on
//! # macOS). Single-thread by design — instantiate one runtime per
//! # core for thread-per-core.
//! [dependencies]
//! omq = "0"
//!
//! # Alternative: tokio (multi-thread by default).
//! [dependencies]
//! omq = { version = "0", default-features = false, features = ["tokio-backend"] }
//! ```
//!
//! # Cargo features
//!
//! All optional, all opt-in:
//!
//! - `compio-backend` — (default) compio runtime backend.
//! - `tokio-backend` — tokio runtime backend (mutually exclusive with compio).
//! - `curve` — CURVE encrypted-handshake mechanism (RFC 26).
//! - `blake3zmq` — omq-native AEAD (X25519 + BLAKE3 + ChaCha20).
//! - `lz4` — `lz4+tcp://` compression transport.
//! - `zstd` — `zstd+tcp://` compression transport.
//! - `priority` — strict per-pipe priority on `Socket::connect_with`.
//!
//! See [BENCHMARKS.md](https://github.com/paddor/omq.rs/blob/main/BENCHMARKS.md)
//! for throughput / latency tables.

#![cfg_attr(docsrs, feature(doc_cfg))]

#[cfg(all(feature = "compio-backend", feature = "tokio-backend"))]
compile_error!(
    "omq features `compio-backend` and `tokio-backend` are mutually \
     exclusive; pick exactly one"
);

#[cfg(not(any(feature = "compio-backend", feature = "tokio-backend")))]
compile_error!(
    "omq needs exactly one backend: enable `compio-backend` (default) \
     or `tokio-backend`"
);

#[cfg(feature = "compio-backend")]
pub use omq_compio::*;

#[cfg(feature = "tokio-backend")]
pub use omq_tokio::*;

/// Name of the active backend. Useful for runtime version banners.
pub const BACKEND: &str = if cfg!(feature = "compio-backend") {
    "compio"
} else {
    "tokio"
};