Eclipse Zenoh

The Eclipse Zenoh: Zero Overhead Pub/sub, Store/Query and Compute.

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

Check the website zenoh.io and the roadmap for more detailed information.

C API

This repository provides a C binding based on the main Zenoh implementation written in Rust.

How to build it

⚠️ WARNING ⚠️ : Zenoh and its ecosystem are under active development. When you build from git, make sure you also build from git any other Zenoh repository you plan to use (e.g. binding, plugin, backend, etc.). It may happen that some changes in git are not compatible with the most recent packaged Zenoh release (e.g. deb, docker, pip). We put particular effort in mantaining compatibility between the various git repositories in the Zenoh project.

Make sure that rust is available on your platform:

-- Ubuntu --

$ sudo apt-get install rustc

-- MacOS --

$ brew install rust

Clone the source with git:

git clone https://github.com/eclipse-zenoh/zenoh-c.git
cd zenoh-c

Build and install:

$ cd /path/to/zenoh-c
$ mkdir -p build && cd build 
$ cmake -DCMAKE_BUILD_TYPE=Release ..
$ cmake --build .
$ cmake --build . --target install # on linux use **sudo**

You may alternatively use -DCMAKE_BUILD_TYPE=RelWithDebInfo if you wish to keep the debug symbols.

Note that the install target is only available for Release and RelWithDebInfo builds.
CMake also offers the Debug build type, which we do not allow as an install target since you may suffer a significant performance hit if accidentally using this one.
Finally, CMake typicall offers a MinSizeRel build type. While we do not prevent you from using it, note that it is strictly equivalent to running a Release build.

Building the Examples

$ cd /path/to/zenoh-c
$ mkdir -p build && cd build #
$ cmake -DCMAKE_BUILD_TYPE=Release .. # If Ninja is installed on your system, adding `-GNinja` to this command can greatly speed up the build time
$ cmake --build . --target examples

You may also use --target <example_name> if you wish to only build a specific example.

All build artifacts will be in the /path/to/zenoh-c/target/release directory.

Running the Examples

Basic Pub/Sub Example

$ ./target/release/examples/z_sub

$ ./target/release/examples/z_pub

Queryable and Query Example

$ ./target/release/examples/z_queryable

$ ./target/release/examples/z_get

Running the Throughput Examples

$ ./target/release/examples/z_sub_thgr

$ ./target/release/examples/z_pub_thgr

API conventions

Many of the types exposed by the zenoh-c API are types for which destruction is necessary. To help you spot these types, we named them with the convention that any destructible type must start by z_owned.

For maximum performance, we try to make as few copies as possible. Sometimes, this implies moving data that you z_owned. Any function that takes a non-const pointer to a z_owned type will perform its destruction. To make this pattern more obvious, we encourage you to use the z_move macro instead of a simple & to create these pointers. Rest assured that all z_owned types are double-free safe, and that you may check whether any z_owned_X_t typed value is still valid by using z_X_check(&val), or the z_check(val) macro if you're using C11.

We hope this convention will help you streamline your memory-safe usage of zenoh, as following it should make looking for leaks trivial: simply search for paths where a value of a z_owned type hasn't been passed to a function using z_move.

Functions that simply need to borrow your data will instead take values of the associated z_X_t type. You may construct them using z_X_loan(&val) (or the z_loan(val) generic macro with C11).

Note that some z_X_t typed values can be constructed without needing to z_borrow their owned variants. This allows you to reduce the amount of copies realized in your program.

The examples have been written with C11 in mind, using the conventions we encourage you to follow.

Finally, we strongly advise that you refrain from using structure field that starts with _:

We try to maintain a common API between zenoh-c and zenoh-pico, such that porting code from one to the other is, ideally, trivial. However, some types must have distinct representations in either library, meaning that using these representations explicitly will get you in trouble when porting.
We reserve the right to change the memory layout of any type which has _-prefixed fields, so trying to use them might cause your code to break on updates.

Logging

By default, zenoh-c enables Zenoh's logging library upon using the z_open or z_scout functions. This behaviour can be disabled by adding -DDISABLE_LOGGER_AUTOINIT:bool=true to the cmake configuration command. The logger may then be manually re-enabled with the zc_init_logger function.

gabrik / zenoh-c