Merge commit '8974132e1bd49954ebf0a7b6242c8c3f8d21f503'

Conflicts:
	Cargo.lock
	build-resources/opaque-types/Cargo.lock

.github/release.yml

@@ -32,4 +32,7 @@ changelog:
         - dependencies
     - title: Other changes
       labels:
-        - "*"
+        - "*"
+      exclude:
+        labels:
+          - internal

.github/workflows/ci.yml

@@ -231,6 +231,15 @@ jobs:
           cmake -DCMAKE_TOOLCHAIN_FILE="../ci/toolchains/TC-x86_64-pc-windows-gnu.cmake" -DZENOHC_BUILD_WITH_SHARED_MEMORY=ON -DZENOHC_BUILD_WITH_UNSTABLE_API=ON ..
           cmake --build . --target examples
 
+  markdown_lint:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+      - uses: DavidAnson/markdownlint-cli2-action@v18
+        with:
+          config: '.markdownlint.yaml'
+          globs: '**/README.md'
+
   # NOTE: In GitHub repository settings, the "Require status checks to pass
   # before merging" branch protection rule ensures that commits are only merged
   # from branches where specific status checks have passed. These checks are
@@ -239,7 +248,7 @@ jobs:
   ci:
     name: CI status checks
     runs-on: ubuntu-latest
-    needs: build
+    needs: [build, cross-compile-mac-os, cross-compile-ubuntu, markdown_lint]
     if: always()
     steps:
       - name: Check whether all jobs pass

.markdownlint.yaml

@@ -0,0 +1,6 @@
+{
+  "MD013": false, # Line length limitation
+  "MD033": false, # Enable Inline HTML
+  "MD041": false, # Allow first line heading
+  "MD045": false, # Allow Images have no alternate text
+}

README.md

@@ -175,6 +175,7 @@ cmake ../zenoh-c/examples -DCMAKE_INSTALL_PREFIX=~/.local
 ```
 
 ## Documentation
+
 Zenoh-c API documentation is available on [Read the Docs](https://zenoh-c.readthedocs.io/en/latest/index.html).
 
 It can be built manually by performing the following steps:
@@ -186,6 +187,7 @@ sphinx-build -b html . _build/html
 ```
 
 ## Cross-Compilation
+
 Cross-compilation can be performed using standard cmake approach as described in [[cmake-toolchains](https://cmake.org/cmake/help/latest/manual/cmake-toolchains.7.html)].
 
 In addition the following project-specific options might need to be set for cross-compilation:
@@ -217,6 +219,7 @@ and release files will be located at
 `/path/to/zenoh-c/target/x86_64-pc-windows-gnu/release`
 
 > :warning: **WARNING** :warning: : Perhaps additional efforts are necessary, that will depend of your environment.
+
 ## Rust Version
 
 The Rust version we use is defined in [rust-toolchain.toml](rust-toolchain.toml), which is `1.75.0`.
@@ -233,6 +236,7 @@ cmake ../zenoh-c -DZENOHC_CARGO_CHANNEL="+1.75.0"
 It's necessary sometimes to build zenoh-c library with set of features different from default. For example: enable TCP and UDP only. This can be done by changing `ZENOHC_CARGO_FLAGS` parameter for cmake (notice ";" instead of space due to cmake peculiarities)
 
 Available features can be found in [Cargo.toml](./Cargo.toml)
+
 ```bash
 cmake ../zenoh-c -DZENOHC_CARGO_FLAGS="--no-default-features;--features=transport_tcp,transport_udp"
 ```

docs/README.md

@@ -3,6 +3,7 @@
 zenoh-c API documentation is available on [Read the Docs](https://zenoh-c.readthedocs.io/en/latest/index.html).
 
 -------------------------------
+
 ## How to build it
 
 ```bash

docs/api.rst

@@ -475,7 +475,7 @@ Functions
 ---------
 
 .. doxygenfunction:: zc_matching_listener_drop
-.. doxygenfunction:: zc_matching_listener_undeclare
+.. doxygenfunction:: zc_undeclare_matching_listener
 .. doxygenfunction:: zc_closure_matching_status_drop
 .. doxygenfunction:: zc_closure_matching_status_loan
 .. doxygenfunction:: zc_closure_matching_status_call
@@ -708,7 +708,6 @@ Functions
 .. doxygenfunction:: z_undeclare_querier
 .. doxygenfunction:: z_querier_loan
 .. doxygenfunction:: z_querier_drop
-.. doxygenfunction:: z_declare_background_querier
 .. doxygenfunction:: z_querier_id
 .. doxygenfunction:: z_querier_keyexpr
 .. doxygenfunction:: z_querier_get

examples/z_advanced_pub.c

@@ -53,10 +53,8 @@ int main(int argc, char** argv) {
 
     ze_advanced_publisher_options_t pub_opts;
     ze_advanced_publisher_options_default(&pub_opts);
-    ze_advanced_publisher_cache_options_t cache_options;
-    ze_advanced_publisher_cache_options_default(&cache_options);
-    cache_options.max_samples = args.history;
-    pub_opts.cache = &cache_options;
+    ze_advanced_publisher_cache_options_default(&pub_opts.cache);  // or pub_opts.cache.is_enabled = true;
+    pub_opts.cache.max_samples = args.history;
     pub_opts.publisher_detection = true;
     pub_opts.sample_miss_detection = true;
 

examples/z_advanced_sub.c

@@ -64,16 +64,10 @@ int main(int argc, char** argv) {
 
     ze_advanced_subscriber_options_t sub_opts;
     ze_advanced_subscriber_options_default(&sub_opts);
-
-    ze_advanced_subscriber_history_options_t sub_history_options;
-    ze_advanced_subscriber_history_options_default(&sub_history_options);
-    sub_history_options.detect_late_publishers = true;
-
-    ze_advanced_subscriber_recovery_options_t sub_recovery_options;
-    ze_advanced_subscriber_recovery_options_default(&sub_recovery_options);
-    sub_recovery_options.periodic_queries_period_ms = 1000;
-    sub_opts.history = &sub_history_options;
-    sub_opts.recovery = &sub_recovery_options;
+    ze_advanced_subscriber_history_options_default(&sub_opts.history);  // or sub_opts.history.is_enabled = true;
+    sub_opts.history.detect_late_publishers = true;
+    ze_advanced_subscriber_recovery_options_default(&sub_opts.recovery);  // or sub_opts.recovery.is_enabled = true;
+    sub_opts.recovery.periodic_queries_period_ms = 1000;
     sub_opts.subscriber_detection = true;
 
     z_owned_closure_sample_t callback;

include/zenoh_commons.h

@@ -1009,7 +1009,11 @@ typedef struct zc_moved_shm_client_list_t {
 #if defined(Z_FEATURE_UNSTABLE_API)
 typedef struct ze_advanced_publisher_cache_options_t {
   /**
-   * Number of samples to keep for each resource
+   * Must be set to ``true``, to enable the cache.
+   */
+  bool is_enabled;
+  /**
+   * Number of samples to keep for each resource.
    */
   size_t max_samples;
   /**
@@ -1053,9 +1057,9 @@ typedef struct ze_advanced_publisher_options_t {
    */
   struct z_publisher_options_t publisher_options;
   /**
-   * Optional settings for publisher cache.
+   * Publisher cache settings.
    */
-  struct ze_advanced_publisher_cache_options_t *cache;
+  struct ze_advanced_publisher_cache_options_t cache;
   /**
    * Allow matching Subscribers to detect lost samples and optionally ask for retransimission.
    *
@@ -1070,7 +1074,7 @@ typedef struct ze_advanced_publisher_options_t {
    * An optional key expression to be added to the liveliness token key expression.
    * It can be used to convey meta data.
    */
-  struct z_loaned_keyexpr_t *publisher_detection_metadata;
+  const struct z_loaned_keyexpr_t *publisher_detection_metadata;
 } ze_advanced_publisher_options_t;
 #endif
 /**
@@ -1142,6 +1146,10 @@ typedef struct ze_moved_advanced_subscriber_t {
  */
 #if defined(Z_FEATURE_UNSTABLE_API)
 typedef struct ze_advanced_subscriber_history_options_t {
+  /**
+   * Must be set to ``true``, to enable the history data recovery.
+   */
+  bool is_enabled;
   /**
    * Enable detection of late joiner publishers and query for their historical data.
    * Late joiner detection can only be achieved for Publishers that enable publisher_detection.
@@ -1164,6 +1172,10 @@ typedef struct ze_advanced_subscriber_history_options_t {
  */
 #if defined(Z_FEATURE_UNSTABLE_API)
 typedef struct ze_advanced_subscriber_recovery_options_t {
+  /**
+   * Must be set to ``true``, to enable the lost sample recovery.
+   */
+  bool is_enabled;
   /**
    * Period for queries for not yet received Samples.
    *
@@ -1186,16 +1198,14 @@ typedef struct ze_advanced_subscriber_options_t {
    */
   struct z_subscriber_options_t subscriber_options;
   /**
-   * Optional settings for querying historical data. History can only be retransmitted by Publishers that enable caching.
-   * Querying historical data is disabled if the value is ``NULL``.
+   * Settings for querying historical data. History can only be retransmitted by Publishers that enable caching.
    */
-  struct ze_advanced_subscriber_history_options_t *history;
+  struct ze_advanced_subscriber_history_options_t history;
   /**
-   * Optional settings for retransmission of detected lost Samples. Retransmission of lost samples can only be done by Publishers that enable
+   * Settings for retransmission of detected lost Samples. Retransmission of lost samples can only be done by Publishers that enable
    * caching and sample_miss_detection.
-   * Retransmission is disabled if the value is ``NULL``.
    */
-  struct ze_advanced_subscriber_recovery_options_t *recovery;
+  struct ze_advanced_subscriber_recovery_options_t recovery;
   /**
    * Timeout to be used for history and recovery queries.
    * Default value will be used if set to ``0``.
@@ -1209,7 +1219,7 @@ typedef struct ze_advanced_subscriber_options_t {
    * An optional key expression to be added to the liveliness token key expression.
    * It can be used to convey meta data.
    */
-  struct z_loaned_keyexpr_t *subscriber_detection_metadata;
+  const struct z_loaned_keyexpr_t *subscriber_detection_metadata;
 } ze_advanced_subscriber_options_t;
 #endif
 /**

src/advanced_publisher.rs

@@ -37,7 +37,9 @@ use crate::{
 /// @brief Setting for advanced publisher's cache. The cache allows advanced subscribers to recover history and/or lost samples.
 #[repr(C)]
 pub struct ze_advanced_publisher_cache_options_t {
-    /// Number of samples to keep for each resource
+    /// Must be set to ``true``, to enable the cache.
+    pub is_enabled: bool,
+    /// Number of samples to keep for each resource.
     pub max_samples: usize,
     /// The congestion control to apply to replies.
     pub congestion_control: z_congestion_control_t,
@@ -50,6 +52,7 @@ pub struct ze_advanced_publisher_cache_options_t {
 impl Default for ze_advanced_publisher_cache_options_t {
     fn default() -> Self {
         Self {
+            is_enabled: true,
             max_samples: 1,
             congestion_control: CongestionControl::default().into(),
             priority: Priority::default().into(),
@@ -86,8 +89,8 @@ impl From<&ze_advanced_publisher_cache_options_t> for CacheConfig {
 pub struct ze_advanced_publisher_options_t {
     /// Base publisher options.
     pub publisher_options: z_publisher_options_t,
-    /// Optional settings for publisher cache.
-    pub cache: Option<&'static mut ze_advanced_publisher_cache_options_t>,
+    /// Publisher cache settings.
+    pub cache: ze_advanced_publisher_cache_options_t,
     /// Allow matching Subscribers to detect lost samples and optionally ask for retransimission.
     ///
     /// Retransmission can only be done if history is enabled on subscriber side.
@@ -96,17 +99,21 @@ pub struct ze_advanced_publisher_options_t {
     pub publisher_detection: bool,
     /// An optional key expression to be added to the liveliness token key expression.
     /// It can be used to convey meta data.
-    pub publisher_detection_metadata: Option<&'static mut z_loaned_keyexpr_t>,
+    pub publisher_detection_metadata: Option<&'static z_loaned_keyexpr_t>,
 }
 
 /// Constructs the default value for `z_publisher_options_t`.
 #[no_mangle]
 pub extern "C" fn ze_advanced_publisher_options_default(
     this_: &mut MaybeUninit<ze_advanced_publisher_options_t>,
 ) {
+    let cache = ze_advanced_publisher_cache_options_t {
+        is_enabled: false,
+        ..Default::default()
+    };
     this_.write(ze_advanced_publisher_options_t {
         publisher_options: z_publisher_options_t::default(),
-        cache: None,
+        cache,
         sample_miss_detection: false,
         publisher_detection: false,
         publisher_detection_metadata: None,
@@ -158,8 +165,8 @@ pub extern "C" fn ze_declare_advanced_publisher(
         if let Some(pub_detection_metadata) = &options.publisher_detection_metadata {
             p = p.publisher_detection_metadata(pub_detection_metadata.as_rust_type_ref());
         }
-        if let Some(cache) = &options.cache {
-            p = p.cache((&**cache).into());
+        if options.cache.is_enabled {
+            p = p.cache((&options.cache).into());
         }
     }
     match p.wait() {