Home

Awesome

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.

Unit Tests Examples

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.

zig fetch --save=zzmq 'https://github.com/nine-lives-later/zzmq/archive/refs/tags/v0.2.2-zig0.13.tar.gz'

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

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

exe.root_module.addImport("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:

BranchZig VersionComment
mainZig v0.13.xThe latest unreleased version for Zig 0.13.
zig-0.12Zig v0.12.xThe latest unreleased version for Zig 0.12.
zig-0.11Zig v0.11.xThe 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

License

Published under the Mozilla Public License 2.0.

Feel free to also see the ZeroMQ licensing terms.