Crate zenoh 

Zenoh /zeno/ is a stack that unifies data in motion, data at rest, and computations. It elegantly blends traditional pub/sub with geo-distributed storage, queries, and computations, while retaining a level of time and space efficiency that is well beyond any of the mainstream stacks.

Components and concepts

The main Zenoh components and concepts are described below.

Session

The root element of the Zenoh API is the session. A session is created by the open function, which takes a config as an argument. The Session holds the runtime object, which maintains the connection to the Zenoh network.

The Zenoh protocol allows nodes to form a graph with an arbitrary topology, such as a mesh, a star, or a clique. There is a mode parameter in the config which specifies the role of the node in the topology: a peer, router or client. See WhatAmI for details.

Zenoh supports two paradigms of communication: publish/subscribe and query/reply. The entities that perform the communication (e.g., publishers, subscribers, queriers, and queryables) are declared by the session object.

Publish/Subscribe

In the publish/subscribe paradigm, data is produced by Publisher and consumed by Subscriber. See the pubsub API for details.

Query/Reply

In the query/reply paradigm, data is made available by Queryable and requested by Querier or directly via Session::get operations. More details are available in the query API.

Key Expressions

Data is associated with keys in the form of a slash-separated path, e.g., robot/sensor/temp. The requesting side uses key expressions to address the data of interest. Key expressions can contain wildcards, e.g., robot/sensor/* or robot/**.

Data representation

Data is received as samples, which contain the payload and all metadata associated with the data. The raw byte payload object ZBytes, which provides mechanisms for zero-copy creation and access, is available in the bytes module. The zenoh_ext crate also provides serialization and deserialization of basic types and structures for ZBytes.

Other components

Other important functionality of Zenoh includes:

• scouting to discover Zenoh nodes in the network. Note that it’s not necessary to explicitly discover other nodes just to publish, subscribe, or query data.
• Monitor liveliness to be notified when a specified resource appears or disappears in the network.
• The matching API allows the active side of communication (publisher, querier) to know whether there are any interested parties on the other side (subscriber, queryable), which allows saving bandwidth and CPU resources.

Builders

Zenoh extensively uses the builder pattern. For example, to create a publisher, you first create a PublisherBuilder using the declare_publisher method. The builder is resolved to the Publisher instance by awaiting it in an async context or by calling the wait method in a synchronous context.

Channels and callbacks

There are two ways to get sequential data from Zenoh primitives (e.g., a series of Samples from a Subscriber or Replys from a Query): by channel or by callback.

In channel mode, methods like recv_async become available on the subscriber or query object (through Deref coercion to the corresponding channel handler type). By default, the FifoChannel is used.

The builders provide methods with to assign an arbitrary channel instead of the default one, and callback to assign a callback function.

See more details in the handlers module documentation.

Usage examples

Below are basic examples of using Zenoh. More examples are available in the documentation for each module and in zenoh-examples.

Publishing/Subscribing

The example below shows how to publish and subscribe to data using Zenoh.

Publishing data:

#[tokio::main]
async fn main() {
    let session = zenoh::open(zenoh::Config::default()).await.unwrap();
    session.put("key/expression", "value").await.unwrap();
    session.close().await.unwrap();
}

Subscribing to data:

use futures::prelude::*;

#[tokio::main]
async fn main() {
    let session = zenoh::open(zenoh::Config::default()).await.unwrap();
    let subscriber = session.declare_subscriber("key/expression").await.unwrap();
    while let Ok(sample) = subscriber.recv_async().await {
        println!("Received: {:?}", sample);
    };
}

Query/Reply

Declare a queryable:

#[tokio::main]
async fn main() {
    let session = zenoh::open(zenoh::Config::default()).await.unwrap();
    let queryable = session.declare_queryable("key/expression").await.unwrap();
    while let Ok(query) = queryable.recv_async().await {
        let reply = query.reply("key/expression", "value").await.unwrap();
    }
}

Request data:

use futures::prelude::*;

#[tokio::main]
async fn main() {
    let session = zenoh::open(zenoh::Config::default()).await.unwrap();
    let replies = session.get("key/expression").await.unwrap();
    while let Ok(reply) = replies.recv_async().await {
        println!(">> Received {:?}", reply.result());
    }
}

Features

The following features are exposed by the crate:

• auth_pubkey, auth_usrpwd

  Enable authentication support, credentials are configurable in the Config

• internal

  Enable some internal APIs, usually necessary to expose some internal functionalities to other language bindings. These APIs are not supposed to be called by users as they are close to implementation and can be changed at any moment

• plugins

  Enable the APIs related to plugin support in zenohd. These APIs are internal and unstable for now

• runtime_plugins

  Enable the dynamic plugins loading. Includes plugins. May be removed in future and combined with plugins

• shared-memory

  Enable shared-memory transport support and specific shared-memory related APIs

• stats

  Enable collection of statistical data. This data becomes available in “adminspace” (by key @/<zenoh_id>/router/metrics)

• tracing-instrument

  Developer feature - enable tracing of asynchronous tasks for debugging

• transport-compression

  Enable data-compression on the fly. If this feature is enabled, compression can be turned on or off in Config

• transport_multilink

  Enable multiple link connection for unicast transports. Maximum number of connections is configurable in Config

• transport_quic, transport_quic_datagram, transport_serial, transport_tcp, transport_tls, transport_udp, transport_unixpipe, transport_unixsock-stream, transport_vsock, transport_ws

  Enable specific transports

• unstable

  Enable the unstable APIs which may change or disappear in future releases. The difference with internal is that the unstable API may be stabilized, while internal is unstable by nature, because it reveals implementation details.

The features enabled by default are:

auth_pubkey, auth_usrpwd, transport_compression, transport_multilink, transport_quic, transport_quic_datagram, transport_tcp, transport_tls, transport_udp, transport_unixsock-stream, transport_ws.

Modules

bytes

Payload primitives and encoding

config

Configuration to pass to open and scout functions and associated constants.

handlers

Callback handler trait.

key_expr

Key Expressions

liveliness

Liveliness primitives

matching

Matching primitives

pubsub

Pub/sub primitives

qos

Quality of service primitives

query

Query/reply primitives

sample

Sample primitives

scouting

Scouting primitives

session

Zenoh Session and associated types

shmunstable

Shared memory.

time

Timestamp support

Structs

Config

Zenoh configuration.

Session

The Session is the main component of Zenoh. It holds the zenoh runtime object, which maintains the state of the connection of the node to the Zenoh network.

Constants

GIT_VERSION

Traits

Resolvable

A resolvable execution, either sync or async

Resolve

Zenoh’s trait for resolving builder patterns.

Wait

Synchronous execution of a resolvable

Functions

init_log_from_env_or

A utility function to enable the tracing formatting subscriber.

open

Open a zenoh Session.

scout

Scout for routers and/or peers.

try_init_log_from_env

A utility function to enable the tracing formatting subscriber.

Type Aliases

Error

A Zenoh error.

Result

A Zenoh result.