From 8322703cdd924b056511bcbd974581b267429370 Mon Sep 17 00:00:00 2001 From: Denis Biryukov Date: Tue, 10 Sep 2024 16:00:13 +0200 Subject: [PATCH] make unstable tags more visible in the docs --- build-resources/opaque-types/src/lib.rs | 54 +- docs/api.rst | 2 + include/zenoh_commons.h | 624 ++++++++++-------- src/closures/matching_status_closure.rs | 16 +- src/closures/zenohid_closure.rs | 16 +- src/commons.rs | 36 +- src/get.rs | 8 +- src/info.rs | 8 +- src/keyexpr.rs | 4 +- src/liveliness.rs | 28 +- src/payload.rs | 10 +- src/publication_cache.rs | 18 +- src/publisher.rs | 22 +- src/put.rs | 10 +- src/queryable.rs | 6 +- src/querying_subscriber.rs | 16 +- src/scouting.rs | 2 +- src/session.rs | 2 +- src/shm/buffer/zshm.rs | 20 +- src/shm/buffer/zshmmut.rs | 18 +- src/shm/client/shm_client.rs | 10 +- src/shm/client/shm_segment.rs | 4 +- src/shm/client_storage/mod.rs | 30 +- src/shm/common/types.rs | 6 +- .../posix/posix_shm_client.rs | 2 +- .../posix/posix_shm_provider.rs | 2 +- .../posix/protocol_id.rs | 2 +- src/shm/provider/alloc_layout.rs | 2 +- src/shm/provider/chunk.rs | 4 +- src/shm/provider/shm_provider.rs | 32 +- src/shm/provider/shm_provider_backend.rs | 2 +- src/shm/provider/types.rs | 38 +- 32 files changed, 572 insertions(+), 482 deletions(-) diff --git a/build-resources/opaque-types/src/lib.rs b/build-resources/opaque-types/src/lib.rs index d36e39fe3..563e7b7ec 100644 --- a/build-resources/opaque-types/src/lib.rs +++ b/build-resources/opaque-types/src/lib.rs @@ -131,7 +131,7 @@ get_opaque_type_data!(Option>, z_owned_queryable_t); /// A loaned Zenoh queryable. get_opaque_type_data!(Queryable<'static, ()>, z_loaned_queryable_t); #[cfg(feature = "unstable")] -/// @attention Unstable feature. +/// @warning This API has been marked as unstable: it works as advertised, but it may be changed in a future release. /// @brief An owned Zenoh querying subscriber. /// /// In addition to receiving the data it is subscribed to, @@ -141,7 +141,7 @@ get_opaque_type_data!( ze_owned_querying_subscriber_t ); #[cfg(feature = "unstable")] -/// @attention Unstable feature. +/// @warning This API has been marked as unstable: it works as advertised, but it may be changed in a future release. /// @brief A loaned Zenoh querying subscriber. get_opaque_type_data!( (zenoh_ext::FetchingSubscriber<'static, ()>, &'static Session), @@ -190,7 +190,7 @@ get_opaque_type_data!(Option, z_owned_config_t); get_opaque_type_data!(Config, z_loaned_config_t); #[cfg(feature = "unstable")] -/// @attention Unstable feature. +/// @warning This API has been marked as unstable: it works as advertised, but it may be changed in a future release. /// @brief A Zenoh ID. /// /// In general, valid Zenoh IDs are LSB-first 128bit unsigned and non-zero integers. @@ -207,7 +207,7 @@ get_opaque_type_data!(Option>, z_owned_publisher_t); get_opaque_type_data!(Publisher<'static>, z_loaned_publisher_t); #[cfg(feature = "unstable")] -/// @attention Unstable feature. +/// @warning This API has been marked as unstable: it works as advertised, but it may be changed in a future release. /// @brief An owned Zenoh matching listener. /// /// A listener that sends notifications when the [`MatchingStatus`] of a publisher changes. @@ -226,7 +226,7 @@ get_opaque_type_data!(Option>, z_owned_subscriber_t); get_opaque_type_data!(Subscriber<'static, ()>, z_loaned_subscriber_t); #[cfg(feature = "unstable")] -/// @attention Unstable feature. +/// @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. @@ -237,10 +237,10 @@ get_opaque_type_data!( zc_owned_liveliness_token_t ); #[cfg(feature = "unstable")] -/// @attention Unstable feature. +/// @warning This API has been marked as unstable: it works as advertised, but it may be changed in a future release. get_opaque_type_data!(LivelinessToken<'static>, zc_loaned_liveliness_token_t); #[cfg(feature = "unstable")] -/// @attention Unstable feature. +/// @warning This API has been marked as unstable: it works as advertised, but it may be changed in a future release. /// @brief An owned Zenoh publication cache. /// /// Used to store publications on intersecting key expressions. Can be queried later via `z_get()` to retrieve this data @@ -250,7 +250,7 @@ get_opaque_type_data!( ze_owned_publication_cache_t ); #[cfg(feature = "unstable")] -/// @attention Unstable feature. +/// @warning This API has been marked as unstable: it works as advertised, but it may be changed in a future release. /// @brief A loaned Zenoh publication cache. get_opaque_type_data!( zenoh_ext::PublicationCache<'static>, @@ -284,18 +284,18 @@ get_opaque_type_data!(Option, z_owned_hello_t); get_opaque_type_data!(Hello, z_loaned_hello_t); #[cfg(all(feature = "shared-memory", feature = "unstable"))] -/// @attention Unstable feature. +/// @warning This API has been marked as unstable: it works as advertised, but it may be changed in a future release. /// @brief An owned SHM Client. get_opaque_type_data!(Option>, z_owned_shm_client_t); #[cfg(all(feature = "shared-memory", feature = "unstable"))] -/// @attention Unstable feature. +/// @warning This API has been marked as unstable: it works as advertised, but it may be changed in a future release. /// @brief An owned list of SHM Clients. get_opaque_type_data!( Option)>>, zc_owned_shm_client_list_t ); #[cfg(all(feature = "shared-memory", feature = "unstable"))] -/// @attention Unstable feature. +/// @warning This API has been marked as unstable: it works as advertised, but it may be changed in a future release. /// @brief A loaned list of SHM Clients. get_opaque_type_data!( Vec<(ProtocolID, Arc)>, @@ -303,7 +303,7 @@ get_opaque_type_data!( ); #[cfg(all(feature = "shared-memory", feature = "unstable"))] -/// @attention Unstable feature. +/// @warning This API has been marked as unstable: it works as advertised, but it may be changed in a future release. /// @brief An owned SHM Client Storage get_opaque_type_data!(Option>, z_owned_shm_client_storage_t); #[cfg(all(feature = "shared-memory", feature = "unstable"))] @@ -311,38 +311,38 @@ get_opaque_type_data!(Option>, z_owned_shm_client_storage_ get_opaque_type_data!(Arc, z_loaned_shm_client_storage_t); #[cfg(all(feature = "shared-memory", feature = "unstable"))] -/// @attention Unstable feature. +/// @warning This API has been marked as unstable: it works as advertised, but it may be changed in a future release. /// @brief An owned MemoryLayout. get_opaque_type_data!(Option, z_owned_memory_layout_t); #[cfg(all(feature = "shared-memory", feature = "unstable"))] -/// @attention Unstable feature. +/// @warning This API has been marked as unstable: it works as advertised, but it may be changed in a future release. /// @brief A loaned MemoryLayout. get_opaque_type_data!(MemoryLayout, z_loaned_memory_layout_t); #[cfg(all(feature = "shared-memory", feature = "unstable"))] -/// @attention Unstable feature. +/// @warning This API has been marked as unstable: it works as advertised, but it may be changed in a future release. /// @brief An owned ChunkAllocResult. get_opaque_type_data!(Option, z_owned_chunk_alloc_result_t); #[cfg(all(feature = "shared-memory", feature = "unstable"))] -/// @attention Unstable feature. +/// @warning This API has been marked as unstable: it works as advertised, but it may be changed in a future release. /// @brief A loaned ChunkAllocResult. get_opaque_type_data!(ChunkAllocResult, z_loaned_chunk_alloc_result_t); #[cfg(all(feature = "shared-memory", feature = "unstable"))] -/// @attention Unstable feature. +/// @warning This API has been marked as unstable: it works as advertised, but it may be changed in a future release. /// @brief An owned ZShm slice. get_opaque_type_data!(Option, z_owned_shm_t); #[cfg(all(feature = "shared-memory", feature = "unstable"))] -/// @attention Unstable feature. +/// @warning This API has been marked as unstable: it works as advertised, but it may be changed in a future release. /// @brief A loaned ZShm slice. get_opaque_type_data!(zshm, z_loaned_shm_t); #[cfg(all(feature = "shared-memory", feature = "unstable"))] -/// @attention Unstable feature. +/// @warning This API has been marked as unstable: it works as advertised, but it may be changed in a future release. /// @brief An owned ZShmMut slice. get_opaque_type_data!(Option, z_owned_shm_mut_t); #[cfg(all(feature = "shared-memory", feature = "unstable"))] -/// @attention Unstable feature. +/// @warning This API has been marked as unstable: it works as advertised, but it may be changed in a future release. /// @brief A loaned ZShmMut slice. get_opaque_type_data!(zshmmut, z_loaned_shm_mut_t); @@ -408,11 +408,11 @@ enum CDummySHMProvider { } #[cfg(all(feature = "shared-memory", feature = "unstable"))] -/// @attention Unstable feature. +/// @warning This API has been marked as unstable: it works as advertised, but it may be changed in a future release. /// @brief An owned ShmProvider. get_opaque_type_data!(Option, z_owned_shm_provider_t); #[cfg(all(feature = "shared-memory", feature = "unstable"))] -/// @attention Unstable feature. +/// @warning This API has been marked as unstable: it works as advertised, but it may be changed in a future release. /// @brief A loaned ShmProvider. get_opaque_type_data!(CDummySHMProvider, z_loaned_shm_provider_t); @@ -430,11 +430,11 @@ enum CSHMLayout { } #[cfg(all(feature = "shared-memory", feature = "unstable"))] -/// @attention Unstable feature. +/// @warning This API has been marked as unstable: it works as advertised, but it may be changed in a future release. /// @brief An owned ShmProvider's AllocLayout. get_opaque_type_data!(Option, z_owned_alloc_layout_t); #[cfg(all(feature = "shared-memory", feature = "unstable"))] -/// @attention Unstable feature. +/// @warning This API has been marked as unstable: it works as advertised, but it may be changed in a future release. /// @brief A loaned ShmProvider's AllocLayout. get_opaque_type_data!(CSHMLayout, z_loaned_alloc_layout_t); @@ -481,14 +481,14 @@ get_opaque_type_data!( get_opaque_type_data!(RingChannelHandler, z_loaned_ring_handler_reply_t); #[cfg(feature = "unstable")] -/// @attention Unstable feature. +/// @warning This API has been marked as unstable: it works as advertised, but it may be changed in a future release. /// @brief An owned Zenoh-allocated source info`. get_opaque_type_data!(SourceInfo, z_owned_source_info_t); #[cfg(feature = "unstable")] -/// @attention Unstable feature. +/// @warning This API has been marked as unstable: it works as advertised, but it may be changed in a future release. /// @brief A loaned source info. get_opaque_type_data!(SourceInfo, z_loaned_source_info_t); #[cfg(feature = "unstable")] -/// @attention Unstable feature. +/// @warning This API has been marked as unstable: it works as advertised, but it may be changed in a future release. /// @brief An entity gloabal id. get_opaque_type_data!(EntityGlobalId, z_entity_global_id_t); diff --git a/docs/api.rst b/docs/api.rst index f50d7fa54..fd2b72f44 100644 --- a/docs/api.rst +++ b/docs/api.rst @@ -501,11 +501,13 @@ Types .. doxygenstruct:: z_put_options_t :members: .. doxygenstruct:: z_delete_options_t + :members: .. doxygenstruct:: z_publisher_options_t :members: .. doxygenstruct:: z_publisher_put_options_t :members: .. doxygenstruct:: z_publisher_delete_options_t + :members: .. doxygenstruct:: zc_owned_matching_listener_t .. doxygenstruct:: zc_owned_closure_matching_status_t diff --git a/include/zenoh_commons.h b/include/zenoh_commons.h index 9c8ec9a13..12ae60dbc 100644 --- a/include/zenoh_commons.h +++ b/include/zenoh_commons.h @@ -17,7 +17,7 @@ #define ZENOHC_API #endif /** - * @attention Unstable feature. + * @warning This API has been marked as unstable: it works as advertised, but it may be changed in a future release. * @brief Allocation errors */ #if (defined(SHARED_MEMORY) && defined(UNSTABLE)) @@ -80,7 +80,7 @@ typedef enum z_consolidation_mode_t { Z_CONSOLIDATION_MODE_LATEST = 2, } z_consolidation_mode_t; /** - * @attention Unstable feature. + * @warning This API has been marked as unstable: it works as advertised, but it may be changed in a future release. * @brief Intersection level of 2 key expressions. */ #if defined(UNSTABLE) @@ -104,7 +104,7 @@ typedef enum z_keyexpr_intersection_level_t { } z_keyexpr_intersection_level_t; #endif /** - * @attention Unstable feature. + * @warning This API has been marked as unstable: it works as advertised, but it may be changed in a future release. * @brief Layouting errors */ #if (defined(SHARED_MEMORY) && defined(UNSTABLE)) @@ -174,7 +174,7 @@ typedef enum z_query_target_t { Z_QUERY_TARGET_ALL_COMPLETE, } z_query_target_t; /** - * @attention Unstable feature. + * @warning This API has been marked as unstable: it works as advertised, but it may be changed in a future release. * @brief The publisher reliability. * @note Currently `reliability` does not trigger any data retransmission on the wire. * It is rather used as a marker on the wire and it may be used to select the best link available (e.g. TCP for reliable data and UDP for best effort data). @@ -216,7 +216,7 @@ typedef enum z_whatami_t { Z_WHATAMI_CLIENT = 4, } z_whatami_t; /** - * @attention Unstable feature. + * @warning This API has been marked as unstable: it works as advertised, but it may be changed in a future release. * @brief Status of SHM buffer allocation operation. */ #if (defined(SHARED_MEMORY) && defined(UNSTABLE)) @@ -236,7 +236,7 @@ typedef enum zc_buf_alloc_status_t { } zc_buf_alloc_status_t; #endif /** - * @attention Unstable feature. + * @warning This API has been marked as unstable: it works as advertised, but it may be changed in a future release. * @brief Status of SHM buffer layouting + allocation operation. */ #if (defined(SHARED_MEMORY) && defined(UNSTABLE)) @@ -314,7 +314,7 @@ typedef enum zc_log_severity_t { ZC_LOG_SEVERITY_ERROR = 4, } zc_log_severity_t; /** - * @attention Unstable feature. + * @warning This API has been marked as unstable: it works as advertised, but it may be changed in a future release. * @brief Key expressions types to which Queryable should reply to. */ #if defined(UNSTABLE) @@ -330,7 +330,7 @@ typedef enum zc_reply_keyexpr_t { } zc_reply_keyexpr_t; #endif /** - * @attention Unstable feature. + * @warning This API has been marked as unstable: it works as advertised, but it may be changed in a future release. * @brief A result of SHM buffer allocation operation. */ #if (defined(SHARED_MEMORY) && defined(UNSTABLE)) @@ -342,7 +342,7 @@ typedef struct z_buf_alloc_result_t { #endif typedef int8_t z_result_t; /** - * @attention Unstable feature. + * @warning This API has been marked as unstable: it works as advertised, but it may be changed in a future release. * @brief An AllocAlignment. */ #if (defined(SHARED_MEMORY) && defined(UNSTABLE)) @@ -392,21 +392,21 @@ typedef struct ALIGN(8) z_bytes_slice_iterator_t { uint8_t _0[24]; } z_bytes_slice_iterator_t; /** - * @attention Unstable feature. + * @warning This API has been marked as unstable: it works as advertised, but it may be changed in a future release. * @brief Unique segment identifier. */ #if (defined(SHARED_MEMORY) && defined(UNSTABLE)) typedef uint32_t z_segment_id_t; #endif /** - * @attention Unstable feature. + * @warning This API has been marked as unstable: it works as advertised, but it may be changed in a future release. * @brief Chunk id within it's segment. */ #if (defined(SHARED_MEMORY) && defined(UNSTABLE)) typedef uint32_t z_chunk_id_t; #endif /** - * @attention Unstable feature. + * @warning This API has been marked as unstable: it works as advertised, but it may be changed in a future release. * @brief A ChunkDescriptor. */ #if (defined(SHARED_MEMORY) && defined(UNSTABLE)) @@ -417,7 +417,7 @@ typedef struct z_chunk_descriptor_t { } z_chunk_descriptor_t; #endif /** - * @attention Unstable feature. + * @warning This API has been marked as unstable: it works as advertised, but it may be changed in a future release. * @brief An AllocatedChunk. */ #if (defined(SHARED_MEMORY) && defined(UNSTABLE)) @@ -558,7 +558,7 @@ typedef struct z_moved_closure_sample_t { struct z_owned_closure_sample_t _this; } z_moved_closure_sample_t; /** - * @attention Unstable feature. + * @warning This API has been marked as unstable: it works as advertised, but it may be changed in a future release. * @brief A closure is a structure that contains all the elements for stateful, memory-leak-free callbacks: * * Closures are not guaranteed not to be called concurrently. @@ -585,7 +585,7 @@ typedef struct z_owned_closure_zid_t { } z_owned_closure_zid_t; #endif /** - * @attention Unstable feature. + * @warning This API has been marked as unstable: it works as advertised, but it may be changed in a future release. * @brief Moved closure. */ #if defined(UNSTABLE) @@ -624,7 +624,7 @@ typedef struct z_publisher_options_t { bool is_express; #if defined(UNSTABLE) /** - * @attention Unstable feature. + * @warning This API has been marked as unstable: it works as advertised, but it may be changed in a future release. * * The publisher reliability. */ @@ -632,7 +632,7 @@ typedef struct z_publisher_options_t { #endif #if defined(UNSTABLE) /** - * @attention Unstable feature. + * @warning This API has been marked as unstable: it works as advertised, but it may be changed in a future release. * * The allowed destination for this publisher. */ @@ -679,7 +679,7 @@ typedef struct z_delete_options_t { struct z_timestamp_t *timestamp; #if defined(UNSTABLE) /** - * @attention Unstable feature. + * @warning This API has been marked as unstable: it works as advertised, but it may be changed in a future release. * * The delete operation reliability. */ @@ -687,7 +687,7 @@ typedef struct z_delete_options_t { #endif #if defined(UNSTABLE) /** - * @attention Unstable feature. + * @warning This API has been marked as unstable: it works as advertised, but it may be changed in a future release. * * The allowed destination of this message. */ @@ -739,7 +739,7 @@ typedef struct z_get_options_t { bool is_express; #if defined(UNSTABLE) /** - * @attention Unstable feature. + * @warning This API has been marked as unstable: it works as advertised, but it may be changed in a future release. * * The allowed destination for the query. */ @@ -747,7 +747,7 @@ typedef struct z_get_options_t { #endif #if defined(UNSTABLE) /** - * @attention Unstable feature. + * @warning This API has been marked as unstable: it works as advertised, but it may be changed in a future release. * * The accepted replies for the query. */ @@ -759,7 +759,7 @@ typedef struct z_get_options_t { enum z_priority_t priority; #if defined(UNSTABLE) /** - * @attention Unstable feature. + * @warning This API has been marked as unstable: it works as advertised, but it may be changed in a future release. * * The source info for the query. */ @@ -810,7 +810,7 @@ typedef struct z_publisher_put_options_t { const struct z_timestamp_t *timestamp; #if defined(UNSTABLE) /** - * @attention Unstable feature. + * @warning This API has been marked as unstable: it works as advertised, but it may be changed in a future release. * * The source info for the publication. */ @@ -847,7 +847,7 @@ typedef struct z_put_options_t { struct z_timestamp_t *timestamp; #if defined(UNSTABLE) /** - * @attention Unstable feature. + * @warning This API has been marked as unstable: it works as advertised, but it may be changed in a future release. * * The put operation reliability. */ @@ -855,7 +855,7 @@ typedef struct z_put_options_t { #endif #if defined(UNSTABLE) /** - * @attention Unstable feature. + * @warning This API has been marked as unstable: it works as advertised, but it may be changed in a future release. * * The allowed destination of this message. */ @@ -863,7 +863,7 @@ typedef struct z_put_options_t { #endif #if defined(UNSTABLE) /** - * @attention Unstable feature. + * @warning This API has been marked as unstable: it works as advertised, but it may be changed in a future release. * * The source info for the message. */ @@ -904,7 +904,7 @@ typedef struct z_query_reply_options_t { struct z_timestamp_t *timestamp; #if defined(UNSTABLE) /** - * @attention Unstable feature. + * @warning This API has been marked as unstable: it works as advertised, but it may be changed in a future release. * * The source info for the reply. */ @@ -938,7 +938,7 @@ typedef struct z_query_reply_del_options_t { struct z_timestamp_t *timestamp; #if defined(UNSTABLE) /** - * @attention Unstable feature. + * @warning This API has been marked as unstable: it works as advertised, but it may be changed in a future release. * * The source info for the reply. */ @@ -994,7 +994,7 @@ typedef struct z_scout_options_t { enum z_what_t what; } z_scout_options_t; /** - * @attention Unstable feature. + * @warning This API has been marked as unstable: it works as advertised, but it may be changed in a future release. * @brief Callbacks for ShmSegment. */ #if (defined(SHARED_MEMORY) && defined(UNSTABLE)) @@ -1003,7 +1003,7 @@ typedef struct zc_shm_segment_callbacks_t { } zc_shm_segment_callbacks_t; #endif /** - * @attention Unstable feature. + * @warning This API has been marked as unstable: it works as advertised, but it may be changed in a future release. * @brief An ShmSegment. */ #if (defined(SHARED_MEMORY) && defined(UNSTABLE)) @@ -1013,7 +1013,7 @@ typedef struct z_shm_segment_t { } z_shm_segment_t; #endif /** - * @attention Unstable feature. + * @warning This API has been marked as unstable: it works as advertised, but it may be changed in a future release. * @brief Callback for ShmClient. */ #if (defined(SHARED_MEMORY) && defined(UNSTABLE)) @@ -1022,7 +1022,7 @@ typedef struct zc_shm_client_callbacks_t { } zc_shm_client_callbacks_t; #endif /** - * @attention Unstable feature. + * @warning This API has been marked as unstable: it works as advertised, but it may be changed in a future release. * @brief A result of SHM buffer layouting + allocation operation. */ #if (defined(SHARED_MEMORY) && defined(UNSTABLE)) @@ -1034,7 +1034,7 @@ typedef struct z_buf_layout_alloc_result_t { } z_buf_layout_alloc_result_t; #endif /** - * @attention Unstable feature. + * @warning This API has been marked as unstable: it works as advertised, but it may be changed in a future release. * @brief Unique protocol identifier. * Here is a contract: it is up to user to make sure that incompatible ShmClient * and ShmProviderBackend implementations will never use the same ProtocolID. @@ -1069,7 +1069,7 @@ typedef struct zc_context_t { } zc_context_t; #endif /** - * @attention Unstable feature. + * @warning This API has been marked as unstable: it works as advertised, but it may be changed in a future release. * @brief Callbacks for ShmProviderBackend. */ #if (defined(SHARED_MEMORY) && defined(UNSTABLE)) @@ -1132,7 +1132,7 @@ typedef struct zc_moved_closure_log_t { struct zc_owned_closure_log_t _this; } zc_moved_closure_log_t; /** - * @attention Unstable feature. + * @warning This API has been marked as unstable: it works as advertised, but it may be changed in a future release. * @brief Loaned closure. */ #if defined(UNSTABLE) @@ -1141,7 +1141,7 @@ typedef struct zc_loaned_closure_matching_status_t { } zc_loaned_closure_matching_status_t; #endif /** - * @attention Unstable feature. + * @warning This API has been marked as unstable: it works as advertised, but it may be changed in a future release. * @brief A struct that indicates if there exist Subscribers matching the Publisher's key expression. */ #if defined(UNSTABLE) @@ -1153,7 +1153,7 @@ typedef struct zc_matching_status_t { } zc_matching_status_t; #endif /** - * @attention Unstable feature. + * @warning This API has been marked as unstable: it works as advertised, but it may be changed in a future release. * @brief A closure is a structure that contains all the elements for stateful, memory-leak-free callbacks: * * Closures are not guaranteed not to be called concurrently. @@ -1180,7 +1180,7 @@ typedef struct zc_owned_closure_matching_status_t { } zc_owned_closure_matching_status_t; #endif /** - * @attention Unstable feature. + * @warning This API has been marked as unstable: it works as advertised, but it may be changed in a future release. * @brief Moved closure. */ #if defined(UNSTABLE) @@ -1189,7 +1189,7 @@ typedef struct zc_moved_closure_matching_status_t { } zc_moved_closure_matching_status_t; #endif /** - * @attention Unstable feature. + * @warning This API has been marked as unstable: it works as advertised, but it may be changed in a future release. * @brief The options for `zc_liveliness_declare_token()`. */ #if defined(UNSTABLE) @@ -1198,7 +1198,7 @@ typedef struct zc_liveliness_declaration_options_t { } zc_liveliness_declaration_options_t; #endif /** - * @attention Unstable feature. + * @warning This API has been marked as unstable: it works as advertised, but it may be changed in a future release. * @brief The options for `zc_liveliness_declare_subscriber()` */ #if defined(UNSTABLE) @@ -1207,7 +1207,7 @@ typedef struct zc_liveliness_subscriber_options_t { } zc_liveliness_subscriber_options_t; #endif /** - * @attention Unstable feature. + * @warning This API has been marked as unstable: it works as advertised, but it may be changed in a future release. * @brief The options for `zc_liveliness_get()` */ #if defined(UNSTABLE) @@ -1216,7 +1216,7 @@ typedef struct zc_liveliness_get_options_t { } zc_liveliness_get_options_t; #endif /** - * @attention Unstable feature. + * @warning This API has been marked as unstable: it works as advertised, but it may be changed in a future release. * @brief Options passed to the `ze_declare_publication_cache()` function. */ #if defined(UNSTABLE) @@ -1246,7 +1246,7 @@ typedef struct ze_publication_cache_options_t { } ze_publication_cache_options_t; #endif /** - * @attention Unstable feature. + * @warning This API has been marked as unstable: it works as advertised, but it may be changed in a future release. * @brief A set of options that can be applied to a querying subscriber, * upon its declaration via `ze_declare_querying_subscriber()`. * @@ -1341,7 +1341,7 @@ ZENOHC_API void z_alloc_layout_drop(z_moved_alloc_layout_t *this_); ZENOHC_API const z_loaned_alloc_layout_t *z_alloc_layout_loan(const z_owned_alloc_layout_t *this_); #endif /** - * @attention Unstable feature. + * @warning This API has been marked as unstable: it works as advertised, but it may be changed in a future release. * @brief Creates a new Alloc Layout for SHM Provider. */ #if (defined(SHARED_MEMORY) && defined(UNSTABLE)) @@ -1406,7 +1406,7 @@ ZENOHC_API z_result_t z_bytes_deserialize_into_int8(const struct z_loaned_bytes_t *this_, int8_t *dst); /** - * @attention Unstable feature. + * @warning This API has been marked as unstable: it works as advertised, but it may be changed in a future release. * @brief Deserializes data into a loaned SHM buffer. * * @param this_: Data to deserialize. @@ -1418,7 +1418,7 @@ z_result_t z_bytes_deserialize_into_loaned_shm(const struct z_loaned_bytes_t *th const z_loaned_shm_t **dst); #endif /** - * @attention Unstable feature. + * @warning This API has been marked as unstable: it works as advertised, but it may be changed in a future release. * @brief Deserializes data into a mutably loaned SHM buffer. * * @param this_: Data to deserialize. @@ -1430,7 +1430,7 @@ z_result_t z_bytes_deserialize_into_mut_loaned_shm(struct z_loaned_bytes_t *this z_loaned_shm_t **dst); #endif /** - * @attention Unstable feature. + * @warning This API has been marked as unstable: it works as advertised, but it may be changed in a future release. * @brief Deserializes data into an owned SHM buffer by copying it's shared reference. * * @param this_: Data to deserialize. @@ -1701,14 +1701,16 @@ ZENOHC_API void z_bytes_serialize_from_int64(struct z_owned_bytes_t *this_, int6 */ ZENOHC_API void z_bytes_serialize_from_int8(struct z_owned_bytes_t *this_, int8_t val); /** - * @attention Unstable feature. + * @warning This API has been marked as unstable: it works as advertised, but it may be changed in a future release. * @brief Serializes from an immutable SHM buffer consuming it. */ #if (defined(SHARED_MEMORY) && defined(UNSTABLE)) -ZENOHC_API z_result_t z_bytes_serialize_from_shm(struct z_owned_bytes_t *this_, z_moved_shm_t *shm); +ZENOHC_API +z_result_t z_bytes_serialize_from_shm(struct z_owned_bytes_t *this_, + z_moved_shm_t *shm); #endif /** - * @attention Unstable feature. + * @warning This API has been marked as unstable: it works as advertised, but it may be changed in a future release. * @brief Serializes from a mutable SHM buffer consuming it. */ #if (defined(SHARED_MEMORY) && defined(UNSTABLE)) @@ -1788,14 +1790,15 @@ z_result_t z_bytes_writer_write_all(struct z_bytes_writer_t *this_, const uint8_t *src, size_t len); /** - * @attention Unstable feature. + * @warning This API has been marked as unstable: it works as advertised, but it may be changed in a future release. * @brief Deletes Chunk Alloc Result. */ #if (defined(SHARED_MEMORY) && defined(UNSTABLE)) -ZENOHC_API void z_chunk_alloc_result_drop(z_moved_chunk_alloc_result_t *this_); +ZENOHC_API +void z_chunk_alloc_result_drop(z_moved_chunk_alloc_result_t *this_); #endif /** - * @attention Unstable feature. + * @warning This API has been marked as unstable: it works as advertised, but it may be changed in a future release. * @brief Borrows Chunk Alloc Result. */ #if (defined(SHARED_MEMORY) && defined(UNSTABLE)) @@ -1803,7 +1806,7 @@ ZENOHC_API const z_loaned_chunk_alloc_result_t *z_chunk_alloc_result_loan(const z_owned_chunk_alloc_result_t *this_); #endif /** - * @attention Unstable feature. + * @warning This API has been marked as unstable: it works as advertised, but it may be changed in a future release. * @brief Creates a new Chunk Alloc Result with Error value. */ #if (defined(SHARED_MEMORY) && defined(UNSTABLE)) @@ -1812,7 +1815,7 @@ void z_chunk_alloc_result_new_error(z_owned_chunk_alloc_result_t *this_, enum z_alloc_error_t alloc_error); #endif /** - * @attention Unstable feature. + * @warning This API has been marked as unstable: it works as advertised, but it may be changed in a future release. * @brief Creates a new Chunk Alloc Result with Ok value. */ #if (defined(SHARED_MEMORY) && defined(UNSTABLE)) @@ -1906,7 +1909,7 @@ ZENOHC_API void z_closure_sample_drop(struct z_moved_closure_sample_t *closure_) ZENOHC_API const struct z_loaned_closure_sample_t *z_closure_sample_loan(const struct z_owned_closure_sample_t *closure); /** - * @attention Unstable feature. + * @warning This API has been marked as unstable: it works as advertised, but it may be changed in a future release. * @brief Calls the closure. Calling an uninitialized closure is a no-op. */ #if defined(UNSTABLE) @@ -1915,7 +1918,7 @@ void z_closure_zid_call(const struct z_loaned_closure_zid_t *closure, const z_id_t *z_id); #endif /** - * @attention Unstable feature. + * @warning This API has been marked as unstable: it works as advertised, but it may be changed in a future release. * @brief Drops the closure, resetting it to its gravestone state. Droping an uninitialized (null) closure is a no-op. */ #if defined(UNSTABLE) @@ -1923,7 +1926,7 @@ ZENOHC_API void z_closure_zid_drop(struct z_moved_closure_zid_t *closure_); #endif /** - * @attention Unstable feature. + * @warning This API has been marked as unstable: it works as advertised, but it may be changed in a future release. * @brief Borrows closure. */ #if defined(UNSTABLE) @@ -2570,18 +2573,20 @@ ZENOHC_API const struct z_loaned_encoding_t *z_encoding_zenoh_uint64(void); */ ZENOHC_API const struct z_loaned_encoding_t *z_encoding_zenoh_uint8(void); /** - * @attention Unstable feature. + * @warning This API has been marked as unstable: it works as advertised, but it may be changed in a future release. * @brief Returns the entity id of the entity global id. */ #if defined(UNSTABLE) -ZENOHC_API uint32_t z_entity_global_id_eid(const z_entity_global_id_t *this_); +ZENOHC_API +uint32_t z_entity_global_id_eid(const z_entity_global_id_t *this_); #endif /** - * @attention Unstable feature. + * @warning This API has been marked as unstable: it works as advertised, but it may be changed in a future release. * @brief Returns the zenoh id of entity global id. */ #if defined(UNSTABLE) -ZENOHC_API z_id_t z_entity_global_id_zid(const z_entity_global_id_t *this_); +ZENOHC_API +z_id_t z_entity_global_id_zid(const z_entity_global_id_t *this_); #endif /** * Constructs send and recieve ends of the fifo channel @@ -2724,21 +2729,24 @@ void z_hello_locators(const struct z_loaned_hello_t *this_, */ ZENOHC_API enum z_whatami_t z_hello_whatami(const struct z_loaned_hello_t *this_); /** - * @attention Unstable feature. + * @warning This API has been marked as unstable: it works as advertised, but it may be changed in a future release. * @brief Returns id of Zenoh entity that transmitted hello message. */ #if defined(UNSTABLE) -ZENOHC_API z_id_t z_hello_zid(const struct z_loaned_hello_t *this_); +ZENOHC_API +z_id_t z_hello_zid(const struct z_loaned_hello_t *this_); #endif /** - * @attention Unstable feature. + * @warning This API has been marked as unstable: it works as advertised, but it may be changed in a future release. * @brief Formats the `z_id_t` into 16-digit hex string (LSB-first order) */ #if defined(UNSTABLE) -ZENOHC_API void z_id_to_string(const z_id_t *zid, struct z_owned_string_t *dst); +ZENOHC_API +void z_id_to_string(const z_id_t *zid, + struct z_owned_string_t *dst); #endif /** - * @attention Unstable feature. + * @warning This API has been marked as unstable: it works as advertised, but it may be changed in a future release. * @brief Fetches the Zenoh IDs of all connected peers. * * `callback` will be called once for each ID, is guaranteed to never be called concurrently, @@ -2752,7 +2760,7 @@ z_result_t z_info_peers_zid(const struct z_loaned_session_t *session, struct z_moved_closure_zid_t *callback); #endif /** - * @attention Unstable feature. + * @warning This API has been marked as unstable: it works as advertised, but it may be changed in a future release. * @brief Fetches the Zenoh IDs of all connected routers. * * `callback` will be called once for each ID, is guaranteed to never be called concurrently, @@ -2766,7 +2774,7 @@ z_result_t z_info_routers_zid(const struct z_loaned_session_t *session, struct z_moved_closure_zid_t *callback); #endif /** - * @attention Unstable feature. + * @warning This API has been marked as unstable: it works as advertised, but it may be changed in a future release. * @brief Returns the session's Zenoh ID. * * Unless the `session` is invalid, that ID is guaranteed to be non-zero. @@ -2774,7 +2782,8 @@ z_result_t z_info_routers_zid(const struct z_loaned_session_t *session, * to pass it a valid session. */ #if defined(UNSTABLE) -ZENOHC_API z_id_t z_info_zid(const struct z_loaned_session_t *session); +ZENOHC_API +z_id_t z_info_zid(const struct z_loaned_session_t *session); #endif /** * Returns ``true`` if `this` is valid. @@ -2797,18 +2806,20 @@ ZENOHC_API bool z_internal_bytes_check(const struct z_owned_bytes_t *this_); */ ZENOHC_API void z_internal_bytes_null(struct z_owned_bytes_t *this_); /** - * @attention Unstable feature. + * @warning This API has been marked as unstable: it works as advertised, but it may be changed in a future release. * @return ``true`` if `this` is valid. */ #if (defined(SHARED_MEMORY) && defined(UNSTABLE)) -ZENOHC_API bool z_internal_chunk_alloc_result_check(const z_owned_chunk_alloc_result_t *this_); +ZENOHC_API +bool z_internal_chunk_alloc_result_check(const z_owned_chunk_alloc_result_t *this_); #endif /** - * @attention Unstable feature. + * @warning This API has been marked as unstable: it works as advertised, but it may be changed in a future release. * @brief Constructs Chunk Alloc Result in its gravestone value. */ #if (defined(SHARED_MEMORY) && defined(UNSTABLE)) -ZENOHC_API void z_internal_chunk_alloc_result_null(z_owned_chunk_alloc_result_t *this_); +ZENOHC_API +void z_internal_chunk_alloc_result_null(z_owned_chunk_alloc_result_t *this_); #endif /** * Returns ``true`` if closure is valid, ``false`` if it is in gravestone state. @@ -2843,18 +2854,20 @@ ZENOHC_API bool z_internal_closure_sample_check(const struct z_owned_closure_sam */ ZENOHC_API void z_internal_closure_sample_null(struct z_owned_closure_sample_t *this_); /** - * @attention Unstable feature. + * @warning This API has been marked as unstable: it works as advertised, but it may be changed in a future release. * @brief Returns ``true`` if closure is valid, ``false`` if it is in gravestone state. */ #if defined(UNSTABLE) -ZENOHC_API bool z_internal_closure_zid_check(const struct z_owned_closure_zid_t *this_); +ZENOHC_API +bool z_internal_closure_zid_check(const struct z_owned_closure_zid_t *this_); #endif /** - * @attention Unstable feature. + * @warning This API has been marked as unstable: it works as advertised, but it may be changed in a future release. * @brief Constructs a null closure. */ #if defined(UNSTABLE) -ZENOHC_API void z_internal_closure_zid_null(struct z_owned_closure_zid_t *this_); +ZENOHC_API +void z_internal_closure_zid_null(struct z_owned_closure_zid_t *this_); #endif /** * Returns ``true`` if conditional variable is valid, ``false`` otherwise. @@ -2924,18 +2937,20 @@ ZENOHC_API bool z_internal_keyexpr_check(const struct z_owned_keyexpr_t *this_); */ ZENOHC_API void z_internal_keyexpr_null(struct z_owned_keyexpr_t *this_); /** - * @attention Unstable feature. + * @warning This API has been marked as unstable: it works as advertised, but it may be changed in a future release. * @brief Returns ``true`` if `this` is valid. */ #if (defined(SHARED_MEMORY) && defined(UNSTABLE)) -ZENOHC_API bool z_internal_memory_layout_check(const z_owned_memory_layout_t *this_); +ZENOHC_API +bool z_internal_memory_layout_check(const z_owned_memory_layout_t *this_); #endif /** - * @attention Unstable feature. + * @warning This API has been marked as unstable: it works as advertised, but it may be changed in a future release. * @brief Constructs Memory Layout in its gravestone value. */ #if (defined(SHARED_MEMORY) && defined(UNSTABLE)) -ZENOHC_API void z_internal_memory_layout_null(z_owned_memory_layout_t *this_); +ZENOHC_API +void z_internal_memory_layout_null(z_owned_memory_layout_t *this_); #endif /** * Returns ``true`` if mutex is valid, ``false`` otherwise. @@ -3029,74 +3044,84 @@ ZENOHC_API bool z_internal_session_check(const struct z_owned_session_t *this_); */ ZENOHC_API void z_internal_session_null(struct z_owned_session_t *this_); /** - * @attention Unstable feature. + * @warning This API has been marked as unstable: it works as advertised, but it may be changed in a future release. * @return ``true`` if `this` is valid. */ #if (defined(SHARED_MEMORY) && defined(UNSTABLE)) -ZENOHC_API bool z_internal_shm_check(const z_owned_shm_t *this_); +ZENOHC_API +bool z_internal_shm_check(const z_owned_shm_t *this_); #endif /** - * @attention Unstable feature. + * @warning This API has been marked as unstable: it works as advertised, but it may be changed in a future release. * @return Returns ``true`` if `this` is valid. */ #if (defined(SHARED_MEMORY) && defined(UNSTABLE)) -ZENOHC_API bool z_internal_shm_client_check(const z_owned_shm_client_t *this_); +ZENOHC_API +bool z_internal_shm_client_check(const z_owned_shm_client_t *this_); #endif /** - * @attention Unstable feature. + * @warning This API has been marked as unstable: it works as advertised, but it may be changed in a future release. * @brief Constructs SHM client in its gravestone value. */ #if (defined(SHARED_MEMORY) && defined(UNSTABLE)) -ZENOHC_API void z_internal_shm_client_null(z_owned_shm_client_t *this_); +ZENOHC_API +void z_internal_shm_client_null(z_owned_shm_client_t *this_); #endif /** - * @attention Unstable feature. + * @warning This API has been marked as unstable: it works as advertised, but it may be changed in a future release. * @return ``true`` if `this` is valid. */ #if (defined(SHARED_MEMORY) && defined(UNSTABLE)) -ZENOHC_API bool z_internal_shm_client_storage_check(const z_owned_shm_client_storage_t *this_); +ZENOHC_API +bool z_internal_shm_client_storage_check(const z_owned_shm_client_storage_t *this_); #endif /** - * @attention Unstable feature. + * @warning This API has been marked as unstable: it works as advertised, but it may be changed in a future release. * Constructs SHM Client Storage in its gravestone value. */ #if (defined(SHARED_MEMORY) && defined(UNSTABLE)) -ZENOHC_API void z_internal_shm_client_storage_null(z_owned_shm_client_storage_t *this_); +ZENOHC_API +void z_internal_shm_client_storage_null(z_owned_shm_client_storage_t *this_); #endif /** - * @attention Unstable feature. + * @warning This API has been marked as unstable: it works as advertised, but it may be changed in a future release. * @return ``true`` if `this` is valid. */ #if (defined(SHARED_MEMORY) && defined(UNSTABLE)) -ZENOHC_API bool z_internal_shm_mut_check(const z_owned_shm_mut_t *this_); +ZENOHC_API +bool z_internal_shm_mut_check(const z_owned_shm_mut_t *this_); #endif /** - * @attention Unstable feature. + * @warning This API has been marked as unstable: it works as advertised, but it may be changed in a future release. * @brief Constructs ZShmMut slice in its gravestone value. */ #if (defined(SHARED_MEMORY) && defined(UNSTABLE)) -ZENOHC_API void z_internal_shm_mut_null(z_owned_shm_mut_t *this_); +ZENOHC_API +void z_internal_shm_mut_null(z_owned_shm_mut_t *this_); #endif /** - * @attention Unstable feature. + * @warning This API has been marked as unstable: it works as advertised, but it may be changed in a future release. * @brief Constructs ZShm slice in its gravestone value. */ #if (defined(SHARED_MEMORY) && defined(UNSTABLE)) -ZENOHC_API void z_internal_shm_null(z_owned_shm_t *this_); +ZENOHC_API +void z_internal_shm_null(z_owned_shm_t *this_); #endif /** - * @attention Unstable feature. + * @warning This API has been marked as unstable: it works as advertised, but it may be changed in a future release. * @brief Returns ``true`` if `this` is valid. */ #if (defined(SHARED_MEMORY) && defined(UNSTABLE)) -ZENOHC_API bool z_internal_shm_provider_check(const z_owned_shm_provider_t *this_); +ZENOHC_API +bool z_internal_shm_provider_check(const z_owned_shm_provider_t *this_); #endif /** - * @attention Unstable feature. + * @warning This API has been marked as unstable: it works as advertised, but it may be changed in a future release. * @brief Constructs SHM Provider in its gravestone value. */ #if (defined(SHARED_MEMORY) && defined(UNSTABLE)) -ZENOHC_API void z_internal_shm_provider_null(z_owned_shm_provider_t *this_); +ZENOHC_API +void z_internal_shm_provider_null(z_owned_shm_provider_t *this_); #endif /** * @return ``true`` if slice is not empty, ``false`` otherwise. @@ -3107,18 +3132,20 @@ ZENOHC_API bool z_internal_slice_check(const struct z_owned_slice_t *this_); */ ZENOHC_API void z_internal_slice_null(struct z_owned_slice_t *this_); /** - * @attention Unstable feature. + * @warning This API has been marked as unstable: it works as advertised, but it may be changed in a future release. * @brief Returns ``true`` if source info is valid, ``false`` if it is in gravestone state. */ #if defined(UNSTABLE) -ZENOHC_API bool z_internal_source_info_check(const z_owned_source_info_t *this_); +ZENOHC_API +bool z_internal_source_info_check(const z_owned_source_info_t *this_); #endif /** - * @attention Unstable feature. + * @warning This API has been marked as unstable: it works as advertised, but it may be changed in a future release. * @brief Constructs source info in its gravestone state. */ #if defined(UNSTABLE) -ZENOHC_API void z_internal_source_info_null(z_owned_source_info_t *this_); +ZENOHC_API +void z_internal_source_info_null(z_owned_source_info_t *this_); #endif /** * @return ``true`` if the string array is valid, ``false`` if it is in a gravestone state. @@ -3273,7 +3300,7 @@ z_result_t z_keyexpr_join(struct z_owned_keyexpr_t *this_, */ ZENOHC_API const struct z_loaned_keyexpr_t *z_keyexpr_loan(const struct z_owned_keyexpr_t *this_); /** - * @attention Unstable feature. + * @warning This API has been marked as unstable: it works as advertised, but it may be changed in a future release. * @brief Returns the relation between `left` and `right` from `left`'s point of view. * * @note This is slower than `z_keyexpr_intersects` and `keyexpr_includes`, so you should favor these methods for most applications. @@ -3284,14 +3311,15 @@ enum z_keyexpr_intersection_level_t z_keyexpr_relation_to(const struct z_loaned_ const struct z_loaned_keyexpr_t *right); #endif /** - * @attention Unstable feature. + * @warning This API has been marked as unstable: it works as advertised, but it may be changed in a future release. * @brief Deletes Memory Layout. */ #if (defined(SHARED_MEMORY) && defined(UNSTABLE)) -ZENOHC_API void z_memory_layout_drop(z_moved_memory_layout_t *this_); +ZENOHC_API +void z_memory_layout_drop(z_moved_memory_layout_t *this_); #endif /** - * @attention Unstable feature. + * @warning This API has been marked as unstable: it works as advertised, but it may be changed in a future release. * @brief Extract data from Memory Layout. */ #if (defined(SHARED_MEMORY) && defined(UNSTABLE)) @@ -3301,7 +3329,7 @@ void z_memory_layout_get_data(size_t *out_size, const z_loaned_memory_layout_t *this_); #endif /** - * @attention Unstable feature. + * @warning This API has been marked as unstable: it works as advertised, but it may be changed in a future release. * @brief Borrows Memory Layout. */ #if (defined(SHARED_MEMORY) && defined(UNSTABLE)) @@ -3309,7 +3337,7 @@ ZENOHC_API const z_loaned_memory_layout_t *z_memory_layout_loan(const z_owned_memory_layout_t *this_); #endif /** - * @attention Unstable feature. + * @warning This API has been marked as unstable: it works as advertised, but it may be changed in a future release. * @brief Creates a new Memory Layout. */ #if (defined(SHARED_MEMORY) && defined(UNSTABLE)) @@ -3356,7 +3384,7 @@ ZENOHC_API z_result_t z_open(struct z_owned_session_t *this_, struct z_moved_config_t *config); /** - * @attention Unstable feature. + * @warning This API has been marked as unstable: it works as advertised, but it may be changed in a future release. * @brief Constructs and opens a new Zenoh session with specified client storage. * * @return 0 in case of success, negative error code otherwise (in this case the session will be in its gravestone state). @@ -3368,14 +3396,15 @@ z_result_t z_open_with_custom_shm_clients(struct z_owned_session_t *this_, const z_loaned_shm_client_storage_t *shm_clients); #endif /** - * @attention Unstable feature. + * @warning This API has been marked as unstable: it works as advertised, but it may be changed in a future release. * @brief Creates a new POSIX SHM Client. */ #if (defined(SHARED_MEMORY) && defined(UNSTABLE)) -ZENOHC_API void z_posix_shm_client_new(z_owned_shm_client_t *this_); +ZENOHC_API +void z_posix_shm_client_new(z_owned_shm_client_t *this_); #endif /** - * @attention Unstable feature. + * @warning This API has been marked as unstable: it works as advertised, but it may be changed in a future release. * @brief Creates a new POSIX SHM Provider. */ #if (defined(SHARED_MEMORY) && defined(UNSTABLE)) @@ -3404,11 +3433,12 @@ ZENOHC_API void z_publisher_delete_options_default(struct z_publisher_delete_opt */ ZENOHC_API void z_publisher_drop(struct z_moved_publisher_t *this_); /** - * @attention Unstable feature. + * @warning This API has been marked as unstable: it works as advertised, but it may be changed in a future release. * @brief Returns the ID of the publisher. */ #if defined(UNSTABLE) -ZENOHC_API z_entity_global_id_t z_publisher_id(const struct z_loaned_publisher_t *publisher); +ZENOHC_API +z_entity_global_id_t z_publisher_id(const struct z_loaned_publisher_t *publisher); #endif /** * Returns the key expression of the publisher. @@ -3624,11 +3654,12 @@ ZENOHC_API enum z_query_target_t z_query_target_default(void); */ ZENOHC_API void z_queryable_drop(struct z_moved_queryable_t *this_); /** - * @attention Unstable feature. + * @warning This API has been marked as unstable: it works as advertised, but it may be changed in a future release. * @brief Returns the ID of the queryable. */ #if defined(UNSTABLE) -ZENOHC_API z_entity_global_id_t z_queryable_id(const struct z_loaned_queryable_t *queryable); +ZENOHC_API +z_entity_global_id_t z_queryable_id(const struct z_loaned_queryable_t *queryable); #endif ZENOHC_API const struct z_loaned_queryable_t *z_queryable_loan(const struct z_owned_queryable_t *this_); @@ -3657,17 +3688,19 @@ ZENOHC_API uint64_t z_random_u64(void); */ ZENOHC_API uint8_t z_random_u8(void); /** - * @attention Unstable feature. + * @warning This API has been marked as unstable: it works as advertised, but it may be changed in a future release. */ #if (defined(SHARED_MEMORY) && defined(UNSTABLE)) -ZENOHC_API void z_ref_shm_client_storage_global(z_owned_shm_client_storage_t *this_); +ZENOHC_API +void z_ref_shm_client_storage_global(z_owned_shm_client_storage_t *this_); #endif /** - * @attention Unstable feature. + * @warning This API has been marked as unstable: it works as advertised, but it may be changed in a future release. * @brief Returns the default value for `reliability`. */ #if defined(UNSTABLE) -ZENOHC_API enum z_reliability_t z_reliability_default(void); +ZENOHC_API +enum z_reliability_t z_reliability_default(void); #endif /** * Constructs an owned shallow copy of reply in provided uninitialized memory location. @@ -3718,12 +3751,14 @@ ZENOHC_API const struct z_loaned_reply_t *z_reply_loan(const struct z_owned_repl */ ZENOHC_API const struct z_loaned_sample_t *z_reply_ok(const struct z_loaned_reply_t *this_); /** - * @attention Unstable feature. + * @warning This API has been marked as unstable: it works as advertised, but it may be changed in a future release. * @brief Gets the id of the zenoh instance that answered this Reply. * @return `true` if id is present. */ #if defined(UNSTABLE) -ZENOHC_API bool z_reply_replier_id(const struct z_loaned_reply_t *this_, z_id_t *out_id); +ZENOHC_API +bool z_reply_replier_id(const struct z_loaned_reply_t *this_, + z_id_t *out_id); #endif /** * Constructs send and recieve ends of the ring channel @@ -3873,14 +3908,15 @@ ZENOHC_API const struct z_loaned_bytes_t *z_sample_payload(const struct z_loaned */ ZENOHC_API enum z_priority_t z_sample_priority(const struct z_loaned_sample_t *this_); /** - * @attention Unstable feature. - * @brief Returns the reliability setting the sample was delieverd with. + * @warning This API has been marked as unstable: it works as advertised, but it may be changed in a future release. + * @brief Returns the reliability setting the sample was delivered with. */ #if defined(UNSTABLE) -ZENOHC_API enum z_reliability_t z_sample_reliability(const struct z_loaned_sample_t *this_); +ZENOHC_API +enum z_reliability_t z_sample_reliability(const struct z_loaned_sample_t *this_); #endif /** - * @attention Unstable feature. + * @warning This API has been marked as unstable: it works as advertised, but it may be changed in a future release. * @brief Returns the sample source_info. */ #if defined(UNSTABLE) @@ -3927,14 +3963,15 @@ ZENOHC_API void z_session_drop(struct z_moved_session_t *this_); */ ZENOHC_API const struct z_loaned_session_t *z_session_loan(const struct z_owned_session_t *this_); /** - * @attention Unstable feature. + * @warning This API has been marked as unstable: it works as advertised, but it may be changed in a future release. * @brief Deletes SHM Client. */ #if (defined(SHARED_MEMORY) && defined(UNSTABLE)) -ZENOHC_API void z_shm_client_drop(z_moved_shm_client_t *this_); +ZENOHC_API +void z_shm_client_drop(z_moved_shm_client_t *this_); #endif /** - * @attention Unstable feature. + * @warning This API has been marked as unstable: it works as advertised, but it may be changed in a future release. * @brief Creates a new SHM Client. */ #if (defined(SHARED_MEMORY) && defined(UNSTABLE)) @@ -3944,7 +3981,7 @@ void z_shm_client_new(z_owned_shm_client_t *this_, struct zc_shm_client_callbacks_t callbacks); #endif /** - * @attention Unstable feature. + * @warning This API has been marked as unstable: it works as advertised, but it may be changed in a future release. * @brief Performs a shallow copy of SHM Client Storage. */ #if (defined(SHARED_MEMORY) && defined(UNSTABLE)) @@ -3953,14 +3990,15 @@ void z_shm_client_storage_clone(z_owned_shm_client_storage_t *this_, const z_loaned_shm_client_storage_t *from); #endif /** - * @attention Unstable feature. + * @warning This API has been marked as unstable: it works as advertised, but it may be changed in a future release. * @brief Derefs SHM Client Storage. */ #if (defined(SHARED_MEMORY) && defined(UNSTABLE)) -ZENOHC_API void z_shm_client_storage_drop(z_moved_shm_client_storage_t *this_); +ZENOHC_API +void z_shm_client_storage_drop(z_moved_shm_client_storage_t *this_); #endif /** - * @attention Unstable feature. + * @warning This API has been marked as unstable: it works as advertised, but it may be changed in a future release. * @brief Borrows SHM Client Storage. */ #if (defined(SHARED_MEMORY) && defined(UNSTABLE)) @@ -3968,7 +4006,7 @@ ZENOHC_API const z_loaned_shm_client_storage_t *z_shm_client_storage_loan(const z_owned_shm_client_storage_t *this_); #endif /** - * @attention Unstable feature. + * @warning This API has been marked as unstable: it works as advertised, but it may be changed in a future release. */ #if (defined(SHARED_MEMORY) && defined(UNSTABLE)) ZENOHC_API @@ -3977,13 +4015,14 @@ z_result_t z_shm_client_storage_new(z_owned_shm_client_storage_t *this_, bool add_default_client_set); #endif /** - * @attention Unstable feature. + * @warning This API has been marked as unstable: it works as advertised, but it may be changed in a future release. */ #if (defined(SHARED_MEMORY) && defined(UNSTABLE)) -ZENOHC_API void z_shm_client_storage_new_default(z_owned_shm_client_storage_t *this_); +ZENOHC_API +void z_shm_client_storage_new_default(z_owned_shm_client_storage_t *this_); #endif /** - * @attention Unstable feature. + * @warning This API has been marked as unstable: it works as advertised, but it may be changed in a future release. * @brief Converts borrowed ZShm slice to owned ZShm slice by performing a shallow SHM reference copy. */ #if (defined(SHARED_MEMORY) && defined(UNSTABLE)) @@ -3992,39 +4031,45 @@ void z_shm_clone(z_owned_shm_t *out, const z_loaned_shm_t *this_); #endif /** - * @attention Unstable feature. + * @warning This API has been marked as unstable: it works as advertised, but it may be changed in a future release. * @return the pointer of the ZShm slice. */ #if (defined(SHARED_MEMORY) && defined(UNSTABLE)) -ZENOHC_API const unsigned char *z_shm_data(const z_loaned_shm_t *this_); +ZENOHC_API +const unsigned char *z_shm_data(const z_loaned_shm_t *this_); #endif /** - * @attention Unstable feature. + * @warning This API has been marked as unstable: it works as advertised, but it may be changed in a future release. * @brief Deletes ZShm slice. */ #if (defined(SHARED_MEMORY) && defined(UNSTABLE)) -ZENOHC_API void z_shm_drop(z_moved_shm_t *this_); +ZENOHC_API +void z_shm_drop(z_moved_shm_t *this_); #endif /** - * @attention Unstable feature. + * @warning This API has been marked as unstable: it works as advertised, but it may be changed in a future release. * @brief Constructs ZShm slice from ZShmMut slice. */ #if (defined(SHARED_MEMORY) && defined(UNSTABLE)) -ZENOHC_API void z_shm_from_mut(z_owned_shm_t *this_, z_moved_shm_mut_t *that); +ZENOHC_API +void z_shm_from_mut(z_owned_shm_t *this_, + z_moved_shm_mut_t *that); #endif /** - * @attention Unstable feature. + * @warning This API has been marked as unstable: it works as advertised, but it may be changed in a future release. * @return the length of the ZShm slice. */ #if (defined(SHARED_MEMORY) && defined(UNSTABLE)) -ZENOHC_API size_t z_shm_len(const z_loaned_shm_t *this_); +ZENOHC_API +size_t z_shm_len(const z_loaned_shm_t *this_); #endif /** - * @attention Unstable feature. + * @warning This API has been marked as unstable: it works as advertised, but it may be changed in a future release. * @brief Borrows ZShm slice. */ #if (defined(SHARED_MEMORY) && defined(UNSTABLE)) -ZENOHC_API const z_loaned_shm_t *z_shm_loan(const z_owned_shm_t *this_); +ZENOHC_API +const z_loaned_shm_t *z_shm_loan(const z_owned_shm_t *this_); #endif /** * @brief Mutably borrows ZShm slice. @@ -4033,56 +4078,64 @@ ZENOHC_API const z_loaned_shm_t *z_shm_loan(const z_owned_shm_t *this_); ZENOHC_API z_loaned_shm_t *z_shm_loan_mut(z_owned_shm_t *this_); #endif /** - * @attention Unstable feature. + * @warning This API has been marked as unstable: it works as advertised, but it may be changed in a future release. * @return the immutable pointer to the underlying data. */ #if (defined(SHARED_MEMORY) && defined(UNSTABLE)) -ZENOHC_API const unsigned char *z_shm_mut_data(const z_loaned_shm_mut_t *this_); +ZENOHC_API +const unsigned char *z_shm_mut_data(const z_loaned_shm_mut_t *this_); #endif /** - * @attention Unstable feature. + * @warning This API has been marked as unstable: it works as advertised, but it may be changed in a future release. * @return the mutable pointer to the underlying data. */ #if (defined(SHARED_MEMORY) && defined(UNSTABLE)) -ZENOHC_API unsigned char *z_shm_mut_data_mut(z_loaned_shm_mut_t *this_); +ZENOHC_API +unsigned char *z_shm_mut_data_mut(z_loaned_shm_mut_t *this_); #endif /** - * @attention Unstable feature. + * @warning This API has been marked as unstable: it works as advertised, but it may be changed in a future release. * @brief Deletes ZShmMut slice. */ #if (defined(SHARED_MEMORY) && defined(UNSTABLE)) -ZENOHC_API void z_shm_mut_drop(z_moved_shm_mut_t *this_); +ZENOHC_API +void z_shm_mut_drop(z_moved_shm_mut_t *this_); #endif /** - * @attention Unstable feature. + * @warning This API has been marked as unstable: it works as advertised, but it may be changed in a future release. * @return the length of the ZShmMut slice. */ #if (defined(SHARED_MEMORY) && defined(UNSTABLE)) -ZENOHC_API size_t z_shm_mut_len(const z_loaned_shm_mut_t *this_); +ZENOHC_API +size_t z_shm_mut_len(const z_loaned_shm_mut_t *this_); #endif /** - * @attention Unstable feature. + * @warning This API has been marked as unstable: it works as advertised, but it may be changed in a future release. * @brief Borrows ZShmMut slice. */ #if (defined(SHARED_MEMORY) && defined(UNSTABLE)) -ZENOHC_API const z_loaned_shm_mut_t *z_shm_mut_loan(const z_owned_shm_mut_t *this_); +ZENOHC_API +const z_loaned_shm_mut_t *z_shm_mut_loan(const z_owned_shm_mut_t *this_); #endif /** - * @attention Unstable feature. + * @warning This API has been marked as unstable: it works as advertised, but it may be changed in a future release. * @brief Mutably borrows ZShmMut slice. */ #if (defined(SHARED_MEMORY) && defined(UNSTABLE)) -ZENOHC_API z_loaned_shm_mut_t *z_shm_mut_loan_mut(z_owned_shm_mut_t *this_); +ZENOHC_API +z_loaned_shm_mut_t *z_shm_mut_loan_mut(z_owned_shm_mut_t *this_); #endif /** - * @attention Unstable feature. + * @warning This API has been marked as unstable: it works as advertised, but it may be changed in a future release. * @brief Tries to construct ZShmMut slice from ZShm slice. */ #if (defined(SHARED_MEMORY) && defined(UNSTABLE)) -ZENOHC_API void z_shm_mut_try_from_immut(z_owned_shm_mut_t *this_, z_moved_shm_t *that); +ZENOHC_API +void z_shm_mut_try_from_immut(z_owned_shm_mut_t *this_, + z_moved_shm_t *that); #endif /** - * @attention Unstable feature. + * @warning This API has been marked as unstable: it works as advertised, but it may be changed in a future release. */ #if (defined(SHARED_MEMORY) && defined(UNSTABLE)) ZENOHC_API @@ -4092,7 +4145,7 @@ void z_shm_provider_alloc(struct z_buf_layout_alloc_result_t *out_result, struct z_alloc_alignment_t alignment); #endif /** - * @attention Unstable feature. + * @warning This API has been marked as unstable: it works as advertised, but it may be changed in a future release. */ #if (defined(SHARED_MEMORY) && defined(UNSTABLE)) ZENOHC_API @@ -4102,7 +4155,7 @@ void z_shm_provider_alloc_gc(struct z_buf_layout_alloc_result_t *out_result, struct z_alloc_alignment_t alignment); #endif /** - * @attention Unstable feature. + * @warning This API has been marked as unstable: it works as advertised, but it may be changed in a future release. */ #if (defined(SHARED_MEMORY) && defined(UNSTABLE)) ZENOHC_API @@ -4112,7 +4165,7 @@ void z_shm_provider_alloc_gc_defrag(struct z_buf_layout_alloc_result_t *out_resu struct z_alloc_alignment_t alignment); #endif /** - * @attention Unstable feature. + * @warning This API has been marked as unstable: it works as advertised, but it may be changed in a future release. */ #if (defined(SHARED_MEMORY) && defined(UNSTABLE)) ZENOHC_API @@ -4125,7 +4178,7 @@ z_result_t z_shm_provider_alloc_gc_defrag_async(struct z_buf_layout_alloc_result struct z_buf_layout_alloc_result_t*)); #endif /** - * @attention Unstable feature. + * @warning This API has been marked as unstable: it works as advertised, but it may be changed in a future release. */ #if (defined(SHARED_MEMORY) && defined(UNSTABLE)) ZENOHC_API @@ -4135,7 +4188,7 @@ void z_shm_provider_alloc_gc_defrag_blocking(struct z_buf_layout_alloc_result_t struct z_alloc_alignment_t alignment); #endif /** - * @attention Unstable feature. + * @warning This API has been marked as unstable: it works as advertised, but it may be changed in a future release. */ #if (defined(SHARED_MEMORY) && defined(UNSTABLE)) ZENOHC_API @@ -4145,39 +4198,44 @@ void z_shm_provider_alloc_gc_defrag_dealloc(struct z_buf_layout_alloc_result_t * struct z_alloc_alignment_t alignment); #endif /** - * @attention Unstable feature. + * @warning This API has been marked as unstable: it works as advertised, but it may be changed in a future release. */ #if (defined(SHARED_MEMORY) && defined(UNSTABLE)) -ZENOHC_API size_t z_shm_provider_available(const z_loaned_shm_provider_t *provider); +ZENOHC_API +size_t z_shm_provider_available(const z_loaned_shm_provider_t *provider); #endif /** - * @attention Unstable feature. + * @warning This API has been marked as unstable: it works as advertised, but it may be changed in a future release. */ #if (defined(SHARED_MEMORY) && defined(UNSTABLE)) -ZENOHC_API size_t z_shm_provider_defragment(const z_loaned_shm_provider_t *provider); +ZENOHC_API +size_t z_shm_provider_defragment(const z_loaned_shm_provider_t *provider); #endif /** - * @attention Unstable feature. + * @warning This API has been marked as unstable: it works as advertised, but it may be changed in a future release. * @brief Deletes SHM Provider. */ #if (defined(SHARED_MEMORY) && defined(UNSTABLE)) -ZENOHC_API void z_shm_provider_drop(z_moved_shm_provider_t *this_); +ZENOHC_API +void z_shm_provider_drop(z_moved_shm_provider_t *this_); #endif /** - * @attention Unstable feature. + * @warning This API has been marked as unstable: it works as advertised, but it may be changed in a future release. */ #if (defined(SHARED_MEMORY) && defined(UNSTABLE)) -ZENOHC_API size_t z_shm_provider_garbage_collect(const z_loaned_shm_provider_t *provider); +ZENOHC_API +size_t z_shm_provider_garbage_collect(const z_loaned_shm_provider_t *provider); #endif /** - * @attention Unstable feature. + * @warning This API has been marked as unstable: it works as advertised, but it may be changed in a future release. * @brief Borrows SHM Provider. */ #if (defined(SHARED_MEMORY) && defined(UNSTABLE)) -ZENOHC_API const z_loaned_shm_provider_t *z_shm_provider_loan(const z_owned_shm_provider_t *this_); +ZENOHC_API +const z_loaned_shm_provider_t *z_shm_provider_loan(const z_owned_shm_provider_t *this_); #endif /** - * @attention Unstable feature. + * @warning This API has been marked as unstable: it works as advertised, but it may be changed in a future release. */ #if (defined(SHARED_MEMORY) && defined(UNSTABLE)) ZENOHC_API @@ -4187,7 +4245,7 @@ z_result_t z_shm_provider_map(z_owned_shm_mut_t *out_result, size_t len); #endif /** - * @attention Unstable feature. + * @warning This API has been marked as unstable: it works as advertised, but it may be changed in a future release. * @brief Creates a new SHM Provider. */ #if (defined(SHARED_MEMORY) && defined(UNSTABLE)) @@ -4198,7 +4256,7 @@ void z_shm_provider_new(z_owned_shm_provider_t *this_, struct zc_shm_provider_backend_callbacks_t callbacks); #endif /** - * @attention Unstable feature. + * @warning This API has been marked as unstable: it works as advertised, but it may be changed in a future release. * @brief Creates a new threadsafe SHM Provider. */ #if (defined(SHARED_MEMORY) && defined(UNSTABLE)) @@ -4209,18 +4267,20 @@ void z_shm_provider_threadsafe_new(z_owned_shm_provider_t *this_, struct zc_shm_provider_backend_callbacks_t callbacks); #endif /** - * @attention Unstable feature. + * @warning This API has been marked as unstable: it works as advertised, but it may be changed in a future release. * @brief Mutably borrows ZShm slice as borrowed ZShmMut slice. */ #if (defined(SHARED_MEMORY) && defined(UNSTABLE)) -ZENOHC_API z_loaned_shm_mut_t *z_shm_try_mut(z_owned_shm_t *this_); +ZENOHC_API +z_loaned_shm_mut_t *z_shm_try_mut(z_owned_shm_t *this_); #endif /** - * @attention Unstable feature. + * @warning This API has been marked as unstable: it works as advertised, but it may be changed in a future release. * @brief Tries to reborrow mutably-borrowed ZShm slice as borrowed ZShmMut slice. */ #if (defined(SHARED_MEMORY) && defined(UNSTABLE)) -ZENOHC_API z_loaned_shm_mut_t *z_shm_try_reloan_mut(z_loaned_shm_t *this_); +ZENOHC_API +z_loaned_shm_mut_t *z_shm_try_reloan_mut(z_loaned_shm_t *this_); #endif /** * Puts current thread to sleep for specified amount of milliseconds. @@ -4288,28 +4348,31 @@ ZENOHC_API size_t z_slice_len(const struct z_loaned_slice_t *this_); */ ZENOHC_API const struct z_loaned_slice_t *z_slice_loan(const struct z_owned_slice_t *this_); /** - * @attention Unstable feature. + * @warning This API has been marked as unstable: it works as advertised, but it may be changed in a future release. * @brief Frees the memory and invalidates the source info, resetting it to a gravestone state. */ #if defined(UNSTABLE) -ZENOHC_API void z_source_info_drop(z_moved_source_info_t *this_); +ZENOHC_API +void z_source_info_drop(z_moved_source_info_t *this_); #endif /** - * @attention Unstable feature. + * @warning This API has been marked as unstable: it works as advertised, but it may be changed in a future release. * @brief Returns the source_id of the source info. */ #if defined(UNSTABLE) -ZENOHC_API z_entity_global_id_t z_source_info_id(const z_loaned_source_info_t *this_); +ZENOHC_API +z_entity_global_id_t z_source_info_id(const z_loaned_source_info_t *this_); #endif /** - * @attention Unstable feature. + * @warning This API has been marked as unstable: it works as advertised, but it may be changed in a future release. * @brief Borrows source info. */ #if defined(UNSTABLE) -ZENOHC_API const z_loaned_source_info_t *z_source_info_loan(const z_owned_source_info_t *this_); +ZENOHC_API +const z_loaned_source_info_t *z_source_info_loan(const z_owned_source_info_t *this_); #endif /** - * @attention Unstable feature. + * @warning This API has been marked as unstable: it works as advertised, but it may be changed in a future release. * @brief Creates source info. */ #if defined(UNSTABLE) @@ -4319,11 +4382,12 @@ z_result_t z_source_info_new(z_owned_source_info_t *this_, uint64_t source_sn); #endif /** - * @attention Unstable feature. + * @warning This API has been marked as unstable: it works as advertised, but it may be changed in a future release. * @brief Returns the source_sn of the source info. */ #if defined(UNSTABLE) -ZENOHC_API uint64_t z_source_info_sn(const z_loaned_source_info_t *this_); +ZENOHC_API +uint64_t z_source_info_sn(const z_loaned_source_info_t *this_); #endif /** * Destroys the string array, resetting it to its gravestone value. @@ -4504,11 +4568,12 @@ ZENOHC_API const char *z_time_now_as_str(const char *buf, size_t len); /** - * @attention Unstable feature. + * @warning This API has been marked as unstable: it works as advertised, but it may be changed in a future release. * @brief Returns id associated with this timestamp. */ #if defined(UNSTABLE) -ZENOHC_API z_id_t z_timestamp_id(const struct z_timestamp_t *this_); +ZENOHC_API +z_id_t z_timestamp_id(const struct z_timestamp_t *this_); #endif /** * Create uhlc timestamp from session id. @@ -4713,7 +4778,7 @@ ZENOHC_API void zc_closure_log_drop(struct zc_moved_closure_log_t *closure_); ZENOHC_API const struct zc_loaned_closure_log_t *zc_closure_log_loan(const struct zc_owned_closure_log_t *closure); /** - * @attention Unstable feature. + * @warning This API has been marked as unstable: it works as advertised, but it may be changed in a future release. * @brief Calls the closure. Calling an uninitialized closure is a no-op. */ #if defined(UNSTABLE) @@ -4722,7 +4787,7 @@ void zc_closure_matching_status_call(const struct zc_loaned_closure_matching_sta const struct zc_matching_status_t *mathing_status); #endif /** - * @attention Unstable feature. + * @warning This API has been marked as unstable: it works as advertised, but it may be changed in a future release. * @brief Drops the closure, resetting it to its gravestone state. Droping an uninitialized closure is a no-op. */ #if defined(UNSTABLE) @@ -4730,7 +4795,7 @@ ZENOHC_API void zc_closure_matching_status_drop(struct zc_moved_closure_matching_status_t *closure_); #endif /** - * @attention Unstable feature. + * @warning This API has been marked as unstable: it works as advertised, but it may be changed in a future release. * @brief Borrows closure. */ #if defined(UNSTABLE) @@ -4828,7 +4893,7 @@ ZENOHC_API bool zc_internal_closure_log_check(const struct zc_owned_closure_log_ */ ZENOHC_API void zc_internal_closure_log_null(struct zc_owned_closure_log_t *this_); /** - * @attention Unstable feature. + * @warning This API has been marked as unstable: it works as advertised, but it may be changed in a future release. * @brief Returns ``true`` if closure is valid, ``false`` if it is in gravestone state. */ #if defined(UNSTABLE) @@ -4836,7 +4901,7 @@ ZENOHC_API bool zc_internal_closure_matching_status_check(const struct zc_owned_closure_matching_status_t *this_); #endif /** - * @attention Unstable feature. + * @warning This API has been marked as unstable: it works as advertised, but it may be changed in a future release. * @brief Constructs a null value of 'zc_owned_closure_matching_status_t' type */ #if defined(UNSTABLE) @@ -4844,49 +4909,55 @@ ZENOHC_API void zc_internal_closure_matching_status_null(struct zc_owned_closure_matching_status_t *this_); #endif /** - * @attention Unstable feature. + * @warning This API has been marked as unstable: it works as advertised, but it may be changed in a future release. * @brief Returns ``true`` if liveliness token is valid, ``false`` otherwise. */ #if defined(UNSTABLE) -ZENOHC_API bool zc_internal_liveliness_token_check(const zc_owned_liveliness_token_t *this_); +ZENOHC_API +bool zc_internal_liveliness_token_check(const zc_owned_liveliness_token_t *this_); #endif /** - * @attention Unstable feature. + * @warning This API has been marked as unstable: it works as advertised, but it may be changed in a future release. * @brief Constructs liveliness token in its gravestone state. */ #if defined(UNSTABLE) -ZENOHC_API void zc_internal_liveliness_token_null(zc_owned_liveliness_token_t *this_); +ZENOHC_API +void zc_internal_liveliness_token_null(zc_owned_liveliness_token_t *this_); #endif /** - * @attention Unstable feature. + * @warning This API has been marked as unstable: it works as advertised, but it may be changed in a future release. * @brief Checks the matching listener is for the gravestone state */ #if defined(UNSTABLE) -ZENOHC_API bool zc_internal_matching_listener_check(const zc_owned_matching_listener_t *this_); +ZENOHC_API +bool zc_internal_matching_listener_check(const zc_owned_matching_listener_t *this_); #endif /** - * @attention Unstable feature. + * @warning This API has been marked as unstable: it works as advertised, but it may be changed in a future release. * @brief Constructs an empty matching listener. */ #if defined(UNSTABLE) -ZENOHC_API void zc_internal_matching_listener_null(zc_owned_matching_listener_t *this_); +ZENOHC_API +void zc_internal_matching_listener_null(zc_owned_matching_listener_t *this_); #endif /** - * @attention Unstable feature. + * @warning This API has been marked as unstable: it works as advertised, but it may be changed in a future release. * @brief Returns ``true`` if `this` is valid. */ #if (defined(SHARED_MEMORY) && defined(UNSTABLE)) -ZENOHC_API bool zc_internal_shm_client_list_check(const zc_owned_shm_client_list_t *this_); +ZENOHC_API +bool zc_internal_shm_client_list_check(const zc_owned_shm_client_list_t *this_); #endif /** - * @attention Unstable feature. + * @warning This API has been marked as unstable: it works as advertised, but it may be changed in a future release. * @brief Constructs SHM client list in its gravestone value. */ #if (defined(SHARED_MEMORY) && defined(UNSTABLE)) -ZENOHC_API void zc_internal_shm_client_list_null(zc_owned_shm_client_list_t *this_); +ZENOHC_API +void zc_internal_shm_client_list_null(zc_owned_shm_client_list_t *this_); #endif /** - * @attention Unstable feature. + * @warning This API has been marked as unstable: it works as advertised, but it may be changed in a future release. * @brief Constructs default value for `zc_liveliness_declaration_options_t`. */ #if defined(UNSTABLE) @@ -4894,7 +4965,7 @@ ZENOHC_API void zc_liveliness_declaration_options_default(struct zc_liveliness_declaration_options_t *this_); #endif /** - * @attention Unstable feature. + * @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 this_: An uninitialized memory location where subscriber will be constructed. @@ -4914,7 +4985,7 @@ z_result_t zc_liveliness_declare_subscriber(struct z_owned_subscriber_t *this_, struct zc_liveliness_subscriber_options_t *_options); #endif /** - * @attention Unstable feature. + * @warning This API has been marked as unstable: it works as advertised, but it may be changed in a future release. * @brief Constructs and declares a liveliness token on the network. * * Liveliness token subscribers on an intersecting key expression will receive a PUT sample when connectivity @@ -4933,7 +5004,7 @@ z_result_t zc_liveliness_declare_token(zc_owned_liveliness_token_t *this_, const struct zc_liveliness_declaration_options_t *_options); #endif /** - * @attention Unstable feature. + * @warning This API has been marked as unstable: it works as advertised, but it may be changed in a future release. * @brief Queries liveliness tokens currently on the network with a key expression intersecting with `key_expr`. * * @param session: The Zenoh session. @@ -4949,14 +5020,15 @@ z_result_t zc_liveliness_get(const struct z_loaned_session_t *session, struct zc_liveliness_get_options_t *options); #endif /** - * @attention Unstable feature. + * @warning This API has been marked as unstable: it works as advertised, but it may be changed in a future release. * @brief Constructs default value `zc_liveliness_get_options_t`. */ #if defined(UNSTABLE) -ZENOHC_API void zc_liveliness_get_options_default(struct zc_liveliness_get_options_t *this_); +ZENOHC_API +void zc_liveliness_get_options_default(struct zc_liveliness_get_options_t *this_); #endif /** - * @attention Unstable feature. + * @warning This API has been marked as unstable: it works as advertised, but it may be changed in a future release. * @brief Constucts default value for `zc_liveliness_declare_subscriber_options_t`. */ #if defined(UNSTABLE) @@ -4964,14 +5036,15 @@ ZENOHC_API void zc_liveliness_subscriber_options_default(struct zc_liveliness_subscriber_options_t *this_); #endif /** - * @attention Unstable feature. + * @warning This API has been marked as unstable: it works as advertised, but it may be changed in a future release. * @brief Undeclares liveliness token, frees memory and resets it to a gravestone state. */ #if defined(UNSTABLE) -ZENOHC_API void zc_liveliness_token_drop(zc_moved_liveliness_token_t *this_); +ZENOHC_API +void zc_liveliness_token_drop(zc_moved_liveliness_token_t *this_); #endif /** - * @attention Unstable feature. + * @warning This API has been marked as unstable: it works as advertised, but it may be changed in a future release. * @brief Borrows token. */ #if defined(UNSTABLE) @@ -4979,21 +5052,23 @@ ZENOHC_API const zc_loaned_liveliness_token_t *zc_liveliness_token_loan(const zc_owned_liveliness_token_t *this_); #endif /** - * @attention Unstable feature. + * @warning This API has been marked as unstable: it works as advertised, but it may be changed in a future release. * @brief Destroys a liveliness token, notifying subscribers of its destruction. */ #if defined(UNSTABLE) -ZENOHC_API z_result_t zc_liveliness_undeclare_token(zc_moved_liveliness_token_t *this_); +ZENOHC_API +z_result_t zc_liveliness_undeclare_token(zc_moved_liveliness_token_t *this_); #endif /** - * @attention Unstable feature. + * @warning This API has been marked as unstable: it works as advertised, but it may be changed in a future release. * @brief Returns default value of `zc_locality_t` */ #if defined(UNSTABLE) -ZENOHC_API enum zc_locality_t zc_locality_default(void); +ZENOHC_API +enum zc_locality_t zc_locality_default(void); #endif /** - * @attention Unstable feature. + * @warning This API has been marked as unstable: it works as advertised, but it may be changed in a future release. * @brief Gets publisher matching status - i.e. if there are any subscribers matching its key expression. * * @return 0 in case of success, negative error code otherwise (in this case matching_status is not updated). @@ -5004,7 +5079,7 @@ z_result_t zc_publisher_get_matching_status(const struct z_loaned_publisher_t *t struct zc_matching_status_t *matching_status); #endif /** - * @attention Unstable feature. + * @warning This API has been marked as unstable: it works as advertised, but it may be changed in a future release. * @brief Constructs matching listener, registering a callback for notifying subscribers matching with a given publisher. * * @param this_: An unitilized memory location where matching listener will be constructed. The matching listener will be automatically dropped when publisher is dropped. @@ -5020,30 +5095,33 @@ z_result_t zc_publisher_matching_listener_declare(zc_owned_matching_listener_t * struct zc_moved_closure_matching_status_t *callback); #endif /** - * @attention Unstable feature. + * @warning This API has been marked as unstable: it works as advertised, but it may be changed in a future release. * @brief Undeclares the given matching listener, droping and invalidating it. */ #if defined(UNSTABLE) -ZENOHC_API void zc_publisher_matching_listener_drop(zc_moved_matching_listener_t *this_); +ZENOHC_API +void zc_publisher_matching_listener_drop(zc_moved_matching_listener_t *this_); #endif /** - * @attention Unstable feature. + * @warning This API has been marked as unstable: it works as advertised, but it may be changed in a future release. * @brief Undeclares the given matching listener, droping and invalidating it. * * @return 0 in case of success, negative error code otherwise. */ #if defined(UNSTABLE) -ZENOHC_API z_result_t zc_publisher_matching_listener_undeclare(zc_moved_matching_listener_t *this_); +ZENOHC_API +z_result_t zc_publisher_matching_listener_undeclare(zc_moved_matching_listener_t *this_); #endif /** - * @attention Unstable feature. + * @warning This API has been marked as unstable: it works as advertised, but it may be changed in a future release. * @brief Returns the default value of #zc_reply_keyexpr_t. */ #if defined(UNSTABLE) -ZENOHC_API enum zc_reply_keyexpr_t zc_reply_keyexpr_default(void); +ZENOHC_API +enum zc_reply_keyexpr_t zc_reply_keyexpr_default(void); #endif /** - * @attention Unstable feature. + * @warning This API has been marked as unstable: it works as advertised, but it may be changed in a future release. */ #if (defined(SHARED_MEMORY) && defined(UNSTABLE)) ZENOHC_API @@ -5052,14 +5130,15 @@ z_result_t zc_shm_client_list_add_client(z_protocol_id_t id, zc_loaned_shm_client_list_t *list); #endif /** - * @attention Unstable feature. + * @warning This API has been marked as unstable: it works as advertised, but it may be changed in a future release. * @brief Deletes list of SHM Clients. */ #if (defined(SHARED_MEMORY) && defined(UNSTABLE)) -ZENOHC_API void zc_shm_client_list_drop(zc_moved_shm_client_list_t *this_); +ZENOHC_API +void zc_shm_client_list_drop(zc_moved_shm_client_list_t *this_); #endif /** - * @attention Unstable feature. + * @warning This API has been marked as unstable: it works as advertised, but it may be changed in a future release. * @brief Borrows list of SHM Clients. */ #if (defined(SHARED_MEMORY) && defined(UNSTABLE)) @@ -5067,7 +5146,7 @@ ZENOHC_API const zc_loaned_shm_client_list_t *zc_shm_client_list_loan(const zc_owned_shm_client_list_t *this_); #endif /** - * @attention Unstable feature. + * @warning This API has been marked as unstable: it works as advertised, but it may be changed in a future release. * @brief Mutably borrows list of SHM Clients. */ #if (defined(SHARED_MEMORY) && defined(UNSTABLE)) @@ -5075,11 +5154,12 @@ ZENOHC_API zc_loaned_shm_client_list_t *zc_shm_client_list_loan_mut(zc_owned_shm_client_list_t *this_); #endif /** - * @attention Unstable feature. + * @warning This API has been marked as unstable: it works as advertised, but it may be changed in a future release. * @brief Creates a new empty list of SHM Clients. */ #if (defined(SHARED_MEMORY) && defined(UNSTABLE)) -ZENOHC_API void zc_shm_client_list_new(zc_owned_shm_client_list_t *this_); +ZENOHC_API +void zc_shm_client_list_new(zc_owned_shm_client_list_t *this_); #endif /** * Stops all Zenoh tasks and drops all related static variables. @@ -5090,7 +5170,7 @@ ZENOHC_API void zc_shm_client_list_new(zc_owned_shm_client_list_t *this_); ZENOHC_API void zc_stop_z_runtime(void); /** - * @attention Unstable feature. + * @warning This API has been marked as unstable: it works as advertised, but it may be changed in a future release. * @brief Constructs and declares a publication cache. * * @param this_: An uninitialized location in memory where publication cache will be constructed. @@ -5108,7 +5188,7 @@ z_result_t ze_declare_publication_cache(ze_owned_publication_cache_t *this_, struct ze_publication_cache_options_t *options); #endif /** - * @attention Unstable feature. + * @warning This API has been marked as unstable: it works as advertised, but it may be changed in a future release. * @brief Constructs and declares a querying subscriber for a given key expression. * * @param this_: An uninitialized memory location where querying subscriber will be constructed. @@ -5128,25 +5208,28 @@ z_result_t ze_declare_querying_subscriber(ze_owned_querying_subscriber_t *this_, struct ze_querying_subscriber_options_t *options); #endif /** - * @attention Unstable feature. + * @warning This API has been marked as unstable: it works as advertised, but it may be changed in a future release. * @brief Returns ``true`` if publication cache is valid, ``false`` otherwise. */ #if defined(UNSTABLE) -ZENOHC_API bool ze_internal_publication_cache_check(const ze_owned_publication_cache_t *this_); +ZENOHC_API +bool ze_internal_publication_cache_check(const ze_owned_publication_cache_t *this_); #endif /** - * @attention Unstable feature. + * @warning This API has been marked as unstable: it works as advertised, but it may be changed in a future release. * @brief Constructs a publication cache in a gravestone state. */ #if defined(UNSTABLE) -ZENOHC_API void ze_internal_publication_cache_null(ze_owned_publication_cache_t *this_); +ZENOHC_API +void ze_internal_publication_cache_null(ze_owned_publication_cache_t *this_); #endif /** - * @attention Unstable feature. + * @warning This API has been marked as unstable: it works as advertised, but it may be changed in a future release. * @brief Returns ``true`` if querying subscriber is valid, ``false`` otherwise. */ #if defined(UNSTABLE) -ZENOHC_API bool ze_internal_querying_subscriber_check(const ze_owned_querying_subscriber_t *this_); +ZENOHC_API +bool ze_internal_querying_subscriber_check(const ze_owned_querying_subscriber_t *this_); #endif /** * Constructs a querying subscriber in a gravestone state. @@ -5155,14 +5238,15 @@ ZENOHC_API bool ze_internal_querying_subscriber_check(const ze_owned_querying_su ZENOHC_API void ze_internal_querying_subscriber_null(ze_owned_querying_subscriber_t *this_); #endif /** - * @attention Unstable feature. + * @warning This API has been marked as unstable: it works as advertised, but it may be changed in a future release. * @brief Drops publication cache and resets it to its gravestone state. */ #if defined(UNSTABLE) -ZENOHC_API void ze_publication_cache_drop(ze_moved_publication_cache_t *this_); +ZENOHC_API +void ze_publication_cache_drop(ze_moved_publication_cache_t *this_); #endif /** - * @attention Unstable feature. + * @warning This API has been marked as unstable: it works as advertised, but it may be changed in a future release. * @brief Returns the key expression of the publication cache. */ #if defined(UNSTABLE) @@ -5170,7 +5254,7 @@ ZENOHC_API const struct z_loaned_keyexpr_t *ze_publication_cache_keyexpr(const ze_loaned_publication_cache_t *this_); #endif /** - * @attention Unstable feature. + * @warning This API has been marked as unstable: it works as advertised, but it may be changed in a future release. * @brief Borrows querying subscriber. */ #if defined(UNSTABLE) @@ -5178,21 +5262,23 @@ ZENOHC_API const ze_loaned_publication_cache_t *ze_publication_cache_loan(const ze_owned_publication_cache_t *this_); #endif /** - * @attention Unstable feature. + * @warning This API has been marked as unstable: it works as advertised, but it may be changed in a future release. * @brief Constructs the default value for `ze_publication_cache_options_t`. */ #if defined(UNSTABLE) -ZENOHC_API void ze_publication_cache_options_default(struct ze_publication_cache_options_t *this_); +ZENOHC_API +void ze_publication_cache_options_default(struct ze_publication_cache_options_t *this_); #endif /** - * @attention Unstable feature. + * @warning This API has been marked as unstable: it works as advertised, but it may be changed in a future release. * @brief Drops querying subscriber. */ #if defined(UNSTABLE) -ZENOHC_API void ze_querying_subscriber_drop(ze_moved_querying_subscriber_t *this_); +ZENOHC_API +void ze_querying_subscriber_drop(ze_moved_querying_subscriber_t *this_); #endif /** - * @attention Unstable feature. + * @warning This API has been marked as unstable: it works as advertised, but it may be changed in a future release. * @brief Make querying subscriber perform an additional query on a specified selector. * The queried samples will be merged with the received publications and made available in the subscriber callback. * @return 0 in case of success, negative error code otherwise. @@ -5204,7 +5290,7 @@ z_result_t ze_querying_subscriber_get(const ze_loaned_querying_subscriber_t *thi struct z_get_options_t *options); #endif /** - * @attention Unstable feature. + * @warning This API has been marked as unstable: it works as advertised, but it may be changed in a future release. * @brief Borrows querying subscriber. */ #if defined(UNSTABLE) @@ -5212,7 +5298,7 @@ ZENOHC_API const ze_loaned_querying_subscriber_t *ze_querying_subscriber_loan(const ze_owned_querying_subscriber_t *this_); #endif /** - * @attention Unstable feature. + * @warning This API has been marked as unstable: it works as advertised, but it may be changed in a future release. * @brief Constructs the default value for `ze_querying_subscriber_options_t`. */ #if defined(UNSTABLE) @@ -5220,19 +5306,21 @@ ZENOHC_API void ze_querying_subscriber_options_default(struct ze_querying_subscriber_options_t *this_); #endif /** - * @attention Unstable feature. + * @warning This API has been marked as unstable: it works as advertised, but it may be changed in a future release. * @brief Undeclares and drops publication cache. * @return 0 in case of success, negative error code otherwise. */ #if defined(UNSTABLE) -ZENOHC_API z_result_t ze_undeclare_publication_cache(ze_moved_publication_cache_t *this_); +ZENOHC_API +z_result_t ze_undeclare_publication_cache(ze_moved_publication_cache_t *this_); #endif /** - * @attention Unstable feature. + * @warning This API has been marked as unstable: it works as advertised, but it may be changed in a future release. * @brief Undeclares the given querying subscriber, drops it and resets to a gravestone state. * * @return 0 in case of success, negative error code otherwise. */ #if defined(UNSTABLE) -ZENOHC_API z_result_t ze_undeclare_querying_subscriber(ze_moved_querying_subscriber_t *this_); +ZENOHC_API +z_result_t ze_undeclare_querying_subscriber(ze_moved_querying_subscriber_t *this_); #endif diff --git a/src/closures/matching_status_closure.rs b/src/closures/matching_status_closure.rs index 110b827dc..c21fc7959 100644 --- a/src/closures/matching_status_closure.rs +++ b/src/closures/matching_status_closure.rs @@ -19,7 +19,7 @@ use crate::{ transmute::{LoanedCTypeRef, OwnedCTypeRef, TakeRustType}, zc_matching_status_t, }; -/// @attention Unstable feature. +/// @warning This API has been marked as unstable: it works as advertised, but it may be changed in a future release. /// @brief A closure is a structure that contains all the elements for stateful, memory-leak-free callbacks: /// /// Closures are not guaranteed not to be called concurrently. @@ -38,14 +38,14 @@ pub struct zc_owned_closure_matching_status_t { drop: Option, } -/// @attention Unstable feature. +/// @warning This API has been marked as unstable: it works as advertised, but it may be changed in a future release. /// @brief Loaned closure. #[repr(C)] pub struct zc_loaned_closure_matching_status_t { _0: [usize; 3], } -/// @attention Unstable feature. +/// @warning This API has been marked as unstable: it works as advertised, but it may be changed in a future release. /// @brief Moved closure. #[repr(C)] pub struct zc_moved_closure_matching_status_t { @@ -82,7 +82,7 @@ impl Drop for zc_owned_closure_matching_status_t { } } } -/// @attention Unstable feature. +/// @warning This API has been marked as unstable: it works as advertised, but it may be changed in a future release. /// @brief Constructs a null value of 'zc_owned_closure_matching_status_t' type #[no_mangle] #[allow(clippy::missing_safety_doc)] @@ -92,7 +92,7 @@ pub unsafe extern "C" fn zc_internal_closure_matching_status_null( (*this).write(zc_owned_closure_matching_status_t::default()); } -/// @attention Unstable feature. +/// @warning This API has been marked as unstable: it works as advertised, but it may be changed in a future release. /// @brief Returns ``true`` if closure is valid, ``false`` if it is in gravestone state. #[no_mangle] pub extern "C" fn zc_internal_closure_matching_status_check( @@ -101,7 +101,7 @@ pub extern "C" fn zc_internal_closure_matching_status_check( !this.is_empty() } -/// @attention Unstable feature. +/// @warning This API has been marked as unstable: it works as advertised, but it may be changed in a future release. /// @brief Calls the closure. Calling an uninitialized closure is a no-op. #[no_mangle] pub extern "C" fn zc_closure_matching_status_call( @@ -117,7 +117,7 @@ pub extern "C" fn zc_closure_matching_status_call( } } -/// @attention Unstable feature. +/// @warning This API has been marked as unstable: it works as advertised, but it may be changed in a future release. /// @brief Drops the closure, resetting it to its gravestone state. Droping an uninitialized closure is a no-op. #[no_mangle] pub extern "C" fn zc_closure_matching_status_drop( @@ -147,7 +147,7 @@ impl From for zc_owned_closure_matching_status_ } } -/// @attention Unstable feature. +/// @warning This API has been marked as unstable: it works as advertised, but it may be changed in a future release. /// @brief Borrows closure. #[no_mangle] pub extern "C" fn zc_closure_matching_status_loan( diff --git a/src/closures/zenohid_closure.rs b/src/closures/zenohid_closure.rs index 04e3a3cc2..062a912fe 100644 --- a/src/closures/zenohid_closure.rs +++ b/src/closures/zenohid_closure.rs @@ -20,7 +20,7 @@ use crate::{ transmute::{LoanedCTypeRef, OwnedCTypeRef, TakeRustType}, z_id_t, }; -/// @attention Unstable feature. +/// @warning This API has been marked as unstable: it works as advertised, but it may be changed in a future release. /// @brief A closure is a structure that contains all the elements for stateful, memory-leak-free callbacks: /// /// Closures are not guaranteed not to be called concurrently. @@ -39,14 +39,14 @@ pub struct z_owned_closure_zid_t { drop: Option, } -/// @attention Unstable feature. +/// @warning This API has been marked as unstable: it works as advertised, but it may be changed in a future release. /// @brief Loaned closure. #[repr(C)] pub struct z_loaned_closure_zid_t { _0: [usize; 3], } -/// @attention Unstable feature. +/// @warning This API has been marked as unstable: it works as advertised, but it may be changed in a future release. /// @brief Moved closure. #[repr(C)] pub struct z_moved_closure_zid_t { @@ -84,7 +84,7 @@ impl Drop for z_owned_closure_zid_t { } } -/// @attention Unstable feature. +/// @warning This API has been marked as unstable: it works as advertised, but it may be changed in a future release. /// @brief Returns ``true`` if closure is valid, ``false`` if it is in gravestone state. #[no_mangle] #[allow(clippy::missing_safety_doc)] @@ -92,7 +92,7 @@ pub unsafe extern "C" fn z_internal_closure_zid_check(this_: &z_owned_closure_zi !this_.is_empty() } -/// @attention Unstable feature. +/// @warning This API has been marked as unstable: it works as advertised, but it may be changed in a future release. /// @brief Constructs a null closure. #[no_mangle] #[allow(clippy::missing_safety_doc)] @@ -102,7 +102,7 @@ pub unsafe extern "C" fn z_internal_closure_zid_null( this_.write(z_owned_closure_zid_t::default()); } -/// @attention Unstable feature. +/// @warning This API has been marked as unstable: it works as advertised, but it may be changed in a future release. /// @brief Calls the closure. Calling an uninitialized closure is a no-op. #[no_mangle] pub extern "C" fn z_closure_zid_call(closure: &z_loaned_closure_zid_t, z_id: &z_id_t) { @@ -115,7 +115,7 @@ pub extern "C" fn z_closure_zid_call(closure: &z_loaned_closure_zid_t, z_id: &z_ } } -/// @attention Unstable feature. +/// @warning This API has been marked as unstable: it works as advertised, but it may be changed in a future release. /// @brief Drops the closure, resetting it to its gravestone state. Droping an uninitialized (null) closure is a no-op. #[no_mangle] pub extern "C" fn z_closure_zid_drop(closure_: &mut z_moved_closure_zid_t) { @@ -140,7 +140,7 @@ impl From for z_owned_closure_zid_t { } } -/// @attention Unstable feature. +/// @warning This API has been marked as unstable: it works as advertised, but it may be changed in a future release. /// @brief Borrows closure. #[no_mangle] pub extern "C" fn z_closure_zid_loan(closure: &z_owned_closure_zid_t) -> &z_loaned_closure_zid_t { diff --git a/src/commons.rs b/src/commons.rs index 5d855dd82..b63b649d9 100644 --- a/src/commons.rs +++ b/src/commons.rs @@ -93,7 +93,7 @@ pub extern "C" fn z_timestamp_ntp64_time(this_: &z_timestamp_t) -> u64 { } #[cfg(feature = "unstable")] -/// @attention Unstable feature. +/// @warning This API has been marked as unstable: it works as advertised, but it may be changed in a future release. /// @brief Returns id associated with this timestamp. #[no_mangle] pub extern "C" fn z_timestamp_id(this_: &z_timestamp_t) -> z_id_t { @@ -151,7 +151,7 @@ pub extern "C" fn z_sample_attachment(this_: &z_loaned_sample_t) -> *const z_loa } } #[cfg(feature = "unstable")] -/// @attention Unstable feature. +/// @warning This API has been marked as unstable: it works as advertised, but it may be changed in a future release. /// @brief Returns the sample source_info. #[no_mangle] pub extern "C" fn z_sample_source_info(this_: &z_loaned_sample_t) -> &z_loaned_source_info_t { @@ -190,8 +190,8 @@ pub extern "C" fn z_sample_congestion_control(this_: &z_loaned_sample_t) -> z_co } #[cfg(feature = "unstable")] -/// @attention Unstable feature. -/// @brief Returns the reliability setting the sample was delieverd with. +/// @warning This API has been marked as unstable: it works as advertised, but it may be changed in a future release. +/// @brief Returns the reliability setting the sample was delivered with. #[no_mangle] pub extern "C" fn z_sample_reliability(this_: &z_loaned_sample_t) -> z_reliability_t { this_.as_rust_type_ref().reliability().into() @@ -261,14 +261,14 @@ impl From for Locality { } #[cfg(feature = "unstable")] -/// @attention Unstable feature. +/// @warning This API has been marked as unstable: it works as advertised, but it may be changed in a future release. /// @brief Returns default value of `zc_locality_t` #[no_mangle] pub extern "C" fn zc_locality_default() -> zc_locality_t { Locality::default().into() } -/// @attention Unstable feature. +/// @warning This API has been marked as unstable: it works as advertised, but it may be changed in a future release. /// @brief The publisher reliability. /// @note Currently `reliability` does not trigger any data retransmission on the wire. /// It is rather used as a marker on the wire and it may be used to select the best link available (e.g. TCP for reliable data and UDP for best effort data). @@ -295,7 +295,7 @@ impl From for z_reliability_t { } #[cfg(feature = "unstable")] -/// @attention Unstable feature. +/// @warning This API has been marked as unstable: it works as advertised, but it may be changed in a future release. /// @brief Returns the default value for `reliability`. #[no_mangle] pub extern "C" fn z_reliability_default() -> z_reliability_t { @@ -314,7 +314,7 @@ impl From for Reliability { } #[cfg(feature = "unstable")] -/// @attention Unstable feature. +/// @warning This API has been marked as unstable: it works as advertised, but it may be changed in a future release. /// @brief Key expressions types to which Queryable should reply to. #[repr(C)] #[derive(Clone, Copy, Debug)] @@ -346,7 +346,7 @@ impl From for ReplyKeyExpr { } #[cfg(feature = "unstable")] -/// @attention Unstable feature. +/// @warning This API has been marked as unstable: it works as advertised, but it may be changed in a future release. /// @brief Returns the default value of #zc_reply_keyexpr_t. #[no_mangle] pub extern "C" fn zc_reply_keyexpr_default() -> zc_reply_keyexpr_t { @@ -528,14 +528,14 @@ use crate::z_entity_global_id_t; decl_c_type!(copy(z_entity_global_id_t, EntityGlobalId)); #[cfg(feature = "unstable")] -/// @attention Unstable feature. +/// @warning This API has been marked as unstable: it works as advertised, but it may be changed in a future release. /// @brief Returns the zenoh id of entity global id. #[no_mangle] pub extern "C" fn z_entity_global_id_zid(this_: &z_entity_global_id_t) -> z_id_t { this_.as_rust_type_ref().zid().into_c_type() } #[cfg(feature = "unstable")] -/// @attention Unstable feature. +/// @warning This API has been marked as unstable: it works as advertised, but it may be changed in a future release. /// @brief Returns the entity id of the entity global id. #[no_mangle] pub extern "C" fn z_entity_global_id_eid(this_: &z_entity_global_id_t) -> u32 { @@ -550,7 +550,7 @@ decl_c_type!( ); #[cfg(feature = "unstable")] -/// @attention Unstable feature. +/// @warning This API has been marked as unstable: it works as advertised, but it may be changed in a future release. /// @brief Creates source info. #[no_mangle] pub extern "C" fn z_source_info_new( @@ -568,7 +568,7 @@ pub extern "C" fn z_source_info_new( } #[cfg(feature = "unstable")] -/// @attention Unstable feature. +/// @warning This API has been marked as unstable: it works as advertised, but it may be changed in a future release. /// @brief Returns the source_id of the source info. #[no_mangle] pub extern "C" fn z_source_info_id(this_: &z_loaned_source_info_t) -> z_entity_global_id_t { @@ -580,7 +580,7 @@ pub extern "C" fn z_source_info_id(this_: &z_loaned_source_info_t) -> z_entity_g } #[cfg(feature = "unstable")] -/// @attention Unstable feature. +/// @warning This API has been marked as unstable: it works as advertised, but it may be changed in a future release. /// @brief Returns the source_sn of the source info. #[no_mangle] pub extern "C" fn z_source_info_sn(this_: &z_loaned_source_info_t) -> u64 { @@ -588,7 +588,7 @@ pub extern "C" fn z_source_info_sn(this_: &z_loaned_source_info_t) -> u64 { } #[cfg(feature = "unstable")] -/// @attention Unstable feature. +/// @warning This API has been marked as unstable: it works as advertised, but it may be changed in a future release. /// @brief Returns ``true`` if source info is valid, ``false`` if it is in gravestone state. #[no_mangle] pub extern "C" fn z_internal_source_info_check(this_: &z_owned_source_info_t) -> bool { @@ -596,7 +596,7 @@ pub extern "C" fn z_internal_source_info_check(this_: &z_owned_source_info_t) -> } #[cfg(feature = "unstable")] -/// @attention Unstable feature. +/// @warning This API has been marked as unstable: it works as advertised, but it may be changed in a future release. /// @brief Borrows source info. #[no_mangle] pub extern "C" fn z_source_info_loan(this_: &z_owned_source_info_t) -> &z_loaned_source_info_t { @@ -604,7 +604,7 @@ pub extern "C" fn z_source_info_loan(this_: &z_owned_source_info_t) -> &z_loaned } #[cfg(feature = "unstable")] -/// @attention Unstable feature. +/// @warning This API has been marked as unstable: it works as advertised, but it may be changed in a future release. /// @brief Frees the memory and invalidates the source info, resetting it to a gravestone state. #[no_mangle] pub extern "C" fn z_source_info_drop(this_: &mut z_moved_source_info_t) { @@ -612,7 +612,7 @@ pub extern "C" fn z_source_info_drop(this_: &mut z_moved_source_info_t) { } #[cfg(feature = "unstable")] -/// @attention Unstable feature. +/// @warning This API has been marked as unstable: it works as advertised, but it may be changed in a future release. /// @brief Constructs source info in its gravestone state. #[no_mangle] pub extern "C" fn z_internal_source_info_null(this_: &mut MaybeUninit) { diff --git a/src/get.rs b/src/get.rs index ce0037c81..bd9c978e0 100644 --- a/src/get.rs +++ b/src/get.rs @@ -151,7 +151,7 @@ pub unsafe extern "C" fn z_reply_err(this_: &z_loaned_reply_t) -> *const z_loane } #[cfg(feature = "unstable")] -/// @attention Unstable feature. +/// @warning This API has been marked as unstable: it works as advertised, but it may be changed in a future release. /// @brief Gets the id of the zenoh instance that answered this Reply. /// @return `true` if id is present. #[no_mangle] @@ -197,19 +197,19 @@ pub struct z_get_options_t { /// If true, Zenoh will not wait to batch this message with others to reduce the bandwith. pub is_express: bool, #[cfg(feature = "unstable")] - /// @attention Unstable feature. + /// @warning This API has been marked as unstable: it works as advertised, but it may be changed in a future release. /// /// The allowed destination for the query. pub allowed_destination: zc_locality_t, #[cfg(feature = "unstable")] - /// @attention Unstable feature. + /// @warning This API has been marked as unstable: it works as advertised, but it may be changed in a future release. /// /// The accepted replies for the query. pub accept_replies: zc_reply_keyexpr_t, /// The priority of the query. pub priority: z_priority_t, #[cfg(feature = "unstable")] - /// @attention Unstable feature. + /// @warning This API has been marked as unstable: it works as advertised, but it may be changed in a future release. /// /// The source info for the query. pub source_info: Option<&'static mut z_moved_source_info_t>, diff --git a/src/info.rs b/src/info.rs index 0636d12c4..86ae8b478 100644 --- a/src/info.rs +++ b/src/info.rs @@ -30,7 +30,7 @@ impl From<[u8; 16]> for z_id_t { } } -/// @attention Unstable feature. +/// @warning This API has been marked as unstable: it works as advertised, but it may be changed in a future release. /// @brief Formats the `z_id_t` into 16-digit hex string (LSB-first order) #[no_mangle] pub extern "C" fn z_id_to_string(zid: &z_id_t, dst: &mut MaybeUninit) { @@ -38,7 +38,7 @@ pub extern "C" fn z_id_to_string(zid: &z_id_t, dst: &mut MaybeUninit z_id_t { session.info().zid().wait().into_c_type() } -/// @attention Unstable feature. +/// @warning This API has been marked as unstable: it works as advertised, but it may be changed in a future release. /// @brief Fetches the Zenoh IDs of all connected peers. /// /// `callback` will be called once for each ID, is guaranteed to never be called concurrently, @@ -72,7 +72,7 @@ pub unsafe extern "C" fn z_info_peers_zid( result::Z_OK } -/// @attention Unstable feature. +/// @warning This API has been marked as unstable: it works as advertised, but it may be changed in a future release. /// @brief Fetches the Zenoh IDs of all connected routers. /// /// `callback` will be called once for each ID, is guaranteed to never be called concurrently, diff --git a/src/keyexpr.rs b/src/keyexpr.rs index 8e372a940..fb747909c 100644 --- a/src/keyexpr.rs +++ b/src/keyexpr.rs @@ -607,7 +607,7 @@ pub extern "C" fn z_keyexpr_join( } } #[cfg(feature = "unstable")] -/// @attention Unstable feature. +/// @warning This API has been marked as unstable: it works as advertised, but it may be changed in a future release. /// @brief Intersection level of 2 key expressions. #[derive(Clone, Copy, Debug, PartialEq, Eq)] #[repr(C)] @@ -634,7 +634,7 @@ impl From for z_keyexpr_intersection_level_t { } #[cfg(feature = "unstable")] #[no_mangle] -/// @attention Unstable feature. +/// @warning This API has been marked as unstable: it works as advertised, but it may be changed in a future release. /// @brief Returns the relation between `left` and `right` from `left`'s point of view. /// /// @note This is slower than `z_keyexpr_intersects` and `keyexpr_includes`, so you should favor these methods for most applications. diff --git a/src/liveliness.rs b/src/liveliness.rs index 8e8d12b1c..7559d63bb 100644 --- a/src/liveliness.rs +++ b/src/liveliness.rs @@ -32,7 +32,7 @@ decl_c_type!( loaned(zc_loaned_liveliness_token_t), ); -/// @attention Unstable feature. +/// @warning This API has been marked as unstable: it works as advertised, but it may be changed in a future release. /// @brief Constructs liveliness token in its gravestone state. #[no_mangle] pub extern "C" fn zc_internal_liveliness_token_null( @@ -41,28 +41,28 @@ pub extern "C" fn zc_internal_liveliness_token_null( this_.as_rust_type_mut_uninit().write(None); } -/// @attention Unstable feature. +/// @warning This API has been marked as unstable: it works as advertised, but it may be changed in a future release. /// @brief Returns ``true`` if liveliness token is valid, ``false`` otherwise. #[no_mangle] pub extern "C" fn zc_internal_liveliness_token_check(this_: &zc_owned_liveliness_token_t) -> bool { this_.as_rust_type_ref().is_some() } -/// @attention Unstable feature. +/// @warning This API has been marked as unstable: it works as advertised, but it may be changed in a future release. /// @brief Undeclares liveliness token, frees memory and resets it to a gravestone state. #[no_mangle] pub extern "C" fn zc_liveliness_token_drop(this_: &mut zc_moved_liveliness_token_t) { let _ = this_.take_rust_type(); } -/// @attention Unstable feature. +/// @warning This API has been marked as unstable: it works as advertised, but it may be changed in a future release. /// @brief The options for `zc_liveliness_declare_token()`. #[repr(C)] pub struct zc_liveliness_declaration_options_t { _dummy: u8, } -/// @attention Unstable feature. +/// @warning This API has been marked as unstable: it works as advertised, but it may be changed in a future release. /// @brief Constructs default value for `zc_liveliness_declaration_options_t`. #[no_mangle] pub extern "C" fn zc_liveliness_declaration_options_default( @@ -71,7 +71,7 @@ pub extern "C" fn zc_liveliness_declaration_options_default( this.write(zc_liveliness_declaration_options_t { _dummy: 0 }); } -/// @attention Unstable feature. +/// @warning This API has been marked as unstable: it works as advertised, but it may be changed in a future release. /// @brief Borrows token. #[no_mangle] #[allow(clippy::missing_safety_doc)] @@ -84,7 +84,7 @@ pub unsafe extern "C" fn zc_liveliness_token_loan( .as_loaned_c_type_ref() } -/// @attention Unstable feature. +/// @warning This API has been marked as unstable: it works as advertised, but it may be changed in a future release. /// @brief Constructs and declares a liveliness token on the network. /// /// Liveliness token subscribers on an intersecting key expression will receive a PUT sample when connectivity @@ -117,7 +117,7 @@ pub extern "C" fn zc_liveliness_declare_token( } } -/// @attention Unstable feature. +/// @warning This API has been marked as unstable: it works as advertised, but it may be changed in a future release. /// @brief Destroys a liveliness token, notifying subscribers of its destruction. #[no_mangle] pub extern "C" fn zc_liveliness_undeclare_token( @@ -132,14 +132,14 @@ pub extern "C" fn zc_liveliness_undeclare_token( result::Z_OK } -/// @attention Unstable feature. +/// @warning This API has been marked as unstable: it works as advertised, but it may be changed in a future release. /// @brief The options for `zc_liveliness_declare_subscriber()` #[repr(C)] pub struct zc_liveliness_subscriber_options_t { _dummy: u8, } -/// @attention Unstable feature. +/// @warning This API has been marked as unstable: it works as advertised, but it may be changed in a future release. /// @brief Constucts default value for `zc_liveliness_declare_subscriber_options_t`. #[no_mangle] pub extern "C" fn zc_liveliness_subscriber_options_default( @@ -148,7 +148,7 @@ pub extern "C" fn zc_liveliness_subscriber_options_default( this.write(zc_liveliness_subscriber_options_t { _dummy: 0 }); } -/// @attention Unstable feature. +/// @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 this_: An uninitialized memory location where subscriber will be constructed. @@ -191,14 +191,14 @@ pub extern "C" fn zc_liveliness_declare_subscriber( } } -/// @attention Unstable feature. +/// @warning This API has been marked as unstable: it works as advertised, but it may be changed in a future release. /// @brief The options for `zc_liveliness_get()` #[repr(C)] pub struct zc_liveliness_get_options_t { timeout_ms: u32, } -/// @attention Unstable feature. +/// @warning This API has been marked as unstable: it works as advertised, but it may be changed in a future release. /// @brief Constructs default value `zc_liveliness_get_options_t`. #[no_mangle] pub extern "C" fn zc_liveliness_get_options_default( @@ -207,7 +207,7 @@ pub extern "C" fn zc_liveliness_get_options_default( this.write(zc_liveliness_get_options_t { timeout_ms: 10000 }); } -/// @attention Unstable feature. +/// @warning This API has been marked as unstable: it works as advertised, but it may be changed in a future release. /// @brief Queries liveliness tokens currently on the network with a key expression intersecting with `key_expr`. /// /// @param session: The Zenoh session. diff --git a/src/payload.rs b/src/payload.rs index a1bf5e867..bbd4b254a 100644 --- a/src/payload.rs +++ b/src/payload.rs @@ -152,7 +152,7 @@ pub unsafe extern "C" fn z_bytes_deserialize_into_slice( } #[cfg(all(feature = "shared-memory", feature = "unstable"))] -/// @attention Unstable feature. +/// @warning This API has been marked as unstable: it works as advertised, but it may be changed in a future release. /// @brief Deserializes data into an owned SHM buffer by copying it's shared reference. /// /// @param this_: Data to deserialize. @@ -180,7 +180,7 @@ pub unsafe extern "C" fn z_bytes_deserialize_into_owned_shm( } #[cfg(all(feature = "shared-memory", feature = "unstable"))] -/// @attention Unstable feature. +/// @warning This API has been marked as unstable: it works as advertised, but it may be changed in a future release. /// @brief Deserializes data into a loaned SHM buffer. /// /// @param this_: Data to deserialize. @@ -207,7 +207,7 @@ pub unsafe extern "C" fn z_bytes_deserialize_into_loaned_shm( } #[cfg(all(feature = "shared-memory", feature = "unstable"))] -/// @attention Unstable feature. +/// @warning This API has been marked as unstable: it works as advertised, but it may be changed in a future release. /// @brief Deserializes data into a mutably loaned SHM buffer. /// /// @param this_: Data to deserialize. @@ -813,7 +813,7 @@ pub extern "C" fn z_bytes_iterator_next( } #[cfg(all(feature = "shared-memory", feature = "unstable"))] -/// @attention Unstable feature. +/// @warning This API has been marked as unstable: it works as advertised, but it may be changed in a future release. /// @brief Serializes from an immutable SHM buffer consuming it. #[no_mangle] #[allow(clippy::missing_safety_doc)] @@ -830,7 +830,7 @@ pub unsafe extern "C" fn z_bytes_serialize_from_shm( } #[cfg(all(feature = "shared-memory", feature = "unstable"))] -/// @attention Unstable feature. +/// @warning This API has been marked as unstable: it works as advertised, but it may be changed in a future release. /// @brief Serializes from a mutable SHM buffer consuming it. #[no_mangle] #[allow(clippy::missing_safety_doc)] diff --git a/src/publication_cache.rs b/src/publication_cache.rs index 384ed0fcb..d63dcaf51 100644 --- a/src/publication_cache.rs +++ b/src/publication_cache.rs @@ -25,7 +25,7 @@ use crate::{ #[cfg(feature = "unstable")] use crate::{zc_locality_default, zc_locality_t}; -/// @attention Unstable feature. +/// @warning This API has been marked as unstable: it works as advertised, but it may be changed in a future release. /// @brief Options passed to the `ze_declare_publication_cache()` function. #[repr(C)] pub struct ze_publication_cache_options_t { @@ -42,7 +42,7 @@ pub struct ze_publication_cache_options_t { pub resources_limit: usize, } -/// @attention Unstable feature. +/// @warning This API has been marked as unstable: it works as advertised, but it may be changed in a future release. /// @brief Constructs the default value for `ze_publication_cache_options_t`. #[no_mangle] pub extern "C" fn ze_publication_cache_options_default( @@ -69,7 +69,7 @@ decl_c_type!( loaned(ze_loaned_publication_cache_t), ); -/// @attention Unstable feature. +/// @warning This API has been marked as unstable: it works as advertised, but it may be changed in a future release. /// @brief Constructs and declares a publication cache. /// /// @param this_: An uninitialized location in memory where publication cache will be constructed. @@ -118,7 +118,7 @@ pub extern "C" fn ze_declare_publication_cache( } } -/// @attention Unstable feature. +/// @warning This API has been marked as unstable: it works as advertised, but it may be changed in a future release. /// @brief Constructs a publication cache in a gravestone state. #[no_mangle] #[allow(clippy::missing_safety_doc)] @@ -128,7 +128,7 @@ pub extern "C" fn ze_internal_publication_cache_null( this_.as_rust_type_mut_uninit().write(None); } -/// @attention Unstable feature. +/// @warning This API has been marked as unstable: it works as advertised, but it may be changed in a future release. /// @brief Returns ``true`` if publication cache is valid, ``false`` otherwise. #[no_mangle] #[allow(clippy::missing_safety_doc)] @@ -138,7 +138,7 @@ pub extern "C" fn ze_internal_publication_cache_check( this_.as_rust_type_ref().is_some() } -/// @attention Unstable feature. +/// @warning This API has been marked as unstable: it works as advertised, but it may be changed in a future release. /// @brief Undeclares and drops publication cache. /// @return 0 in case of success, negative error code otherwise. #[no_mangle] @@ -155,7 +155,7 @@ pub extern "C" fn ze_undeclare_publication_cache( result::Z_OK } -/// @attention Unstable feature. +/// @warning This API has been marked as unstable: it works as advertised, but it may be changed in a future release. /// @brief Drops publication cache and resets it to its gravestone state. #[no_mangle] #[allow(clippy::missing_safety_doc)] @@ -163,7 +163,7 @@ pub extern "C" fn ze_publication_cache_drop(this: &mut ze_moved_publication_cach std::mem::drop(this.take_rust_type()) } -/// @attention Unstable feature. +/// @warning This API has been marked as unstable: it works as advertised, but it may be changed in a future release. /// @brief Returns the key expression of the publication cache. #[no_mangle] pub extern "C" fn ze_publication_cache_keyexpr( @@ -172,7 +172,7 @@ pub extern "C" fn ze_publication_cache_keyexpr( this_.as_rust_type_ref().key_expr().as_loaned_c_type_ref() } -/// @attention Unstable feature. +/// @warning This API has been marked as unstable: it works as advertised, but it may be changed in a future release. /// @brief Borrows querying subscriber. #[no_mangle] #[allow(clippy::missing_safety_doc)] diff --git a/src/publisher.rs b/src/publisher.rs index 5dcd3ab78..424e043ba 100644 --- a/src/publisher.rs +++ b/src/publisher.rs @@ -51,12 +51,12 @@ pub struct z_publisher_options_t { /// If true, Zenoh will not wait to batch this message with others to reduce the bandwith. pub is_express: bool, #[cfg(feature = "unstable")] - /// @attention Unstable feature. + /// @warning This API has been marked as unstable: it works as advertised, but it may be changed in a future release. /// /// The publisher reliability. pub reliability: z_reliability_t, #[cfg(feature = "unstable")] - /// @attention Unstable feature. + /// @warning This API has been marked as unstable: it works as advertised, but it may be changed in a future release. /// /// The allowed destination for this publisher. pub allowed_destination: zc_locality_t, @@ -179,7 +179,7 @@ pub struct z_publisher_put_options_t { /// The timestamp of the publication. pub timestamp: Option<&'static z_timestamp_t>, #[cfg(feature = "unstable")] - /// @attention Unstable feature. + /// @warning This API has been marked as unstable: it works as advertised, but it may be changed in a future release. /// /// The source info for the publication. pub source_info: Option<&'static mut z_moved_source_info_t>, @@ -287,7 +287,7 @@ pub extern "C" fn z_publisher_delete( } } #[cfg(feature = "unstable")] -/// @attention Unstable feature. +/// @warning This API has been marked as unstable: it works as advertised, but it may be changed in a future release. /// @brief Returns the ID of the publisher. #[no_mangle] pub extern "C" fn z_publisher_id(publisher: &z_loaned_publisher_t) -> z_entity_global_id_t { @@ -312,7 +312,7 @@ decl_c_type!( #[no_mangle] #[cfg(feature = "unstable")] -/// @attention Unstable feature. +/// @warning This API has been marked as unstable: it works as advertised, but it may be changed in a future release. /// @brief Constructs an empty matching listener. pub extern "C" fn zc_internal_matching_listener_null( this_: &mut MaybeUninit, @@ -322,7 +322,7 @@ pub extern "C" fn zc_internal_matching_listener_null( #[no_mangle] #[cfg(feature = "unstable")] -/// @attention Unstable feature. +/// @warning This API has been marked as unstable: it works as advertised, but it may be changed in a future release. /// @brief Checks the matching listener is for the gravestone state pub extern "C" fn zc_internal_matching_listener_check( this_: &zc_owned_matching_listener_t, @@ -331,7 +331,7 @@ pub extern "C" fn zc_internal_matching_listener_check( } #[cfg(feature = "unstable")] -/// @attention Unstable feature. +/// @warning This API has been marked as unstable: it works as advertised, but it may be changed in a future release. /// @brief A struct that indicates if there exist Subscribers matching the Publisher's key expression. #[repr(C)] #[derive(Debug, Clone, Copy)] @@ -341,7 +341,7 @@ pub struct zc_matching_status_t { } #[cfg(feature = "unstable")] -/// @attention Unstable feature. +/// @warning This API has been marked as unstable: it works as advertised, but it may be changed in a future release. /// @brief Constructs matching listener, registering a callback for notifying subscribers matching with a given publisher. /// /// @param this_: An unitilized memory location where matching listener will be constructed. The matching listener will be automatically dropped when publisher is dropped. @@ -381,7 +381,7 @@ pub extern "C" fn zc_publisher_matching_listener_declare( } #[cfg(feature = "unstable")] -/// @attention Unstable feature. +/// @warning This API has been marked as unstable: it works as advertised, but it may be changed in a future release. /// @brief Undeclares the given matching listener, droping and invalidating it. /// /// @return 0 in case of success, negative error code otherwise. @@ -400,7 +400,7 @@ pub extern "C" fn zc_publisher_matching_listener_undeclare( } #[cfg(feature = "unstable")] -/// @attention Unstable feature. +/// @warning This API has been marked as unstable: it works as advertised, but it may be changed in a future release. /// @brief Undeclares the given matching listener, droping and invalidating it. #[no_mangle] #[allow(clippy::missing_safety_doc)] @@ -409,7 +409,7 @@ pub extern "C" fn zc_publisher_matching_listener_drop(this: &mut zc_moved_matchi } #[cfg(feature = "unstable")] -/// @attention Unstable feature. +/// @warning This API has been marked as unstable: it works as advertised, but it may be changed in a future release. /// @brief Gets publisher matching status - i.e. if there are any subscribers matching its key expression. /// /// @return 0 in case of success, negative error code otherwise (in this case matching_status is not updated). diff --git a/src/put.rs b/src/put.rs index ffb668cfd..b5ee436af 100644 --- a/src/put.rs +++ b/src/put.rs @@ -44,17 +44,17 @@ pub struct z_put_options_t { /// The timestamp of this message. pub timestamp: Option<&'static mut z_timestamp_t>, #[cfg(feature = "unstable")] - /// @attention Unstable feature. + /// @warning This API has been marked as unstable: it works as advertised, but it may be changed in a future release. /// /// The put operation reliability. reliability: z_reliability_t, #[cfg(feature = "unstable")] - /// @attention Unstable feature. + /// @warning This API has been marked as unstable: it works as advertised, but it may be changed in a future release. /// /// The allowed destination of this message. pub allowed_destination: zc_locality_t, #[cfg(feature = "unstable")] - /// @attention Unstable feature. + /// @warning This API has been marked as unstable: it works as advertised, but it may be changed in a future release. /// /// The source info for the message. pub source_info: Option<&'static mut z_moved_source_info_t>, @@ -148,12 +148,12 @@ pub struct z_delete_options_t { /// The timestamp of this message. pub timestamp: Option<&'static mut z_timestamp_t>, #[cfg(feature = "unstable")] - /// @attention Unstable feature. + /// @warning This API has been marked as unstable: it works as advertised, but it may be changed in a future release. /// /// The delete operation reliability. pub reliability: z_reliability_t, #[cfg(feature = "unstable")] - /// @attention Unstable feature. + /// @warning This API has been marked as unstable: it works as advertised, but it may be changed in a future release. /// /// The allowed destination of this message. pub allowed_destination: zc_locality_t, diff --git a/src/queryable.rs b/src/queryable.rs index 529f23109..47eb3ee4c 100644 --- a/src/queryable.rs +++ b/src/queryable.rs @@ -127,7 +127,7 @@ pub struct z_query_reply_options_t { /// The timestamp of the reply. pub timestamp: Option<&'static mut z_timestamp_t>, #[cfg(feature = "unstable")] - /// @attention Unstable feature. + /// @warning This API has been marked as unstable: it works as advertised, but it may be changed in a future release. /// /// The source info for the reply. pub source_info: Option<&'static mut z_moved_source_info_t>, @@ -183,7 +183,7 @@ pub struct z_query_reply_del_options_t { /// The timestamp of the reply. pub timestamp: Option<&'static mut z_timestamp_t>, #[cfg(feature = "unstable")] - /// @attention Unstable feature. + /// @warning This API has been marked as unstable: it works as advertised, but it may be changed in a future release. /// /// The source info for the reply. pub source_info: Option<&'static mut z_moved_source_info_t>, @@ -284,7 +284,7 @@ pub extern "C" fn z_internal_queryable_check(this_: &z_owned_queryable_t) -> boo } #[cfg(feature = "unstable")] -/// @attention Unstable feature. +/// @warning This API has been marked as unstable: it works as advertised, but it may be changed in a future release. /// @brief Returns the ID of the queryable. #[no_mangle] pub extern "C" fn z_queryable_id(queryable: &z_loaned_queryable_t) -> z_entity_global_id_t { diff --git a/src/querying_subscriber.rs b/src/querying_subscriber.rs index 37153b713..ea4bcc45a 100644 --- a/src/querying_subscriber.rs +++ b/src/querying_subscriber.rs @@ -50,7 +50,7 @@ pub extern "C" fn ze_internal_querying_subscriber_null( this.as_rust_type_mut_uninit().write(None); } -/// @attention Unstable feature. +/// @warning This API has been marked as unstable: it works as advertised, but it may be changed in a future release. /// @brief A set of options that can be applied to a querying subscriber, /// upon its declaration via `ze_declare_querying_subscriber()`. /// @@ -75,7 +75,7 @@ pub struct ze_querying_subscriber_options_t { query_timeout_ms: u64, } -/// @attention Unstable feature. +/// @warning This API has been marked as unstable: it works as advertised, but it may be changed in a future release. /// @brief Constructs the default value for `ze_querying_subscriber_options_t`. #[no_mangle] pub extern "C" fn ze_querying_subscriber_options_default( @@ -94,7 +94,7 @@ pub extern "C" fn ze_querying_subscriber_options_default( }); } -/// @attention Unstable feature. +/// @warning This API has been marked as unstable: it works as advertised, but it may be changed in a future release. /// @brief Constructs and declares a querying subscriber for a given key expression. /// /// @param this_: An uninitialized memory location where querying subscriber will be constructed. @@ -155,7 +155,7 @@ pub unsafe extern "C" fn ze_declare_querying_subscriber( } } -/// @attention Unstable feature. +/// @warning This API has been marked as unstable: it works as advertised, but it may be changed in a future release. /// @brief Make querying subscriber perform an additional query on a specified selector. /// The queried samples will be merged with the received publications and made available in the subscriber callback. /// @return 0 in case of success, negative error code otherwise. @@ -220,7 +220,7 @@ pub unsafe extern "C" fn ze_querying_subscriber_get( result::Z_OK } -/// @attention Unstable feature. +/// @warning This API has been marked as unstable: it works as advertised, but it may be changed in a future release. /// @brief Undeclares the given querying subscriber, drops it and resets to a gravestone state. /// /// @return 0 in case of success, negative error code otherwise. @@ -237,14 +237,14 @@ pub extern "C" fn ze_undeclare_querying_subscriber( result::Z_OK } -/// @attention Unstable feature. +/// @warning This API has been marked as unstable: it works as advertised, but it may be changed in a future release. /// @brief Drops querying subscriber. #[no_mangle] pub extern "C" fn ze_querying_subscriber_drop(this_: &mut ze_moved_querying_subscriber_t) { std::mem::drop(this_.take_rust_type()) } -/// @attention Unstable feature. +/// @warning This API has been marked as unstable: it works as advertised, but it may be changed in a future release. /// @brief Returns ``true`` if querying subscriber is valid, ``false`` otherwise. #[no_mangle] pub extern "C" fn ze_internal_querying_subscriber_check( @@ -253,7 +253,7 @@ pub extern "C" fn ze_internal_querying_subscriber_check( this_.as_rust_type_ref().is_some() } -/// @attention Unstable feature. +/// @warning This API has been marked as unstable: it works as advertised, but it may be changed in a future release. /// @brief Borrows querying subscriber. #[no_mangle] #[allow(clippy::missing_safety_doc)] diff --git a/src/scouting.rs b/src/scouting.rs index 4d199c065..9b54ba593 100644 --- a/src/scouting.rs +++ b/src/scouting.rs @@ -64,7 +64,7 @@ pub extern "C" fn z_internal_hello_null(this_: &mut MaybeUninit } #[cfg(feature = "unstable")] -/// @attention Unstable feature. +/// @warning This API has been marked as unstable: it works as advertised, but it may be changed in a future release. /// @brief Returns id of Zenoh entity that transmitted hello message. #[no_mangle] pub extern "C" fn z_hello_zid(this_: &z_loaned_hello_t) -> z_id_t { diff --git a/src/session.rs b/src/session.rs index 5307f676e..007343bed 100644 --- a/src/session.rs +++ b/src/session.rs @@ -79,7 +79,7 @@ pub extern "C" fn z_open( } #[cfg(all(feature = "shared-memory", feature = "unstable"))] -/// @attention Unstable feature. +/// @warning This API has been marked as unstable: it works as advertised, but it may be changed in a future release. /// @brief Constructs and opens a new Zenoh session with specified client storage. /// /// @return 0 in case of success, negative error code otherwise (in this case the session will be in its gravestone state). diff --git a/src/shm/buffer/zshm.rs b/src/shm/buffer/zshm.rs index 9be89a5fa..27630c497 100644 --- a/src/shm/buffer/zshm.rs +++ b/src/shm/buffer/zshm.rs @@ -29,7 +29,7 @@ decl_c_type!( loaned(z_loaned_shm_t, zshm), ); -/// @attention Unstable feature. +/// @warning This API has been marked as unstable: it works as advertised, but it may be changed in a future release. /// @brief Constructs ZShm slice from ZShmMut slice. #[no_mangle] pub extern "C" fn z_shm_from_mut( @@ -40,21 +40,21 @@ pub extern "C" fn z_shm_from_mut( this_.as_rust_type_mut_uninit().write(shm); } -/// @attention Unstable feature. +/// @warning This API has been marked as unstable: it works as advertised, but it may be changed in a future release. /// @brief Constructs ZShm slice in its gravestone value. #[no_mangle] pub extern "C" fn z_internal_shm_null(this_: &mut MaybeUninit) { this_.as_rust_type_mut_uninit().write(None); } -/// @attention Unstable feature. +/// @warning This API has been marked as unstable: it works as advertised, but it may be changed in a future release. /// @return ``true`` if `this` is valid. #[no_mangle] pub extern "C" fn z_internal_shm_check(this_: &z_owned_shm_t) -> bool { this_.as_rust_type_ref().is_some() } -/// @attention Unstable feature. +/// @warning This API has been marked as unstable: it works as advertised, but it may be changed in a future release. /// @brief Converts borrowed ZShm slice to owned ZShm slice by performing a shallow SHM reference copy. #[no_mangle] pub extern "C" fn z_shm_clone(out: &mut MaybeUninit, this_: &z_loaned_shm_t) { @@ -63,7 +63,7 @@ pub extern "C" fn z_shm_clone(out: &mut MaybeUninit, this_: &z_lo out.as_rust_type_mut_uninit().write(Some(copy)); } -/// @attention Unstable feature. +/// @warning This API has been marked as unstable: it works as advertised, but it may be changed in a future release. /// @brief Borrows ZShm slice. #[no_mangle] #[allow(clippy::missing_safety_doc)] @@ -88,7 +88,7 @@ pub unsafe extern "C" fn z_shm_loan_mut(this_: &mut z_owned_shm_t) -> &mut z_loa this.as_loaned_c_type_mut() } -/// @attention Unstable feature. +/// @warning This API has been marked as unstable: it works as advertised, but it may be changed in a future release. /// @brief Mutably borrows ZShm slice as borrowed ZShmMut slice. #[no_mangle] #[allow(clippy::missing_safety_doc)] @@ -105,14 +105,14 @@ pub unsafe extern "C" fn z_shm_try_mut(this_: &mut z_owned_shm_t) -> *mut z_loan } } -/// @attention Unstable feature. +/// @warning This API has been marked as unstable: it works as advertised, but it may be changed in a future release. /// @brief Deletes ZShm slice. #[no_mangle] pub extern "C" fn z_shm_drop(this_: &mut z_moved_shm_t) { let _ = this_.take_rust_type(); } -/// @attention Unstable feature. +/// @warning This API has been marked as unstable: it works as advertised, but it may be changed in a future release. /// @brief Tries to reborrow mutably-borrowed ZShm slice as borrowed ZShmMut slice. #[no_mangle] pub extern "C" fn z_shm_try_reloan_mut(this_: &mut z_loaned_shm_t) -> *mut z_loaned_shm_mut_t { @@ -126,14 +126,14 @@ pub extern "C" fn z_shm_try_reloan_mut(this_: &mut z_loaned_shm_t) -> *mut z_loa } } -/// @attention Unstable feature. +/// @warning This API has been marked as unstable: it works as advertised, but it may be changed in a future release. /// @return the length of the ZShm slice. #[no_mangle] pub extern "C" fn z_shm_len(this_: &z_loaned_shm_t) -> usize { this_.as_rust_type_ref().len() } -/// @attention Unstable feature. +/// @warning This API has been marked as unstable: it works as advertised, but it may be changed in a future release. /// @return the pointer of the ZShm slice. #[no_mangle] pub extern "C" fn z_shm_data(this_: &z_loaned_shm_t) -> *const libc::c_uchar { diff --git a/src/shm/buffer/zshmmut.rs b/src/shm/buffer/zshmmut.rs index 3037b7090..eafb28b3b 100644 --- a/src/shm/buffer/zshmmut.rs +++ b/src/shm/buffer/zshmmut.rs @@ -29,7 +29,7 @@ decl_c_type!( loaned(z_loaned_shm_mut_t, zshmmut), ); -/// @attention Unstable feature. +/// @warning This API has been marked as unstable: it works as advertised, but it may be changed in a future release. /// @brief Tries to construct ZShmMut slice from ZShm slice. #[no_mangle] pub extern "C" fn z_shm_mut_try_from_immut( @@ -43,21 +43,21 @@ pub extern "C" fn z_shm_mut_try_from_immut( this.as_rust_type_mut_uninit().write(shm); } -/// @attention Unstable feature. +/// @warning This API has been marked as unstable: it works as advertised, but it may be changed in a future release. /// @brief Constructs ZShmMut slice in its gravestone value. #[no_mangle] pub extern "C" fn z_internal_shm_mut_null(this_: &mut MaybeUninit) { this_.as_rust_type_mut_uninit().write(None); } -/// @attention Unstable feature. +/// @warning This API has been marked as unstable: it works as advertised, but it may be changed in a future release. /// @return ``true`` if `this` is valid. #[no_mangle] pub extern "C" fn z_internal_shm_mut_check(this_: &z_owned_shm_mut_t) -> bool { this_.as_rust_type_ref().is_some() } -/// @attention Unstable feature. +/// @warning This API has been marked as unstable: it works as advertised, but it may be changed in a future release. /// @brief Borrows ZShmMut slice. #[no_mangle] #[allow(clippy::missing_safety_doc)] @@ -70,7 +70,7 @@ pub unsafe extern "C" fn z_shm_mut_loan(this_: &z_owned_shm_mut_t) -> &z_loaned_ shmmut.as_loaned_c_type_ref() } -/// @attention Unstable feature. +/// @warning This API has been marked as unstable: it works as advertised, but it may be changed in a future release. /// @brief Mutably borrows ZShmMut slice. #[no_mangle] #[allow(clippy::missing_safety_doc)] @@ -85,21 +85,21 @@ pub unsafe extern "C" fn z_shm_mut_loan_mut( shmmut.as_loaned_c_type_mut() } -/// @attention Unstable feature. +/// @warning This API has been marked as unstable: it works as advertised, but it may be changed in a future release. /// @brief Deletes ZShmMut slice. #[no_mangle] pub extern "C" fn z_shm_mut_drop(this_: &mut z_moved_shm_mut_t) { let _ = this_.take_rust_type(); } -/// @attention Unstable feature. +/// @warning This API has been marked as unstable: it works as advertised, but it may be changed in a future release. /// @return the length of the ZShmMut slice. #[no_mangle] pub extern "C" fn z_shm_mut_len(this_: &z_loaned_shm_mut_t) -> usize { this_.as_rust_type_ref().len() } -/// @attention Unstable feature. +/// @warning This API has been marked as unstable: it works as advertised, but it may be changed in a future release. /// @return the immutable pointer to the underlying data. #[no_mangle] pub extern "C" fn z_shm_mut_data(this_: &z_loaned_shm_mut_t) -> *const libc::c_uchar { @@ -107,7 +107,7 @@ pub extern "C" fn z_shm_mut_data(this_: &z_loaned_shm_mut_t) -> *const libc::c_u s.as_ref().as_ptr() } -/// @attention Unstable feature. +/// @warning This API has been marked as unstable: it works as advertised, but it may be changed in a future release. /// @return the mutable pointer to the underlying data. #[no_mangle] pub extern "C" fn z_shm_mut_data_mut(this_: &mut z_loaned_shm_mut_t) -> *mut libc::c_uchar { diff --git a/src/shm/client/shm_client.rs b/src/shm/client/shm_client.rs index 4a77c1f40..0e0aa1ede 100644 --- a/src/shm/client/shm_client.rs +++ b/src/shm/client/shm_client.rs @@ -28,7 +28,7 @@ use crate::{ transmute::{RustTypeRef, RustTypeRefUninit, TakeRustType}, }; -/// @attention Unstable feature. +/// @warning This API has been marked as unstable: it works as advertised, but it may be changed in a future release. /// @brief Callback for ShmClient. #[derive(Debug)] #[repr(C)] @@ -68,7 +68,7 @@ impl ShmClient for DynamicShmClient { } } -/// @attention Unstable feature. +/// @warning This API has been marked as unstable: it works as advertised, but it may be changed in a future release. /// @brief Creates a new SHM Client. #[no_mangle] pub extern "C" fn z_shm_client_new( @@ -80,21 +80,21 @@ pub extern "C" fn z_shm_client_new( this.as_rust_type_mut_uninit().write(Some(client)); } -/// @attention Unstable feature. +/// @warning This API has been marked as unstable: it works as advertised, but it may be changed in a future release. /// @brief Constructs SHM client in its gravestone value. #[no_mangle] pub extern "C" fn z_internal_shm_client_null(this_: &mut MaybeUninit) { this_.as_rust_type_mut_uninit().write(None); } -/// @attention Unstable feature. +/// @warning This API has been marked as unstable: it works as advertised, but it may be changed in a future release. /// @return Returns ``true`` if `this` is valid. #[no_mangle] pub extern "C" fn z_internal_shm_client_check(this_: &z_owned_shm_client_t) -> bool { this_.as_rust_type_ref().is_some() } -/// @attention Unstable feature. +/// @warning This API has been marked as unstable: it works as advertised, but it may be changed in a future release. /// @brief Deletes SHM Client. #[no_mangle] pub extern "C" fn z_shm_client_drop(this_: &mut z_moved_shm_client_t) { diff --git a/src/shm/client/shm_segment.rs b/src/shm/client/shm_segment.rs index 8d1724a0c..4740bd21e 100644 --- a/src/shm/client/shm_segment.rs +++ b/src/shm/client/shm_segment.rs @@ -26,7 +26,7 @@ use crate::{ shm::common::types::z_chunk_id_t, }; -/// @attention Unstable feature. +/// @warning This API has been marked as unstable: it works as advertised, but it may be changed in a future release. /// @brief Callbacks for ShmSegment. #[derive(Debug)] #[repr(C)] @@ -34,7 +34,7 @@ pub struct zc_shm_segment_callbacks_t { map_fn: unsafe extern "C" fn(chunk_id: z_chunk_id_t, context: *mut c_void) -> *mut u8, } -/// @attention Unstable feature. +/// @warning This API has been marked as unstable: it works as advertised, but it may be changed in a future release. /// @brief An ShmSegment. #[derive(Debug)] #[repr(C)] diff --git a/src/shm/client_storage/mod.rs b/src/shm/client_storage/mod.rs index 6c0949a64..4bd62b5b6 100644 --- a/src/shm/client_storage/mod.rs +++ b/src/shm/client_storage/mod.rs @@ -30,7 +30,7 @@ decl_c_type!( loaned(zc_loaned_shm_client_list_t), ); -/// @attention Unstable feature. +/// @warning This API has been marked as unstable: it works as advertised, but it may be changed in a future release. /// @brief Creates a new empty list of SHM Clients. #[no_mangle] pub extern "C" fn zc_shm_client_list_new(this_: &mut MaybeUninit) { @@ -38,7 +38,7 @@ pub extern "C" fn zc_shm_client_list_new(this_: &mut MaybeUninit bool { this_.as_rust_type_ref().is_some() } -/// @attention Unstable feature. +/// @warning This API has been marked as unstable: it works as advertised, but it may be changed in a future release. /// @brief Deletes list of SHM Clients. #[no_mangle] pub extern "C" fn zc_shm_client_list_drop(this_: &mut zc_moved_shm_client_list_t) { let _ = this_.take_rust_type(); } -/// @attention Unstable feature. +/// @warning This API has been marked as unstable: it works as advertised, but it may be changed in a future release. /// @brief Borrows list of SHM Clients. #[no_mangle] #[allow(clippy::missing_safety_doc)] @@ -74,7 +74,7 @@ pub unsafe extern "C" fn zc_shm_client_list_loan( .as_loaned_c_type_ref() } -/// @attention Unstable feature. +/// @warning This API has been marked as unstable: it works as advertised, but it may be changed in a future release. /// @brief Mutably borrows list of SHM Clients. #[no_mangle] #[allow(clippy::missing_safety_doc)] @@ -87,7 +87,7 @@ pub unsafe extern "C" fn zc_shm_client_list_loan_mut( .as_loaned_c_type_mut() } -/// @attention Unstable feature. +/// @warning This API has been marked as unstable: it works as advertised, but it may be changed in a future release. #[no_mangle] pub extern "C" fn zc_shm_client_list_add_client( id: z_protocol_id_t, @@ -106,7 +106,7 @@ decl_c_type!( loaned(z_loaned_shm_client_storage_t), ); -/// @attention Unstable feature. +/// @warning This API has been marked as unstable: it works as advertised, but it may be changed in a future release. #[no_mangle] pub extern "C" fn z_ref_shm_client_storage_global( this: &mut MaybeUninit, @@ -115,7 +115,7 @@ pub extern "C" fn z_ref_shm_client_storage_global( .write(Some(Arc::clone(&GLOBAL_CLIENT_STORAGE.read()))); } -/// @attention Unstable feature. +/// @warning This API has been marked as unstable: it works as advertised, but it may be changed in a future release. #[no_mangle] pub extern "C" fn z_shm_client_storage_new_default( this: &mut MaybeUninit, @@ -127,7 +127,7 @@ pub extern "C" fn z_shm_client_storage_new_default( ))); } -/// @attention Unstable feature. +/// @warning This API has been marked as unstable: it works as advertised, but it may be changed in a future release. #[no_mangle] pub extern "C" fn z_shm_client_storage_new( this: &mut MaybeUninit, @@ -150,7 +150,7 @@ pub extern "C" fn z_shm_client_storage_new( Z_OK } -/// @attention Unstable feature. +/// @warning This API has been marked as unstable: it works as advertised, but it may be changed in a future release. /// @brief Performs a shallow copy of SHM Client Storage. #[no_mangle] pub extern "C" fn z_shm_client_storage_clone( @@ -161,7 +161,7 @@ pub extern "C" fn z_shm_client_storage_clone( .write(Some(from.as_rust_type_ref().clone())); } -/// @attention Unstable feature. +/// @warning This API has been marked as unstable: it works as advertised, but it may be changed in a future release. /// Constructs SHM Client Storage in its gravestone value. #[no_mangle] pub extern "C" fn z_internal_shm_client_storage_null( @@ -170,7 +170,7 @@ pub extern "C" fn z_internal_shm_client_storage_null( this_.as_rust_type_mut_uninit().write(None); } -/// @attention Unstable feature. +/// @warning This API has been marked as unstable: it works as advertised, but it may be changed in a future release. /// @return ``true`` if `this` is valid. #[no_mangle] pub extern "C" fn z_internal_shm_client_storage_check( @@ -179,14 +179,14 @@ pub extern "C" fn z_internal_shm_client_storage_check( this_.as_rust_type_ref().is_some() } -/// @attention Unstable feature. +/// @warning This API has been marked as unstable: it works as advertised, but it may be changed in a future release. /// @brief Derefs SHM Client Storage. #[no_mangle] pub extern "C" fn z_shm_client_storage_drop(this_: &mut z_moved_shm_client_storage_t) { let _ = this_.take_rust_type(); } -/// @attention Unstable feature. +/// @warning This API has been marked as unstable: it works as advertised, but it may be changed in a future release. /// @brief Borrows SHM Client Storage. #[no_mangle] #[allow(clippy::missing_safety_doc)] diff --git a/src/shm/common/types.rs b/src/shm/common/types.rs index 86658543c..4b5573480 100644 --- a/src/shm/common/types.rs +++ b/src/shm/common/types.rs @@ -12,19 +12,19 @@ // ZettaScale Zenoh Team, // -/// @attention Unstable feature. +/// @warning This API has been marked as unstable: it works as advertised, but it may be changed in a future release. /// @brief Unique protocol identifier. /// Here is a contract: it is up to user to make sure that incompatible ShmClient /// and ShmProviderBackend implementations will never use the same ProtocolID. #[allow(non_camel_case_types)] pub type z_protocol_id_t = u32; -/// @attention Unstable feature. +/// @warning This API has been marked as unstable: it works as advertised, but it may be changed in a future release. /// @brief Unique segment identifier. #[allow(non_camel_case_types)] pub type z_segment_id_t = u32; -/// @attention Unstable feature. +/// @warning This API has been marked as unstable: it works as advertised, but it may be changed in a future release. /// @brief Chunk id within it's segment. #[allow(non_camel_case_types)] pub type z_chunk_id_t = u32; diff --git a/src/shm/protocol_implementations/posix/posix_shm_client.rs b/src/shm/protocol_implementations/posix/posix_shm_client.rs index e36736645..b9eae945b 100644 --- a/src/shm/protocol_implementations/posix/posix_shm_client.rs +++ b/src/shm/protocol_implementations/posix/posix_shm_client.rs @@ -18,7 +18,7 @@ use zenoh::shm::{PosixShmClient, ShmClient}; use crate::{transmute::RustTypeRefUninit, z_owned_shm_client_t}; -/// @attention Unstable feature. +/// @warning This API has been marked as unstable: it works as advertised, but it may be changed in a future release. /// @brief Creates a new POSIX SHM Client. #[no_mangle] pub extern "C" fn z_posix_shm_client_new(this_: &mut MaybeUninit) { diff --git a/src/shm/protocol_implementations/posix/posix_shm_provider.rs b/src/shm/protocol_implementations/posix/posix_shm_provider.rs index 291ce0c19..f829dce30 100644 --- a/src/shm/protocol_implementations/posix/posix_shm_provider.rs +++ b/src/shm/protocol_implementations/posix/posix_shm_provider.rs @@ -32,7 +32,7 @@ pub type PosixShmProvider = pub type PosixAllocLayout = AllocLayout<'static, StaticProtocolID, PosixShmProviderBackend>; -/// @attention Unstable feature. +/// @warning This API has been marked as unstable: it works as advertised, but it may be changed in a future release. /// @brief Creates a new POSIX SHM Provider. #[no_mangle] pub extern "C" fn z_posix_shm_provider_new( diff --git a/src/shm/protocol_implementations/posix/protocol_id.rs b/src/shm/protocol_implementations/posix/protocol_id.rs index 3d2fbc29f..babbc89f5 100644 --- a/src/shm/protocol_implementations/posix/protocol_id.rs +++ b/src/shm/protocol_implementations/posix/protocol_id.rs @@ -15,7 +15,7 @@ use libc::c_uint; use zenoh::shm::POSIX_PROTOCOL_ID; -/// @attention Unstable feature. +/// @warning This API has been marked as unstable: it works as advertised, but it may be changed in a future release. /// @brief fProtocol identifier for POSIX SHM Protocol. #[no_mangle] pub static Z_SHM_POSIX_PROTOCOL_ID: c_uint = POSIX_PROTOCOL_ID as c_uint; diff --git a/src/shm/provider/alloc_layout.rs b/src/shm/provider/alloc_layout.rs index 7e2c62c9d..e141d7776 100644 --- a/src/shm/provider/alloc_layout.rs +++ b/src/shm/provider/alloc_layout.rs @@ -50,7 +50,7 @@ decl_c_type!( loaned(z_loaned_alloc_layout_t), ); -/// @attention Unstable feature. +/// @warning This API has been marked as unstable: it works as advertised, but it may be changed in a future release. /// @brief Creates a new Alloc Layout for SHM Provider. #[no_mangle] pub extern "C" fn z_alloc_layout_new( diff --git a/src/shm/provider/chunk.rs b/src/shm/provider/chunk.rs index bf1d1c94c..e28b6a13b 100644 --- a/src/shm/provider/chunk.rs +++ b/src/shm/provider/chunk.rs @@ -18,7 +18,7 @@ use zenoh::shm::{AllocatedChunk, ChunkDescriptor}; use crate::shm::common::types::{z_chunk_id_t, z_segment_id_t}; -/// @attention Unstable feature. +/// @warning This API has been marked as unstable: it works as advertised, but it may be changed in a future release. /// @brief A ChunkDescriptor. #[repr(C)] pub struct z_chunk_descriptor_t { @@ -44,7 +44,7 @@ impl From<&ChunkDescriptor> for z_chunk_descriptor_t { } } -/// @attention Unstable feature. +/// @warning This API has been marked as unstable: it works as advertised, but it may be changed in a future release. /// @brief An AllocatedChunk. #[repr(C)] pub struct z_allocated_chunk_t { diff --git a/src/shm/provider/shm_provider.rs b/src/shm/provider/shm_provider.rs index 63c06a26c..0766a7929 100644 --- a/src/shm/provider/shm_provider.rs +++ b/src/shm/provider/shm_provider.rs @@ -54,7 +54,7 @@ decl_c_type!( loaned(z_loaned_shm_provider_t), ); -/// @attention Unstable feature. +/// @warning This API has been marked as unstable: it works as advertised, but it may be changed in a future release. /// @brief Creates a new SHM Provider. #[no_mangle] pub extern "C" fn z_shm_provider_new( @@ -73,7 +73,7 @@ pub extern "C" fn z_shm_provider_new( .write(Some(CSHMProvider::Dynamic(provider))); } -/// @attention Unstable feature. +/// @warning This API has been marked as unstable: it works as advertised, but it may be changed in a future release. /// @brief Creates a new threadsafe SHM Provider. #[no_mangle] pub extern "C" fn z_shm_provider_threadsafe_new( @@ -92,21 +92,21 @@ pub extern "C" fn z_shm_provider_threadsafe_new( .write(Some(CSHMProvider::DynamicThreadsafe(provider))); } -/// @attention Unstable feature. +/// @warning This API has been marked as unstable: it works as advertised, but it may be changed in a future release. /// @brief Constructs SHM Provider in its gravestone value. #[no_mangle] pub extern "C" fn z_internal_shm_provider_null(this_: &mut MaybeUninit) { this_.as_rust_type_mut_uninit().write(None); } -/// @attention Unstable feature. +/// @warning This API has been marked as unstable: it works as advertised, but it may be changed in a future release. /// @brief Returns ``true`` if `this` is valid. #[no_mangle] pub extern "C" fn z_internal_shm_provider_check(this_: &z_owned_shm_provider_t) -> bool { this_.as_rust_type_ref().is_some() } -/// @attention Unstable feature. +/// @warning This API has been marked as unstable: it works as advertised, but it may be changed in a future release. /// @brief Borrows SHM Provider. #[no_mangle] #[allow(clippy::missing_safety_doc)] @@ -119,14 +119,14 @@ pub unsafe extern "C" fn z_shm_provider_loan( .as_loaned_c_type_ref() } -/// @attention Unstable feature. +/// @warning This API has been marked as unstable: it works as advertised, but it may be changed in a future release. /// @brief Deletes SHM Provider. #[no_mangle] pub extern "C" fn z_shm_provider_drop(this_: &mut z_moved_shm_provider_t) { let _ = this_.take_rust_type(); } -/// @attention Unstable feature. +/// @warning This API has been marked as unstable: it works as advertised, but it may be changed in a future release. #[no_mangle] pub extern "C" fn z_shm_provider_alloc( out_result: &mut MaybeUninit, @@ -137,7 +137,7 @@ pub extern "C" fn z_shm_provider_alloc( alloc::(out_result, provider, size, alignment) } -/// @attention Unstable feature. +/// @warning This API has been marked as unstable: it works as advertised, but it may be changed in a future release. #[no_mangle] pub extern "C" fn z_shm_provider_alloc_gc( out_result: &mut MaybeUninit, @@ -148,7 +148,7 @@ pub extern "C" fn z_shm_provider_alloc_gc( alloc::(out_result, provider, size, alignment) } -/// @attention Unstable feature. +/// @warning This API has been marked as unstable: it works as advertised, but it may be changed in a future release. #[no_mangle] pub extern "C" fn z_shm_provider_alloc_gc_defrag( out_result: &mut MaybeUninit, @@ -159,7 +159,7 @@ pub extern "C" fn z_shm_provider_alloc_gc_defrag( alloc::>(out_result, provider, size, alignment) } -/// @attention Unstable feature. +/// @warning This API has been marked as unstable: it works as advertised, but it may be changed in a future release. #[no_mangle] pub extern "C" fn z_shm_provider_alloc_gc_defrag_dealloc( out_result: &mut MaybeUninit, @@ -170,7 +170,7 @@ pub extern "C" fn z_shm_provider_alloc_gc_defrag_dealloc( alloc::>>(out_result, provider, size, alignment) } -/// @attention Unstable feature. +/// @warning This API has been marked as unstable: it works as advertised, but it may be changed in a future release. #[no_mangle] pub extern "C" fn z_shm_provider_alloc_gc_defrag_blocking( out_result: &mut MaybeUninit, @@ -181,7 +181,7 @@ pub extern "C" fn z_shm_provider_alloc_gc_defrag_blocking( alloc::>>(out_result, provider, size, alignment) } -/// @attention Unstable feature. +/// @warning This API has been marked as unstable: it works as advertised, but it may be changed in a future release. #[no_mangle] pub extern "C" fn z_shm_provider_alloc_gc_defrag_async( out_result: &'static mut MaybeUninit, @@ -204,25 +204,25 @@ pub extern "C" fn z_shm_provider_alloc_gc_defrag_async( ) } -/// @attention Unstable feature. +/// @warning This API has been marked as unstable: it works as advertised, but it may be changed in a future release. #[no_mangle] pub extern "C" fn z_shm_provider_defragment(provider: &z_loaned_shm_provider_t) -> usize { defragment(provider) } -/// @attention Unstable feature. +/// @warning This API has been marked as unstable: it works as advertised, but it may be changed in a future release. #[no_mangle] pub extern "C" fn z_shm_provider_garbage_collect(provider: &z_loaned_shm_provider_t) -> usize { garbage_collect(provider) } -/// @attention Unstable feature. +/// @warning This API has been marked as unstable: it works as advertised, but it may be changed in a future release. #[no_mangle] pub extern "C" fn z_shm_provider_available(provider: &z_loaned_shm_provider_t) -> usize { available(provider) } -/// @attention Unstable feature. +/// @warning This API has been marked as unstable: it works as advertised, but it may be changed in a future release. #[no_mangle] pub extern "C" fn z_shm_provider_map( out_result: &mut MaybeUninit, diff --git a/src/shm/provider/shm_provider_backend.rs b/src/shm/provider/shm_provider_backend.rs index e636f1584..21eda93b1 100644 --- a/src/shm/provider/shm_provider_backend.rs +++ b/src/shm/provider/shm_provider_backend.rs @@ -26,7 +26,7 @@ use crate::{ z_loaned_memory_layout_t, z_owned_chunk_alloc_result_t, z_owned_memory_layout_t, }; -/// @attention Unstable feature. +/// @warning This API has been marked as unstable: it works as advertised, but it may be changed in a future release. /// @brief Callbacks for ShmProviderBackend. #[derive(Debug)] #[repr(C)] diff --git a/src/shm/provider/types.rs b/src/shm/provider/types.rs index ce3f55cdb..bcedb0150 100644 --- a/src/shm/provider/types.rs +++ b/src/shm/provider/types.rs @@ -32,7 +32,7 @@ use crate::{ z_owned_shm_mut_t, }; -/// @attention Unstable feature. +/// @warning This API has been marked as unstable: it works as advertised, but it may be changed in a future release. /// @brief Allocation errors #[repr(C)] #[derive(Clone, Copy)] @@ -67,7 +67,7 @@ impl From for ZAllocError { } } -/// @attention Unstable feature. +/// @warning This API has been marked as unstable: it works as advertised, but it may be changed in a future release. /// @brief Layouting errors #[repr(C)] #[derive(Clone, Copy)] @@ -102,7 +102,7 @@ impl From for ZLayoutError { } } -/// @attention Unstable feature. +/// @warning This API has been marked as unstable: it works as advertised, but it may be changed in a future release. /// @brief An AllocAlignment. #[repr(C)] #[derive(Clone, Copy)] @@ -117,7 +117,7 @@ decl_c_type_inequal!( loaned(z_loaned_memory_layout_t), ); -/// @attention Unstable feature. +/// @warning This API has been marked as unstable: it works as advertised, but it may be changed in a future release. /// @brief Creates a new Memory Layout. #[no_mangle] pub extern "C" fn z_memory_layout_new( @@ -145,21 +145,21 @@ fn create_memory_layout( MemoryLayout::new(size, alignment) } -/// @attention Unstable feature. +/// @warning This API has been marked as unstable: it works as advertised, but it may be changed in a future release. /// @brief Constructs Memory Layout in its gravestone value. #[no_mangle] pub extern "C" fn z_internal_memory_layout_null(this_: &mut MaybeUninit) { this_.as_rust_type_mut_uninit().write(None); } -/// @attention Unstable feature. +/// @warning This API has been marked as unstable: it works as advertised, but it may be changed in a future release. /// @brief Returns ``true`` if `this` is valid. #[no_mangle] pub extern "C" fn z_internal_memory_layout_check(this_: &z_owned_memory_layout_t) -> bool { this_.as_rust_type_ref().is_some() } -/// @attention Unstable feature. +/// @warning This API has been marked as unstable: it works as advertised, but it may be changed in a future release. /// @brief Borrows Memory Layout. #[no_mangle] #[allow(clippy::missing_safety_doc)] @@ -172,14 +172,14 @@ pub unsafe extern "C" fn z_memory_layout_loan( .as_loaned_c_type_ref() } -/// @attention Unstable feature. +/// @warning This API has been marked as unstable: it works as advertised, but it may be changed in a future release. /// @brief Deletes Memory Layout. #[no_mangle] pub extern "C" fn z_memory_layout_drop(this_: &mut z_moved_memory_layout_t) { let _ = this_.take_rust_type(); } -/// @attention Unstable feature. +/// @warning This API has been marked as unstable: it works as advertised, but it may be changed in a future release. /// @brief Extract data from Memory Layout. #[no_mangle] pub extern "C" fn z_memory_layout_get_data( @@ -197,7 +197,7 @@ decl_c_type!( loaned(z_loaned_chunk_alloc_result_t), ); -/// @attention Unstable feature. +/// @warning This API has been marked as unstable: it works as advertised, but it may be changed in a future release. /// @brief Creates a new Chunk Alloc Result with Ok value. #[no_mangle] pub extern "C" fn z_chunk_alloc_result_new_ok( @@ -213,7 +213,7 @@ pub extern "C" fn z_chunk_alloc_result_new_ok( } } -/// @attention Unstable feature. +/// @warning This API has been marked as unstable: it works as advertised, but it may be changed in a future release. /// @brief Creates a new Chunk Alloc Result with Error value. #[no_mangle] pub extern "C" fn z_chunk_alloc_result_new_error( @@ -224,7 +224,7 @@ pub extern "C" fn z_chunk_alloc_result_new_error( .write(Some(Err(alloc_error.into()))); } -/// @attention Unstable feature. +/// @warning This API has been marked as unstable: it works as advertised, but it may be changed in a future release. /// @brief Constructs Chunk Alloc Result in its gravestone value. #[no_mangle] pub extern "C" fn z_internal_chunk_alloc_result_null( @@ -233,7 +233,7 @@ pub extern "C" fn z_internal_chunk_alloc_result_null( this_.as_rust_type_mut_uninit().write(None); } -/// @attention Unstable feature. +/// @warning This API has been marked as unstable: it works as advertised, but it may be changed in a future release. /// @return ``true`` if `this` is valid. #[no_mangle] pub extern "C" fn z_internal_chunk_alloc_result_check( @@ -242,7 +242,7 @@ pub extern "C" fn z_internal_chunk_alloc_result_check( this_.as_rust_type_ref().is_some() } -/// @attention Unstable feature. +/// @warning This API has been marked as unstable: it works as advertised, but it may be changed in a future release. /// @brief Borrows Chunk Alloc Result. #[no_mangle] #[allow(clippy::missing_safety_doc)] @@ -255,14 +255,14 @@ pub unsafe extern "C" fn z_chunk_alloc_result_loan( .as_loaned_c_type_ref() } -/// @attention Unstable feature. +/// @warning This API has been marked as unstable: it works as advertised, but it may be changed in a future release. /// @brief Deletes Chunk Alloc Result. #[no_mangle] pub extern "C" fn z_chunk_alloc_result_drop(this_: &mut z_moved_chunk_alloc_result_t) { let _ = this_.take_rust_type(); } -/// @attention Unstable feature. +/// @warning This API has been marked as unstable: it works as advertised, but it may be changed in a future release. /// @brief Status of SHM buffer allocation operation. #[repr(C)] #[derive(Clone, Copy, Debug)] @@ -273,7 +273,7 @@ pub enum zc_buf_alloc_status_t { ALLOC_ERROR = 1, } -/// @attention Unstable feature. +/// @warning This API has been marked as unstable: it works as advertised, but it may be changed in a future release. /// @brief A result of SHM buffer allocation operation. #[repr(C)] pub struct z_buf_alloc_result_t { @@ -308,7 +308,7 @@ impl From for z_buf_alloc_result_t { } } -/// @attention Unstable feature. +/// @warning This API has been marked as unstable: it works as advertised, but it may be changed in a future release. /// @brief Status of SHM buffer layouting + allocation operation. #[repr(C)] #[derive(Clone, Copy, Debug)] @@ -321,7 +321,7 @@ pub enum zc_buf_layout_alloc_status_t { LAYOUT_ERROR = 2, } -/// @attention Unstable feature. +/// @warning This API has been marked as unstable: it works as advertised, but it may be changed in a future release. /// @brief A result of SHM buffer layouting + allocation operation. #[repr(C)] pub struct z_buf_layout_alloc_result_t {