zmq

ZeroMQ bindings for Kit via czmq - high-performance messaging for distributed applications

Files

Dependencies

No Kit package dependencies.

Native dependencies are required when building or running compiled programs:

The package requires Kit ffi and net capabilities.

Installation

kit add gitlab.com/kit-lang/packages/kit-zmq.git

Usage

import Kit.Zmq as ZMQ

main = fn =>
  endpoint = "inproc://kit-zmq-readme"

  # Bind the receiver first for inproc sockets.
  match ZMQ.pull endpoint
    | Err e -> println "Failed to create receiver: ${show e}"
    | Ok receiver ->
      defer ZMQ.close receiver
      ZMQ.set-linger receiver 0
      ZMQ.set-recv-timeout receiver 1000

      match ZMQ.push endpoint
        | Err e -> println "Failed to create sender: ${show e}"
        | Ok sender ->
          defer ZMQ.close sender
          ZMQ.set-linger sender 0
          ZMQ.set-send-timeout sender 1000

          match ZMQ.send sender "work item"
            | Err e -> println "Send failed: ${show e}"
            | Ok _ ->
              message = ZMQ.recv receiver
              println "Received: ${message}"

main

The high-level API includes constructors for req, rep, pub, sub, push,

pull, dealer, router, and pair sockets. It also provides string

messaging helpers (send, send-more, recv, recv-nowait), lifecycle

management (close), endpoint management (bind, connect, get-endpoint),

subscription helpers, socket options, and typed ZMQError variants.

Supported ZeroMQ patterns include REQ/REP, PUB/SUB, PUSH/PULL, DEALER/ROUTER,

and PAIR. The wrapper exposes string-based messaging over TCP, IPC, and inproc

transports through czmq.

Development

Running Examples

Because this package uses C FFI, run examples as compiled programs:

kit build examples/simple-test.kit -o simple-test
./simple-test

Other examples demonstrate common socket patterns:

kit build examples/req-rep-server.kit -o server
kit build examples/req-rep-client.kit -o client
kit build examples/pub-sub-publisher.kit -o publisher
kit build examples/pub-sub-subscriber.kit -o subscriber
kit build examples/push-pull-worker.kit -o worker
kit build examples/push-pull-ventilator.kit -o ventilator

Running Tests

Run the test suite:

kit test

Run the test suite with coverage:

kit test --coverage

The tests cover module imports, error types, constants, and public API

availability. Runtime socket behavior requires the native czmq and ZeroMQ

libraries to be installed.

Running kit dev

Run the standard development workflow (format, check, test):

kit dev

This will:

1. Format and check source files in src/
2. Run tests in tests/ with coverage

Generating Documentation

Generate API documentation from doc comments:

kit doc

Note: Kit sources with doc comments (##) will generate HTML documents in docs/*.html

Cleaning Build Artifacts

Remove generated files, caches, and build artifacts:

kit task clean

Note: Defined in kit.toml.

Local Installation

To install this package locally for development:

kit install

This installs the package to ~/.kit/packages/@kit/zmq/, making it available for import as Kit.Zmq in other projects.

License

This package is released under the MIT License - see LICENSE for details.

ZeroMQ is distributed under the Mozilla Public License 2.0.

Exported Functions & Types

ZMQError

ZeroMQ error type for typed error handling.

zmq-pair

PAIR socket type constant.

zmq-pub

PUB socket type constant.

zmq-sub

SUB socket type constant.

zmq-req

REQ socket type constant.

zmq-rep

REP socket type constant.

zmq-dealer

DEALER socket type constant.

zmq-router

ROUTER socket type constant.

zmq-pull

PULL socket type constant.

zmq-push

PUSH socket type constant.

zmq-xpub

XPUB socket type constant.

zmq-xsub

XSUB socket type constant.

zmq-stream

STREAM socket type constant.

req

Creates a REQ (request) socket and connects to the endpoint.

REQ sockets are used in request-reply patterns. They send a request and then wait for a reply. Must alternate between send and receive.

Parameters:

Returns:

NonEmptyString -> Result Ptr ZMQError

match ZMQ.req "tcp://localhost:5555"
| Ok socket ->
  ZMQ.send socket "Hello"
  reply = ZMQ.recv socket
  ZMQ.close socket
| Err e -> print "Failed: ${show e}"

rep

Creates a REP (reply) socket and binds to the endpoint.

REP sockets are used in request-reply patterns. They receive a request and then send a reply. Must alternate between receive and send.

Parameters:

Returns:

NonEmptyString -> Result Ptr ZMQError

pub

Creates a PUB (publish) socket and binds to the endpoint.

PUB sockets broadcast messages to all connected SUB subscribers. Messages are dropped if no subscribers are connected.

Parameters:

Returns:

NonEmptyString -> Result Ptr ZMQError

sub

Creates a SUB (subscribe) socket and connects to the endpoint.

SUB sockets receive messages from PUB publishers. By default, subscribes to all messages (empty string filter).

Parameters:

Returns:

NonEmptyString -> String -> Result Ptr ZMQError

push

Creates a PUSH socket and connects to the endpoint.

PUSH sockets send messages in a pipeline pattern. Messages are round-robin distributed to connected PULL sockets.

Parameters:

Returns:

NonEmptyString -> Result Ptr ZMQError

pull

Creates a PULL socket and binds to the endpoint.

PULL sockets receive messages in a pipeline pattern. Messages are fair-queued from connected PUSH sockets.

Parameters:

Returns:

NonEmptyString -> Result Ptr ZMQError

dealer

Creates a DEALER socket and connects to the endpoint.

DEALER sockets are advanced request-reply sockets that can send multiple requests without waiting for replies.

Parameters:

Returns:

NonEmptyString -> Result Ptr ZMQError

router

Creates a ROUTER socket and binds to the endpoint.

ROUTER sockets are advanced reply sockets that can handle multiple clients asynchronously.

Parameters:

Returns:

NonEmptyString -> Result Ptr ZMQError

pair

Creates a PAIR socket and connects/binds to the endpoint.

PAIR sockets are for exclusive one-to-one communication between two peers.

Parameters:

Returns:

NonEmptyString -> Result Ptr ZMQError

send

Sends a string message on a socket.

Parameters:

Returns:

Ptr -> String -> Result Unit ZMQError

ZMQ.send socket "Hello, World!"

send-more

Sends a string message with MORE flag (for multipart messages).

Parameters:

Returns:

Ptr -> String -> Result Unit ZMQError

recv

Receives a string message from a socket (blocking).

Parameters:

Returns:

Ptr -> String

message = ZMQ.recv socket
print "Received: ${message}"

recv-nowait

Receives a string message from a socket (non-blocking).

Parameters:

Returns:

Ptr -> String

close

Closes and destroys a socket.

Parameters:

Ptr -> Unit

ZMQ.close socket

bind

Binds a socket to an additional endpoint.

Parameters:

Returns:

Ptr -> NonEmptyString -> Result Int ZMQError

connect

Connects a socket to an additional endpoint.

Parameters:

Returns:

Ptr -> NonEmptyString -> Result Unit ZMQError

subscribe

Subscribes to messages matching a prefix (SUB sockets only).

Parameters:

Ptr -> String -> Unit

unsubscribe

Unsubscribes from messages matching a prefix (SUB sockets only).

Parameters:

Ptr -> String -> Unit

set-recv-timeout

Sets the receive timeout in milliseconds.

Parameters:

Ptr -> Int -> Unit

set-send-timeout

Sets the send timeout in milliseconds.

Parameters:

Ptr -> Int -> Unit

set-linger

Sets the linger period for socket shutdown.

Parameters:

Ptr -> Int -> Unit

set-identity

Sets the socket identity (for DEALER/ROUTER sockets).

Parameters:

Ptr -> NonEmptyString -> Unit

type-str

Gets the socket type as a string.

Parameters:

Returns:

Ptr -> String

get-endpoint

Gets the last bound endpoint.

Parameters:

Returns:

Ptr -> String