Rust ZeroMQ bindings.
About
The zmq crate provides bindings for the libzmq library from the ZeroMQ project. The API exposed by zmq should be safe (in the usual Rust sense), but it follows the C API closely, so it is not very idiomatic. Also, support for libzmq API in "draft" state is considered out-of-scope for this crate; this includes currently, as of libzmq 4.3.3:
- Newer, thread-safe socket types, such as
ZMQ_CLIENTandZMQ_SERVER. - The "poller" API.
For a more modern, idiomatic approach to libzmq bindings, including draft API features, have a look at libzmq-rs.
Compatibility
The current 0.9 release series requires libzmq 4.1 or newer. New release series of zmq may require newer libzmq versions.
Regarding the minimum Rust version required, zmq is CI-tested on current stable, beta and nightly channels of Rust. Additionally, it is made sure that the code still compiles on Rust 1.32.0. However, no tests are run for that build, so use zmq on older Rust versions on your own risk. It is however likely that it will just work anyways.
Installation
rust-zmq is available from crates.io. Users should add this to their Cargo.toml file:
[dependencies]
zmq = "0.9"
As rust-zmq is a wrapper around libzmq, you need a build of libzmq version 4.1 or newer, before attempting to build the zmq crate. There are several options available:
Dynamic linking using pkg-config
This is probably the preferred method when you are running a recent Unix-like OS that has support for pkg-config. For example, on recent Debian-based distributions, you can use the following command to get the prerequiste headers and library installed:
apt install libzmq3-dev
If your OS of choice does not provide packages of a new-enough libzmq, you can install it from source; see https://github.com/zeromq/libzmq/releases, although in this case, you may prefer a vendored build, which automates that, see below.
The build normally uses pkg-config to find out about libzmq's location. If that is not available, the environment variable LIBZMQ_PREFIX (or alternatively, LIBZMQ_LIB_DIR and LIBZMQ_INCLUDE_DIR) can be defined to avoid the invocation of pkg-config.
Windows build
When building on Windows, using the MSCV toolchain, consider the following when trying to link dynamically against libzmq:
- When building
libzmqfrom sources, the library must be renamed tozmq.libfrom the auto namedlibzmq-v***-mt-gd-*_*_*.lib,libzmq.lib,libzmq-mt-*_*_*.lib, etc. - The folder containing the
*.dll(dynamic link library) referred to byzmq.libmust be accessible via the path for the session that invokes the Rust compiler. - The name of the
*.dllin question depends on the build system used forlibzmqand can usually be seen when openingzmq.libin a text editor.
Vendored build
Starting with the upcoming release 0.9.1 (or when building from current master), you can enable the vendored feature flag to have libzmq be built for you and statically linked into your binary crate. In your Cargo.toml, you can give users the option to do so using a dedicated feature flag:
[features]
vendored-zmq = ['zmq/vendored']
Cross-compilation
When you have a cross-compiled version of libzmq installed, you should be able to cross-compile rust-zmq, assuming a platform supporting pkg-config. For example, assuming you have libzmq compiled for the i686-pc-windows-gnu target installed in ~/.local-w32, the following should work:
PKG_CONFIG_PATH=$HOME/.local-w32/lib/pkgconfig \
PKG_CONFIG_ALLOW_CROSS=1 \
cargo build --target=i686-pc-windows-gnu --verbose
Cross compilation without pkg-config should work as well, but you need set LIBZMQ_PREFIX as described above.
Usage
rust-zmq is a pretty straight forward port of the C API into Rust:
fn main() {
let ctx = zmq::Context::new();
let socket = ctx.socket(zmq::REQ).unwrap();
socket.connect("tcp://127.0.0.1:1234").unwrap();
socket.send("hello world!", 0).unwrap();
}
You can find more usage examples in https://github.com/erickt/rust-zmq/tree/master/examples.
Contributing
Unless you explicitly state otherwise, any contribution intentionally submitted for inclusion in the work by you, as defined in the Apache-2.0 license, shall be dual licensed under the terms of both the Apache License, Version 2.0 and the MIT license without any additional terms or conditions.
See the contribution guidelines for what to watch out for when submitting a pull request.
![[feature] `Hash`able `SocketType`](https://avatars.githubusercontent.com/u/4098092?v=4)
18 Jan 2, 2023
14 Dec 7, 2022
95 Dec 29, 2022
26 Jan 13, 2023
56 Aug 22, 2021
155 Nov 12, 2022
1.6k Jan 7, 2023
98 Dec 12, 2022
115 Dec 15, 2022
1.8k Jan 6, 2023
18.7k Dec 30, 2022
157 Dec 30, 2022
7.6k Jan 7, 2023
371 Nov 18, 2022
84 Dec 4, 2022
134 Dec 11, 2022