Crate arzmq 

Asynchronous Rust bindings for 0MQ (arzmq)

Documentation

About

The arzmq crate provides bindings for the libzmq library from the ZeroMQ project. The API exposed by arzmq should be safe (in the usual Rust sense), but it follows the C API closely, so it is not very idiomatic.

There are feature flags for enabling a builder interface for contexts and sockets as well as a feature flag for enabling 0MQ’s draft-api available.

Compatibility

The aim of this project is to track latest zmq releases as close as possible.

Usage

arzmq is a pretty straight forward port of the C API into Rust:

use std::thread;

use arzmq::prelude::{Context, RequestSocket, ReplySocket, SendFlags, Receiver, RecvFlags, Sender};

fn run_reply(context: &Context, endpoint: &str) {
    let socket = ReplySocket::from_context(context).unwrap();
    socket.bind(endpoint).unwrap();
    
    thread::spawn(move || {
       while socket.recv_msg(RecvFlags::DONT_WAIT).is_err() {}
    });
}

fn main() {
    let ctx = Context::new().unwrap();
    
    run_reply(&ctx, "tcp://127.0.0.1:1234");

    let socket = RequestSocket::from_context(&ctx).unwrap();
    socket.connect("tcp://127.0.0.1:1234").unwrap();
    let _ = socket.send_msg("hello world!", SendFlags::DONT_WAIT);
}

You can find more usage examples in https://github.com/mgaertne/arzmq/tree/master/examples.

Crate features

This crate offers to compile the underlying libzmq with different configurations based on your needs by enabling or disabling cargo features. In addition to that, there are several Rust-related features that you can enable or diable.

Below there is a brief overview, with steps for Windows, Linux, and MacOs for the underlying dependencies for libzmq. Other platforms might work as well, but are untested at this point. Let me know if you made experiences on unmentioned platforms, so that I can provide hints for others in similar situations.

Rust-related features

The main Rust-related features are builder, and futures. builder is enabled by default.

builder

Enables a builder API for the variouos socket types as well as the 0MQ context. Enabled by default.

futures

Enables async futures for the different send and receive traits to use with an async runner like tokio, smol, and the futures executor crate.

libzmq-related features

libzmq offers multiple configurations to include. As it was hard for me to figure out the different compilation options for me to finally succeed incorporating the different features in libzmq, I decided to include the approaches I ended up with here, so that others may be able to reproduce them.

With the exceptions of draft-api and vmci you will have to install additional libraries on your system for the feature to work. By default, the compilation will succeed if the pre-requisites are not in place, but you will not be able to use the functionality. For convenience, that build script generates cfg-checks that you can use to check libzmq capabilities, i.e.:

#[cfg(zmq_has = "curve")]
fn only_working_when_curve_is_enabled_and_working() { ... }

will only compile in the function when curve is enabled and working.

draft-api

Enables all the functionality from the draft-api. This includes various socket types like Client, Peer, as well as several socket and context options. There are no external dependendencies necessary beyond that.

CURVE

CURVE authoritzation is provided through libsodium that can be installed through a package on all systems.

Linux

On Linux, you will have to install the libsodium-dev package through your package manager, i.e.

sudo apt-get install libgsodium-dev

Library locations will be gathered through pkg-config and linked staticallyy to the underlying libzmq library.

MacOS

On MacOS, libsodium can be installed via package managers like homebrew:

brew install libsodium

Library locations will be gathered through pkg-config and linked to the underlying libzmq library.

Windows

On Windows, you need to install libsodium through vcpkg.

vcpkg install --triplet "x64-windows-md" libsodium

Library locations will be gathered through vcpkg and linked statically to the underlying libzmq library.

GSS API

GSS API authoritzation is provided through Kerberos. Linux and Windows systems have an implementation that can be installed. MacOS ships with the Kerberos framework, that you will have to configure.

Linux

On Linux, you will have to install the libgssapi-krb5 package through your package manager, i.e.

sudo apt-get install libgssapi-krb5

Library locations will be gathered through pkg-config and linked staticallyy to the underlying libzmq library.

MacOS

On MacOS, the built-in Kerberos.Framework can be used, but you have to tell the build process about it by setting the following environment variables:

export SYSTEM_DEPS_GSSAPI_LIB_FRAMEWORK=Kerberos
export SYSTEM_DEPS_GSSAPI_NO_PKG_CONFIG=1

Library locations will be gathered through the provided Framework and linked staticallyy to the underlying libzmq library.

Windows

On Windows, you need to install krb5 through vcpkg.

vcpkg install krb5

Library locations will be gathered through vcpkg and linked dynamically to the underlying libzmq library.

PGM

PGM is provided through the openpgm project. The latest openpgm version will be built during the build process, if the feature PGM is enabled.

NACK-Oriented Reliable Multicast (NORM)

NORM is provided through the NORM project. The latest NORM version will be built during the build process, if the feature norm is enabled.

vmci

Enables the VMware socket types for connecting to a virtual machine. There are no external dependendencies necessary beyond that as the functionality can be compiled in from a simple header file on all platforms.

Modules

auth

0MQ authentification mechanisms

context

0MQ context

message

0MQ messages

prelude

security

0MQ security mechanisms

socket

0MQ sockets

Enums

Capability

0MQ capabilities for use with the has_capability() function.

ZmqError

0MQ error codes

Functions

has_capability

check a 0MQ capability

proxy

Start built-in 0MQ proxy

version

Return the current zeromq version, as (major, minor, patch).

Type Aliases

ZmqResult

0MQ specific result type