Zig Binding for ZeroMQ

This Zig library provides a ZeroMQ client.

It is implemented based on the C API of libzmq. The interface is highly inspired by CZMQ and goczmq.

It was originally based on the "High-level C Binding for ZeroMQ" (CZMQ), but later moved to using libzmq directly, to provide zero-copy message support.

Important

The library is currently still work in progress!!

Please feel free to open pull requests for features needed.

Using the Library

Minimal Example

This repository holds various example within the examples folder. Please feel free to also have a look at the various unit tests in this library (esp. ZSocket).

Running the server (also see full example):

const zzmq = @import("zzmq");

var context = try zzmq.ZContext.init(allocator);
defer context.deinit();

var socket = try zzmq.ZSocket.init(zzmq.ZSocketType.Pair, &context);
defer socket.deinit();

try socket.bind("tcp://127.0.0.1:*");

std.log.info("Endpoint: {s}", .{try socket.endpoint()});

// send a message
var message = try zzmq.ZMessage.initUnmanaged(data, null);
defer message.deinit();

try socket.send(&message, .{});

Running the client (also see full example):

const zzmq = @import("zzmq");

var context = try zzmq.ZContext.init(allocator);
defer context.deinit();

var socket = try zzmq.ZSocket.init(zzmq.ZSocketType.Pair, &context);
defer socket.deinit();

const endpoint = try std.fmt.allocPrint(allocator, "tcp://127.0.0.1:{}", .{port});
defer allocator.free(endpoint);

try socket.connect(endpoint);

// receive a message
var message = try socket.receive(.{});
defer message.deinit();

const data = try message.data();

Adding to build process

Determine the specific release tag of the library to use in the project.

Add to the build.zig.zon file, e.g. for Zig 0.11:

.{
    .dependencies = .{
        .zzmq = .{
            .url = "https://github.com/nine-lives-later/zzmq/archive/refs/tags/v0.1.0-zig0.11.tar.gz",
            .hash = "122080e22e9823dc0a4567c71553c4884978a33877c9b3d46f4594ca5f299d534f9b",
        },
    },
}

Note: Should the hash be wrong, remove the .hash field and the compiler error will show the correct value. Starting with Zig 0.12 you can also use zig fetch zzmq <url>.

It is also required to add it to the build.zig file:

const zzmq = b.dependency("zzmq", .{
    .target = target,
    .optimize = optimize,
});

// Note: starting with zig 0.12 the function will be 
//       `exe.root_module.addImport` instead of `exe.addModule`
exe.addModule("zzmq", zzmq.module("zzmq"));

exe.linkSystemLibrary("zmq");
exe.linkLibC();

Installing local dependencies

Installing libzmq development library version 4.1 or higher is also required:

# Building on Ubuntu, PoP_OS, ZorinOS, etc.
sudo apt install libzmq5-dev

# Running on Ubuntu, PoP_OS, ZorinOS, etc.
sudo apt install libzmq5

See the unit test Dockerfile on how to install it into an Alpine Docker image.

To retrieve the version of the libzmq library actually being used, call ZContext.version().

Contributing

Zig Version Branches

There are branches for the supported Zig versions:

Branch	Zig Version	Status	Comment
main	Zig v0.11.x		The latest unreleased version for Zig 0.11.

Please use a specific release tag for including the library into your project.

Testing

The library can be tested locally by running: zig build test.

Contributors

Implementation done by Felix Kollmann.

Inspired by CZMQ and goczmq.

License

Published under the Mozilla Public License 2.0.

• Static linking is allowed.
• Safe for use in close-source applications.
• You do not need a commercial license.

Feel free to also see the ZeroMQ licensing terms.