Note that the library is experimental, and the API is subject to change. See Implementation status for more information.
Kzmq is a Kotlin multi-platform ZeroMQ library. It supports four backend engines:
- CIO, a pure Kotlin coroutine-based implementation (using
ktor-network
andktor-io
), - JeroMQ, a pure Java implementation of ZeroMQ,
- ZeroMQjs, a Node.JS addon implementation of ZeroMQ,
- Libzmq, the main native implementation of ZeroMQ.
Here is how you might implement a server that prints the messages it receives and responds to them with "Hello, world!":
import kotlinx.coroutines.*
import org.zeromq.*
suspend fun main() = coroutineScope {
// Create a ZeroMQ context (with an auto-discoverd engine)
Context().use { context ->
// Socket to talk to clients
val socket = context.createReply().apply {
bind("tcp://localhost:5555")
}
socket.use {
while (isActive) {
// Suspend until a message is received
val message = it.receive()
// Print the message
println(message.singleOrThrow().decodeToString())
// Send a response
it.send(Message("Hello, world!".encodeToByteArray()))
}
}
}
}
For now, you can look at the test suite.
You can generate the Kdoc documentation by running the dokkaHtmlMultiModule
gradle task.
Kzmq supports four backend engines:
- CIO, a pure Kotlin coroutine-based implementation (using
ktor-network
andktor-io
), - JeroMQ, a pure Java implementation of ZeroMQ,
- ZeroMQjs, a Node.JS addon implementation of ZeroMQ,
- Libzmq, the main native implementation of ZeroMQ.
The tables below might help you choose an engine depending on your needs.
We support auto-discovery of engines. See Using in your projects for more information.
Target/Engine | CIO | JeroMQ | ZeroMQjs | Libzmq |
---|---|---|---|---|
JVM | Y | Y | ||
Node.JS | Y | |||
Native | Y | Y |
Transport/Engine | CIO | JeroMQ | ZeroMQjs | Libzmq |
---|---|---|---|---|
tcp:// |
Y | Y | Y | Y |
ipc:// |
Y (♭) | Y | Y | |
inproc:// |
Y (♯) | Y (♯) | Y (♯) | Y (♯) |
(♭) Supported on Native. Requires JVM >= 16 for the JVM target.
(♯) Each engine only supports the inproc
transport with itself.
Protocol/Engine | CIO | JeroMQ | ZeroMQjs | Libzmq |
---|---|---|---|---|
ZMTP 3.0 | Y | Y | Y | Y |
ZMTP 3.1 | Y (♭) | Y (♭) |
(♭) New ZMTP 3.1 sockets are not yet supported
Note that the library is experimental, and the API is subject to change.
Engine | CIO | JeroMQ | ZeroMQjs | Libzmq |
---|---|---|---|---|
Status | Experimental | Experimental | Experimental | Work in progress |
Note that the library is experimental, and the API is subject to change.
This library is published to Maven Central.
- First, add the Maven Central repository if it is not already there:
repositories {
mavenCentral()
}
- Add the API package to your
commonMain
source-set dependencies (or to a particular target source-set dependencies, if you only need it on that target):
kotlin {
sourceSets {
val commonMain by getting {
dependencies {
implementation("org.zeromq:kzmq-core:0.1.0")
}
}
}
}
- Then add one or more engine packages to their corresponding source-sets.
In case you are lost, you can read more about multiplatform projects.
The CIO engine supports only the JVM and native targets.
Add the CIO engine package to your commonMain
source-set dependencies
(or to a particular target source-set dependencies):
kotlin {
sourceSets {
val commonMain by getting {
dependencies {
implementation("org.zeromq:kzmq-cio:0.1.0")
}
}
}
}
The JeroMQ engine supports only the JVM targets.
Add the JeroMQ engine package to your jvmMain
source-set dependencies:
kotlin {
sourceSets {
val jvmMain by getting {
dependencies {
implementation("org.zeromq:kzmq-jeromq:0.1.0")
}
}
}
}
The ZeroMQ.js engine supports only the Node.js targets.
Add the ZeroMQ.js engine package to your jsMain
source-set dependencies:
kotlin {
sourceSets {
val jsMain by getting {
dependencies {
implementation("org.zeromq:kzmq-zeromqjs:0.1.0")
}
}
}
}
The Libzmq engine supports only the native targets.
Add the Libzmq engine package to your nativeMain
source-set dependencies:
kotlin {
sourceSets {
val nativeMain by getting {
dependencies {
implementation("org.zeromq:kzmq-libzmq:0.1.0")
}
}
}
}
In order to build for native targets, you need to have the development package for libzmq
(e.g. zeromq-devel
on Fedora, or libzmq3-dev
on Ubuntu).