stabilize liveliness API (#314)

* stabilize liveliness API * submodule update * zenoh-c submodule update * ifdefs restored to handle zenoh-pico Z_FEATURE_LIVELINESS setting * updated submodules
eclipse-zenoh · Dec 11, 2024 · 0b42e29 · 0b42e29
1 parent 5c98296
commit 0b42e29
Show file tree

Hide file tree

Showing 9 changed files with 9 additions and 49 deletions.
diff --git a/examples/CMakeLists.txt b/examples/CMakeLists.txt
@@ -57,9 +57,6 @@ function(add_examples glob mode lib)
 		endif()
 
 		if(("${mode}" STREQUAL "zenohc") AND (NOT(ZENOHC_BUILD_WITH_UNSTABLE_API)))
-			if(${file} MATCHES ".*liveliness.*$")
-				continue()
-			endif()
 			if(${file} MATCHES ".*querier.*$")
 				continue()
 			endif()

diff --git a/include/zenoh/api.hxx b/include/zenoh/api.hxx
@@ -22,7 +22,9 @@
 #include "api/hello.hxx"
 #include "api/id.hxx"
 #include "api/keyexpr.hxx"
+#if defined(ZENOHCXX_ZENOHC) || Z_FEATURE_LIVELINESS == 1
 #include "api/liveliness.hxx"
+#endif
 #include "api/logging.hxx"
 #include "api/publisher.hxx"
 #include "api/query.hxx"

diff --git a/include/zenoh/api/liveliness.hxx b/include/zenoh/api/liveliness.hxx
@@ -13,23 +13,20 @@
 
 #pragma once
 
-#if defined(Z_FEATURE_UNSTABLE_API) && (defined(ZENOHCXX_ZENOHC) || Z_FEATURE_LIVELINESS == 1)
 #include "base.hxx"
 #include "interop.hxx"
 
 namespace zenoh {
 
 class Session;
 
-/// @warning This API has been marked as unstable: it works as advertised, but it may be changed in a future release.
 /// @brief A liveliness token that can be used to provide the network with information about connectivity to its
 /// declarer.
 ///
 /// When constructed, a PUT sample will be received by liveliness subscribers on intersecting key expressions.
 ///
 /// A DELETE on the token's key expression will be received by subscribers if the token is destroyed, or if connectivity
 /// between the subscriber and the token's creator is lost.
-/// @note Zenoh-c only.
 class LivelinessToken : public Owned<::z_owned_liveliness_token_t> {
     LivelinessToken(zenoh::detail::null_object_t) : Owned(nullptr){};
     friend struct interop::detail::Converter;
@@ -44,5 +41,4 @@ class LivelinessToken : public Owned<::z_owned_liveliness_token_t> {
     }
 };
 
-}  // namespace zenoh
-#endif
+}  // namespace zenoh
diff --git a/include/zenoh/api/session.hxx b/include/zenoh/api/session.hxx
@@ -863,11 +863,8 @@ class Session : public Owned<::z_owned_session_t> {
     }
 #endif
 
-#if defined(Z_FEATURE_UNSTABLE_API) && (defined(ZENOHCXX_ZENOHC) || Z_FEATURE_LIVELINESS == 1)
-    /// @warning This API has been marked as unstable: it works as advertised, but it may be changed in a future
-    /// release.
+#if defined(ZENOHCXX_ZENOHC) || Z_FEATURE_LIVELINESS == 1
     /// @brief Options to pass to ``Session::liveliness_declare_token``.
-    /// @note Zenoh-c only.
     struct LivelinessDeclarationOptions {
        protected:
         uint8_t _dummy = 0;
@@ -876,8 +873,6 @@ class Session : public Owned<::z_owned_session_t> {
         static LivelinessDeclarationOptions create_default() { return {}; }
     };
 
-    /// @warning This API has been marked as unstable: it works as advertised, but it may be changed in a future
-    /// release.
     /// @brief Declares a liveliness token on the network.
     ///
     /// Liveliness token subscribers on an intersecting key expression will receive a PUT sample when connectivity
@@ -888,7 +883,6 @@ class Session : public Owned<::z_owned_session_t> {
     /// @param err if not null, the result code will be written to this location, otherwise ZException exception will be
     /// thrown in case of error.
     /// @return a ``LivelinessToken``.
-    /// @note Zenoh-c only.
     LivelinessToken liveliness_declare_token(
         const KeyExpr& key_expr,
         LivelinessDeclarationOptions&& options = LivelinessDeclarationOptions::create_default(),
@@ -903,19 +897,14 @@ class Session : public Owned<::z_owned_session_t> {
         return t;
     }
 
-    /// @warning This API has been marked as unstable: it works as advertised, but it may be changed in a future
-    /// release.
     /// @brief Options to pass to ``Session::liveliness_declare_subscriber``.
-    /// @note Zenoh-c only.
     struct LivelinessSubscriberOptions {
        public:
         bool history = false;
 
         static LivelinessSubscriberOptions create_default() { return {}; }
     };
 
-    /// @warning This API has been marked as unstable: it works as advertised, but it may be changed in a future
-    /// release.
     /// @brief Declares a subscriber on liveliness tokens that intersect `key_expr`.
     /// @param key_expr the key expression to subscribe to.
     /// @param on_sample the callable that will be called each time a liveliness token status is changed.
@@ -924,7 +913,6 @@ class Session : public Owned<::z_owned_session_t> {
     /// @param err if not null, the result code will be written to this location, otherwise ZException exception will be
     /// thrown in case of error.
     /// @return a ``Subscriber`` object.
-    /// @note Zenoh-c only.
     template <class C, class D>
     [[nodiscard]] Subscriber<void> liveliness_declare_subscriber(
         const KeyExpr& key_expr, C&& on_sample, D&& on_drop,
@@ -989,9 +977,7 @@ class Session : public Owned<::z_owned_session_t> {
     }
 #endif
 
-#if defined(Z_FEATURE_UNSTABLE_API) && (defined(ZENOHCXX_ZENOHC) || Z_FEATURE_LIVELINESS == 1)
-    /// @warning This API has been marked as unstable: it works as advertised, but it may be changed in a future
-    /// release.
+#if defined(ZENOHCXX_ZENOHC) || Z_FEATURE_LIVELINESS == 1
     /// @brief Declare a subscriber on liveliness tokens that intersect `key_expr`.
     /// @tparam Channel the type of channel used to create stream of data (see ``zenoh::channels::FifoChannel`` or
     /// ``zenoh::channels::RingChannel``).
@@ -1001,7 +987,6 @@ class Session : public Owned<::z_owned_session_t> {
     /// @param err if not null, the result code will be written to this location, otherwise ZException exception will be
     /// thrown in case of error.
     /// @return a ``Subscriber`` object.
-    /// @note Zenoh-c only.
     template <class Channel>
     [[nodiscard]] Subscriber<typename Channel::template HandlerType<Sample>> liveliness_declare_subscriber(
         const KeyExpr& key_expr, Channel channel,
@@ -1021,10 +1006,7 @@ class Session : public Owned<::z_owned_session_t> {
                                                                           std::move(cb_handler_pair.second));
     }
 
-    /// @warning This API has been marked as unstable: it works as advertised, but it may be changed in a future
-    /// release.
     /// @brief Options to pass to ``Session::liveliness_get``.
-    /// @note Zenoh-c only.
     struct LivelinessGetOptions {
         /// @name Fields
 
@@ -1037,8 +1019,6 @@ class Session : public Owned<::z_owned_session_t> {
         static LivelinessGetOptions create_default() { return {}; }
     };
 
-    /// @warning This API has been marked as unstable: it works as advertised, but it may be changed in a future
-    /// release.
     /// @brief Query liveliness tokens currently on the network with a key expression intersecting with `key_expr`.
     ///
     /// @param key_expr: the key expression to query liveliness tokens for.
@@ -1047,7 +1027,6 @@ class Session : public Owned<::z_owned_session_t> {
     /// @param options: additional options for the liveliness get operation.
     /// @param err if not null, the result code will be written to this location, otherwise ZException exception will be
     /// thrown in case of error.
-    /// @note Zenoh-c only.
     template <class C, class D>
     void liveliness_get(const KeyExpr& key_expr, C&& on_reply, D&& on_drop,
                         LivelinessGetOptions&& options = LivelinessGetOptions::create_default(),
@@ -1071,8 +1050,6 @@ class Session : public Owned<::z_owned_session_t> {
                              err, "Failed to perform liveliness_get operation");
     }
 
-    /// @warning This API has been marked as unstable: it works as advertised, but it may be changed in a future
-    /// release.
     /// @brief Query liveliness tokens currently on the network with a key expression intersecting with `key_expr`.
     /// @tparam Channel the type of channel used to create stream of data (see ``zenoh::channels::FifoChannel`` or
     /// ``zenoh::channels::RingChannel``).
@@ -1082,7 +1059,6 @@ class Session : public Owned<::z_owned_session_t> {
     /// @param err if not null, the result code will be written to this location, otherwise ZException exception will be
     /// thrown in case of error.
     /// @return reply handler.
-    /// @note Zenoh-c only.
     template <class Channel>
     typename Channel::template HandlerType<Reply> liveliness_get(
         const KeyExpr& key_expr, Channel channel,
@@ -1099,7 +1075,6 @@ class Session : public Owned<::z_owned_session_t> {
         return std::move(cb_handler_pair.second);
     }
 
-#endif
     /// @brief Create Timestamp from session id.
     /// @param err if not null, the result code will be written to this location, otherwise ZException exception will be
     /// thrown in case of error.
@@ -1120,6 +1095,7 @@ class Session : public Owned<::z_owned_session_t> {
         (void)options;
         __ZENOH_RESULT_CHECK(::z_close(interop::as_loaned_c_ptr(*this), nullptr), err, "Failed to close the session");
     }
+#endif
 
 #if defined(ZENOHCXX_ZENOHC) && defined(Z_FEATURE_UNSTABLE_API)
     /// @warning This API has been marked as unstable: it works as advertised, but it may be changed in a future

diff --git a/scripts/install_from_git.sh b/scripts/install_from_git.sh
@@ -38,7 +38,7 @@ absolute_install_location=$(cd $1; pwd)
 bash $SCRIPT_DIR/install_local.sh $SCRIPT_DIR/../zenoh-c $absolute_install_location -DZENOHC_BUILD_WITH_UNSTABLE_API=$USE_UNSTABLE -DZENOHC_BUILD_WITH_SHARED_MEMORY=$USE_SHARED_MEMORY
 if [ "$BUILD_PICO" == "ON" ]; then
     #build zenoh-pico
-    bash $SCRIPT_DIR/install_local.sh $SCRIPT_DIR/../zenoh-pico $absolute_install_location -DZ_FEATURE_UNSTABLE_API=$USE_UNSTABLE_PICO -DZ_FEATURE_LIVELINESS=$USE_UNSTABLE_PICO
+    bash $SCRIPT_DIR/install_local.sh $SCRIPT_DIR/../zenoh-pico $absolute_install_location -DZ_FEATURE_UNSTABLE_API=$USE_UNSTABLE_PICO
 fi
 
 rm -rf ./build

diff --git a/tests/CMakeLists.txt b/tests/CMakeLists.txt
@@ -71,11 +71,6 @@ endforeach()
 if(ZENOHCXX_ZENOHC) 
 	file(GLOB files "${CMAKE_CURRENT_SOURCE_DIR}/zenohc/*.cxx")
 	foreach(file ${files})
-		if(NOT(ZENOHC_BUILD_WITH_UNSTABLE_API))
-			if(${file} MATCHES ".*liveliness.*$")
-				continue()
-			endif()
-		endif()
 		add_test_instance(${file} zenohc zenohcxx::zenohc "")
 	endforeach()
 endif()

diff --git a/tests/universal/network/liveliness.cxx b/tests/universal/network/liveliness.cxx
@@ -23,8 +23,6 @@ using namespace std::chrono_literals;
 #undef NDEBUG
 #include <assert.h>
 
-#if defined(Z_FEATURE_UNSTABLE_API) && (defined(ZENOHCXX_ZENOHC) || Z_FEATURE_LIVELINESS == 1)
-
 void test_liveliness_get() {
     KeyExpr ke("zenoh/liveliness/test/*");
     KeyExpr token_ke("zenoh/liveliness/test/1");
@@ -92,11 +90,7 @@ void test_liveliness_subscriber() {
     assert(delete_tokens.count("zenoh/liveliness/test/2") == 1);
 }
 
-#endif
-
 int main(int argc, char** argv) {
-#if defined Z_FEATURE_UNSTABLE_API
     test_liveliness_get();
     test_liveliness_subscriber();
-#endif
 };
diff --git a/zenoh-c b/zenoh-c
diff --git a/zenoh-pico b/zenoh-pico
+56 −33		Cargo.lock
+56 −33		build-resources/opaque-types/Cargo.lock
+3 −5		build-resources/opaque-types/src/lib.rs
+1 −2		examples/CMakeLists.txt
+49 −14		examples/parse_args.h
+6 −14		examples/z_delete.c
+18 −37		examples/z_get.c
+16 −16		examples/z_get_liveliness.c
+74 −35		examples/z_get_shm.c
+1 −7		examples/z_info.c
+6 −14		examples/z_liveliness.c
+32 −19		examples/z_non_blocking_get.c
+26 −36		examples/z_ping.c
+47 −65		examples/z_ping_shm.c
+16 −12		examples/z_pong.c
+29 −30		examples/z_pub.c
+0 −139		examples/z_pub_attachment.c
+27 −30		examples/z_pub_cache.c
+18 −42		examples/z_pub_shm.c
+53 −21		examples/z_pub_shm_thr.c
+18 −12		examples/z_pub_thr.c
+18 −17		examples/z_pull.c
+10 −20		examples/z_put.c
+22 −46		examples/z_querier.c
+14 −14		examples/z_query_sub.c
+11 −25		examples/z_queryable.c
+68 −25		examples/z_queryable_shm.c
+10 −25		examples/z_queryable_with_channels.c
+30 −40		examples/z_sub.c
+0 −139		examples/z_sub_attachment.c
+14 −15		examples/z_sub_liveliness.c
+56 −21		examples/z_sub_shm.c
+33 −18		examples/z_sub_thr.c
+361 −176		include/zenoh_commons.h
+0 −186		include/zenoh_macros.h
+7 −4		install/PackageConfig.cmake.in
+2 −2		splitguide.yaml
+0 −2		src/lib.rs
+1 −14		src/liveliness.rs
+1 −0		src/publication_cache.rs
+1 −0		src/querying_subscriber.rs
+2 −2		tests/CMakeLists.txt