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
andzenoh-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.