Eclipse zenoh C Client API

Eclipse zenoh is an extremely efficient and fault-tolerant Named Data Networking (NDN) protocol that is able to scale down to extremely constrainded devices and networks.

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

How to build it

1. Make sure that rust is available on your platform:

-- Ubuntu --

$ sudo apt-get install rustc

-- MacOS --

$ brew install rust

2. Clone the source with git:

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

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