zenoh-flat-c

A C binding for zenoh-flat, generated by prebindgen's lang::Cbindgen adapter. It exposes a single, low-level flat C API (z_* symbols) in include/zenoh_flat.h:

• bare opaque-pointer handles (z_session_t*, z_keyexpr_t*, …), each freed by its typed z_<x>_drop;
• by-value closure structs { context, call, drop } for subscribers / queryables / scout, paired with a z_closure_drop_t on-close; callback arguments are owned (the handler must z_<x>_drop them);
• positional arguments (no options structs);
• a nullable error out-param z_error_t *e — pass NULL and read the return value (non-NULL pointer / true = success);
• ownership encoded in const-ness: const z_keyexpr_t* = borrowed (drop after); a non-const z_keyexpr_t* (e.g. z_session_declare_*) is consumed.

The library is libzenoh_flat_c.{a,dylib,so}.

Layout

include/
  zenoh_flat.h            generated C API (z_*); auto-includes the configure header
  zenoh_flat_configure.h  feature #defines (ZENOH_FLAT_UNSTABLE_API, …)
src/lib.rs                include!()s the prebindgen-generated wrappers
build.rs                  runs prebindgen + cbindgen; writes include/zenoh_flat.h
examples/                 z_put / z_delete / z_pub / z_sub / z_queryable / z_scout / z_info
tests/                    z_api_keyexpr_test / z_api_session_test / z_leak_pub_sub_test
CMakeLists.txt            builds the lib (via cargo) + examples + tests (ctest)

Both headers in include/ are produced by build.rs on every cargo build.

Building

Plain cargo (library only):

cargo build

CMake (library + examples + tests):

cmake -S . -B build -DCMAKE_BUILD_TYPE=Debug
cmake --build build
ctest --test-dir build --output-on-failure

The CMake build runs cargo build through a custom target, then links the examples/tests against the zenohflatc::lib IMPORTED target. BUILD_SHARED_LIBS=ON (default) links the dylib; OFF links the static lib (which pulls in the Rust/zenoh native deps).

Examples

z_put, z_delete, z_pub, z_sub, z_queryable, z_get, z_scout, z_info, z_pub_thr, z_sub_thr — written directly against the flat API (examples/parse_args.h provides config/CLI parsing). Run a pair against a local network, e.g. build/examples/z_sub + build/examples/z_put, or build/examples/z_queryable + build/examples/z_get.

z_pub_thr <size> + z_sub_thr are a throughput benchmark: the publisher puts a fixed-size payload in a tight loop (built once, then cheaply cloned via z_zbytes_clone since z_publisher_put consumes its payload), and the subscriber prints msg/s per measurement round (timed with the libc monotonic clock — the flat API has no z_clock_* helpers).

z_get shows the callback form of get: zenoh-flat delivers each reply to a z_closure_reply_t, and on_close fires once the reply stream ends — the example blocks on a condition variable signalled by on_close (in lieu of zenoh-c's FIFO channel + z_recv loop, which has no flat-API equivalent).

Tests (ctest)

• z_api_keyexpr_test — try_from (valid/invalid), intersects/includes, autocanonize, join, and relation_to under unstable.
• z_api_session_test — open / drop a session from the default config.
• z_leak_pub_sub_test — in-process publisher + subscriber: a sample is delivered through the owned-sample handler (functional + leak coverage).

Cargo features

The feature flags mirror zenoh-c and forward through zenoh-flat to the zenoh crate, with zenoh-c's exact default set: auth_pubkey, auth_usrpwd, transport_multilink, transport_compression, transport_quic, transport_tcp, transport_tls, transport_udp, transport_unixsock-stream, transport_ws, transport_quic_datagram. (Also available, off by default: transport_serial, transport_unixpipe, transport_vsock, stats, shared-memory, unstable.)

unstable is off by default. It adds zenoh's unstable surface that zenoh-flat covers to the generated C ABI — the reliability QoS option (a trailing param on z_session_put / z_session_delete / z_session_declare_publisher), the z_set_intersection_level_t keyexpr relation (z_keyexpr_relation_to), and the reply replier_id (z_reply_replier_zid/z_reply_replier_eid).

CMake exposes -DZENOHFLATC_BUILD_WITH_UNSTABLE_API=ON and -DZENOHFLATC_BUILD_WITH_SHARED_MEMORY=ON (default OFF), which pass --features=unstable / --features=shared-memory to cargo.

build.rs emits include/zenoh_flat_configure.h defining ZENOH_FLAT_UNSTABLE_API (and ZENOH_FLAT_SHARED_MEMORY) when those features are on; zenoh_flat.h auto-includes it. Examples/tests #if defined(ZENOH_FLAT_UNSTABLE_API) to pass the extra reliability argument, so they build under both feature modes.

Not yet covered

The flat API wraps the closure-based core of zenoh. Get is exposed in the async callback form (z_session_get, z_querier_get; see z_get). What's not exposed: the channel/handler sugar (z_fifo_channel_* / z_ring_channel_* / z_recv) zenoh-c builds on top of closures, liveliness, shared memory, bytes serialization / reader / writer, and the value-class (impl Into) layer (reserved for a future JNI adapter).