From dbcf741c72dc24948ecca976adb679dc5b26473f Mon Sep 17 00:00:00 2001 From: Denis Biryukov Date: Mon, 9 Sep 2024 18:30:57 +0200 Subject: [PATCH] add unstable tags to docs --- build-resources/opaque-types/src/lib.rs | 81 ++- docs/api.rst | 2 - include/zenoh_commons.h | 579 ++++++++++++------ src/closures/matching_status_closure.rs | 25 +- src/closures/zenohid_closure.rs | 26 +- src/commons.rs | 53 +- src/get.rs | 11 +- src/info.rs | 12 +- src/keyexpr.rs | 8 +- src/liveliness.rs | 42 +- src/payload.rs | 15 +- src/publication_cache.rs | 27 +- src/publisher.rs | 48 +- src/put.rs | 20 +- src/queryable.rs | 11 +- src/querying_subscriber.rs | 24 +- src/scouting.rs | 3 +- src/session.rs | 3 +- src/shm/buffer/zshm.rs | 32 +- src/shm/buffer/zshmmut.rs | 27 +- src/shm/client/shm_client.rs | 15 +- src/shm/client/shm_segment.rs | 6 +- src/shm/client_storage/mod.rs | 35 +- src/shm/common/types.rs | 11 +- .../posix/posix_shm_client.rs | 3 +- .../posix/posix_shm_provider.rs | 3 +- .../posix/protocol_id.rs | 3 +- src/shm/provider/alloc_layout.rs | 3 +- src/shm/provider/chunk.rs | 6 +- src/shm/provider/shm_provider.rs | 28 +- src/shm/provider/shm_provider_backend.rs | 3 +- src/shm/provider/types.rs | 69 ++- 32 files changed, 844 insertions(+), 390 deletions(-) diff --git a/build-resources/opaque-types/src/lib.rs b/build-resources/opaque-types/src/lib.rs index 549e7d573..d36e39fe3 100644 --- a/build-resources/opaque-types/src/lib.rs +++ b/build-resources/opaque-types/src/lib.rs @@ -131,7 +131,8 @@ 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")] -/// An owned Zenoh querying subscriber. +/// @attention Unstable feature. +/// @brief An owned Zenoh querying subscriber. /// /// In addition to receiving the data it is subscribed to, /// it also will fetch data from a Queryable at startup and peridodically (using `ze_querying_subscriber_get()`). @@ -140,7 +141,8 @@ get_opaque_type_data!( ze_owned_querying_subscriber_t ); #[cfg(feature = "unstable")] -/// A loaned Zenoh querying subscriber. +/// @attention Unstable feature. +/// @brief A loaned Zenoh querying subscriber. get_opaque_type_data!( (zenoh_ext::FetchingSubscriber<'static, ()>, &'static Session), ze_loaned_querying_subscriber_t @@ -188,7 +190,8 @@ get_opaque_type_data!(Option, z_owned_config_t); get_opaque_type_data!(Config, z_loaned_config_t); #[cfg(feature = "unstable")] -/// A Zenoh ID. +/// @attention Unstable feature. +/// @brief A Zenoh ID. /// /// In general, valid Zenoh IDs are LSB-first 128bit unsigned and non-zero integers. get_opaque_type_data!(ZenohId, z_id_t); @@ -204,7 +207,8 @@ get_opaque_type_data!(Option>, z_owned_publisher_t); get_opaque_type_data!(Publisher<'static>, z_loaned_publisher_t); #[cfg(feature = "unstable")] -/// An owned Zenoh matching listener. +/// @attention Unstable feature. +/// @brief An owned Zenoh matching listener. /// /// A listener that sends notifications when the [`MatchingStatus`] of a publisher changes. /// Dropping the corresponding publisher, also drops matching listener. @@ -222,7 +226,8 @@ get_opaque_type_data!(Option>, z_owned_subscriber_t); get_opaque_type_data!(Subscriber<'static, ()>, z_loaned_subscriber_t); #[cfg(feature = "unstable")] -/// A liveliness token that can be used to provide the network with information about connectivity to its +/// @attention Unstable feature. +/// @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. /// @@ -232,9 +237,11 @@ get_opaque_type_data!( zc_owned_liveliness_token_t ); #[cfg(feature = "unstable")] +/// @attention Unstable feature. get_opaque_type_data!(LivelinessToken<'static>, zc_loaned_liveliness_token_t); #[cfg(feature = "unstable")] -/// An owned Zenoh publication cache. +/// @attention Unstable feature. +/// @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 /// (for example by `ze_owned_querying_subscriber_t`). @@ -243,7 +250,8 @@ get_opaque_type_data!( ze_owned_publication_cache_t ); #[cfg(feature = "unstable")] -/// A loaned Zenoh publication cache. +/// @attention Unstable feature. +/// @brief A loaned Zenoh publication cache. get_opaque_type_data!( zenoh_ext::PublicationCache<'static>, ze_loaned_publication_cache_t @@ -276,54 +284,66 @@ 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"))] -/// An owned SHM Client +/// @attention Unstable feature. +/// @brief An owned SHM Client. get_opaque_type_data!(Option>, z_owned_shm_client_t); #[cfg(all(feature = "shared-memory", feature = "unstable"))] -/// An owned list of SHM Clients +/// @attention Unstable feature. +/// @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"))] -/// A loaned list of SHM Clients +/// @attention Unstable feature. +/// @brief A loaned list of SHM Clients. get_opaque_type_data!( Vec<(ProtocolID, Arc)>, zc_loaned_shm_client_list_t ); #[cfg(all(feature = "shared-memory", feature = "unstable"))] -/// An owned SHM Client Storage +/// @attention Unstable feature. +/// @brief An owned SHM Client Storage get_opaque_type_data!(Option>, z_owned_shm_client_storage_t); #[cfg(all(feature = "shared-memory", feature = "unstable"))] -/// A loaned SHM Client Storage +/// A loaned SHM Client Storage. get_opaque_type_data!(Arc, z_loaned_shm_client_storage_t); #[cfg(all(feature = "shared-memory", feature = "unstable"))] -/// An owned MemoryLayout +/// @attention Unstable feature. +/// @brief An owned MemoryLayout. get_opaque_type_data!(Option, z_owned_memory_layout_t); #[cfg(all(feature = "shared-memory", feature = "unstable"))] -/// A loaned MemoryLayout +/// @attention Unstable feature. +/// @brief A loaned MemoryLayout. get_opaque_type_data!(MemoryLayout, z_loaned_memory_layout_t); #[cfg(all(feature = "shared-memory", feature = "unstable"))] -/// An owned ChunkAllocResult +/// @attention Unstable feature. +/// @brief An owned ChunkAllocResult. get_opaque_type_data!(Option, z_owned_chunk_alloc_result_t); #[cfg(all(feature = "shared-memory", feature = "unstable"))] -/// A loaned ChunkAllocResult +/// @attention Unstable feature. +/// @brief A loaned ChunkAllocResult. get_opaque_type_data!(ChunkAllocResult, z_loaned_chunk_alloc_result_t); #[cfg(all(feature = "shared-memory", feature = "unstable"))] -/// An owned ZShm slice +/// @attention Unstable feature. +/// @brief An owned ZShm slice. get_opaque_type_data!(Option, z_owned_shm_t); #[cfg(all(feature = "shared-memory", feature = "unstable"))] -/// A loaned ZShm slice +/// @attention Unstable feature. +/// @brief A loaned ZShm slice. get_opaque_type_data!(zshm, z_loaned_shm_t); #[cfg(all(feature = "shared-memory", feature = "unstable"))] -/// An owned ZShmMut slice +/// @attention Unstable feature. +/// @brief An owned ZShmMut slice. get_opaque_type_data!(Option, z_owned_shm_mut_t); #[cfg(all(feature = "shared-memory", feature = "unstable"))] -/// A loaned ZShmMut slice +/// @attention Unstable feature. +/// @brief A loaned ZShmMut slice. get_opaque_type_data!(zshmmut, z_loaned_shm_mut_t); #[cfg(all(feature = "shared-memory", feature = "unstable"))] @@ -388,10 +408,12 @@ enum CDummySHMProvider { } #[cfg(all(feature = "shared-memory", feature = "unstable"))] -/// An owned ShmProvider +/// @attention Unstable feature. +/// @brief An owned ShmProvider. get_opaque_type_data!(Option, z_owned_shm_provider_t); #[cfg(all(feature = "shared-memory", feature = "unstable"))] -/// A loaned ShmProvider +/// @attention Unstable feature. +/// @brief A loaned ShmProvider. get_opaque_type_data!(CDummySHMProvider, z_loaned_shm_provider_t); #[cfg(all(feature = "shared-memory", feature = "unstable"))] @@ -408,10 +430,12 @@ enum CSHMLayout { } #[cfg(all(feature = "shared-memory", feature = "unstable"))] -/// An owned ShmProvider's AllocLayout +/// @attention Unstable feature. +/// @brief An owned ShmProvider's AllocLayout. get_opaque_type_data!(Option, z_owned_alloc_layout_t); #[cfg(all(feature = "shared-memory", feature = "unstable"))] -/// A loaned ShmProvider's AllocLayout +/// @attention Unstable feature. +/// @brief A loaned ShmProvider's AllocLayout. get_opaque_type_data!(CSHMLayout, z_loaned_alloc_layout_t); /// An owned Zenoh fifo sample handler. @@ -457,11 +481,14 @@ get_opaque_type_data!( get_opaque_type_data!(RingChannelHandler, z_loaned_ring_handler_reply_t); #[cfg(feature = "unstable")] -/// An owned Zenoh-allocated source info`. +/// @attention Unstable feature. +/// @brief An owned Zenoh-allocated source info`. get_opaque_type_data!(SourceInfo, z_owned_source_info_t); #[cfg(feature = "unstable")] -/// A loaned source info. +/// @attention Unstable feature. +/// @brief A loaned source info. get_opaque_type_data!(SourceInfo, z_loaned_source_info_t); #[cfg(feature = "unstable")] -/// An entity gloabal id. +/// @attention Unstable feature. +/// @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 197b41f0d..f50d7fa54 100644 --- a/docs/api.rst +++ b/docs/api.rst @@ -534,8 +534,6 @@ Functions .. doxygenfunction:: z_reliability_default -.. doxygenfunction:: zc_closure_matching_status_check -.. doxygenfunction:: zc_closure_matching_status_null .. doxygenfunction:: zc_closure_matching_status_drop .. doxygenfunction:: zc_closure_matching_status_call diff --git a/include/zenoh_commons.h b/include/zenoh_commons.h index 17d780e06..9c8ec9a13 100644 --- a/include/zenoh_commons.h +++ b/include/zenoh_commons.h @@ -17,21 +17,27 @@ #define ZENOHC_API #endif /** - * Allocation errors - * - * - **NEED_DEFRAGMENT**: defragmentation needed - * - **OUT_OF_MEMORY**: the provider is out of memory - * - **OTHER**: other error + * @attention Unstable feature. + * @brief Allocation errors */ #if (defined(SHARED_MEMORY) && defined(UNSTABLE)) typedef enum z_alloc_error_t { #if (defined(SHARED_MEMORY) && defined(UNSTABLE)) + /** + * Defragmentation needed. + */ Z_ALLOC_ERROR_NEED_DEFRAGMENT, #endif #if (defined(SHARED_MEMORY) && defined(UNSTABLE)) + /** + * The provider is out of memory. + */ Z_ALLOC_ERROR_OUT_OF_MEMORY, #endif #if (defined(SHARED_MEMORY) && defined(UNSTABLE)) + /** + * Other error. + */ Z_ALLOC_ERROR_OTHER, #endif } z_alloc_error_t; @@ -74,7 +80,8 @@ typedef enum z_consolidation_mode_t { Z_CONSOLIDATION_MODE_LATEST = 2, } z_consolidation_mode_t; /** - * Intersection level of 2 key expressions. + * @attention Unstable feature. + * @brief Intersection level of 2 key expressions. */ #if defined(UNSTABLE) typedef enum z_keyexpr_intersection_level_t { @@ -97,17 +104,21 @@ typedef enum z_keyexpr_intersection_level_t { } z_keyexpr_intersection_level_t; #endif /** - * Layouting errors - * - * INCORRECT_LAYOUT_ARGS: layout arguments are incorrect - * PROVIDER_INCOMPATIBLE_LAYOUT: layout incompatible with provider + * @attention Unstable feature. + * @brief Layouting errors */ #if (defined(SHARED_MEMORY) && defined(UNSTABLE)) typedef enum z_layout_error_t { #if (defined(SHARED_MEMORY) && defined(UNSTABLE)) + /** + * Layout arguments are incorrect. + */ Z_LAYOUT_ERROR_INCORRECT_LAYOUT_ARGS, #endif #if (defined(SHARED_MEMORY) && defined(UNSTABLE)) + /** + * Layout incompatible with provider. + */ Z_LAYOUT_ERROR_PROVIDER_INCOMPATIBLE_LAYOUT, #endif } z_layout_error_t; @@ -163,8 +174,9 @@ typedef enum z_query_target_t { Z_QUERY_TARGET_ALL_COMPLETE, } z_query_target_t; /** - * The publisher reliability. - * NOTE: Currently `reliability` does not trigger any data retransmission on the wire. + * @attention Unstable feature. + * @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). */ #if defined(UNSTABLE) @@ -204,7 +216,8 @@ typedef enum z_whatami_t { Z_WHATAMI_CLIENT = 4, } z_whatami_t; /** - * Status of SHM buffer allocation operation + * @attention Unstable feature. + * @brief Status of SHM buffer allocation operation. */ #if (defined(SHARED_MEMORY) && defined(UNSTABLE)) typedef enum zc_buf_alloc_status_t { @@ -223,7 +236,8 @@ typedef enum zc_buf_alloc_status_t { } zc_buf_alloc_status_t; #endif /** - * Status of SHM buffer layouting + allocation operation + * @attention Unstable feature. + * @brief Status of SHM buffer layouting + allocation operation. */ #if (defined(SHARED_MEMORY) && defined(UNSTABLE)) typedef enum zc_buf_layout_alloc_status_t { @@ -300,7 +314,8 @@ typedef enum zc_log_severity_t { ZC_LOG_SEVERITY_ERROR = 4, } zc_log_severity_t; /** - * Key expressions types to which Queryable should reply to. + * @attention Unstable feature. + * @brief Key expressions types to which Queryable should reply to. */ #if defined(UNSTABLE) typedef enum zc_reply_keyexpr_t { @@ -315,7 +330,8 @@ typedef enum zc_reply_keyexpr_t { } zc_reply_keyexpr_t; #endif /** - * A result of SHM buffer allocation operation + * @attention Unstable feature. + * @brief A result of SHM buffer allocation operation. */ #if (defined(SHARED_MEMORY) && defined(UNSTABLE)) typedef struct z_buf_alloc_result_t { @@ -326,7 +342,8 @@ typedef struct z_buf_alloc_result_t { #endif typedef int8_t z_result_t; /** - * An AllocAlignment. + * @attention Unstable feature. + * @brief An AllocAlignment. */ #if (defined(SHARED_MEMORY) && defined(UNSTABLE)) typedef struct z_alloc_alignment_t { @@ -375,19 +392,22 @@ typedef struct ALIGN(8) z_bytes_slice_iterator_t { uint8_t _0[24]; } z_bytes_slice_iterator_t; /** - * Unique segment identifier + * @attention Unstable feature. + * @brief Unique segment identifier. */ #if (defined(SHARED_MEMORY) && defined(UNSTABLE)) typedef uint32_t z_segment_id_t; #endif /** - * Chunk id within it's segment + * @attention Unstable feature. + * @brief Chunk id within it's segment. */ #if (defined(SHARED_MEMORY) && defined(UNSTABLE)) typedef uint32_t z_chunk_id_t; #endif /** - * A ChunkDescriptor + * @attention Unstable feature. + * @brief A ChunkDescriptor. */ #if (defined(SHARED_MEMORY) && defined(UNSTABLE)) typedef struct z_chunk_descriptor_t { @@ -397,7 +417,8 @@ typedef struct z_chunk_descriptor_t { } z_chunk_descriptor_t; #endif /** - * An AllocatedChunk + * @attention Unstable feature. + * @brief An AllocatedChunk. */ #if (defined(SHARED_MEMORY) && defined(UNSTABLE)) typedef struct z_allocated_chunk_t { @@ -537,7 +558,8 @@ typedef struct z_moved_closure_sample_t { struct z_owned_closure_sample_t _this; } z_moved_closure_sample_t; /** - * A closure is a structure that contains all the elements for stateful, memory-leak-free callbacks: + * @attention Unstable feature. + * @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. * @@ -563,7 +585,8 @@ typedef struct z_owned_closure_zid_t { } z_owned_closure_zid_t; #endif /** - * Moved closure. + * @attention Unstable feature. + * @brief Moved closure. */ #if defined(UNSTABLE) typedef struct z_moved_closure_zid_t { @@ -601,12 +624,16 @@ typedef struct z_publisher_options_t { bool is_express; #if defined(UNSTABLE) /** + * @attention Unstable feature. + * * The publisher reliability. */ enum z_reliability_t reliability; #endif #if defined(UNSTABLE) /** + * @attention Unstable feature. + * * The allowed destination for this publisher. */ enum zc_locality_t allowed_destination; @@ -652,12 +679,16 @@ typedef struct z_delete_options_t { struct z_timestamp_t *timestamp; #if defined(UNSTABLE) /** + * @attention Unstable feature. + * * The delete operation reliability. */ enum z_reliability_t reliability; #endif #if defined(UNSTABLE) /** + * @attention Unstable feature. + * * The allowed destination of this message. */ enum zc_locality_t allowed_destination; @@ -708,12 +739,16 @@ typedef struct z_get_options_t { bool is_express; #if defined(UNSTABLE) /** + * @attention Unstable feature. + * * The allowed destination for the query. */ enum zc_locality_t allowed_destination; #endif #if defined(UNSTABLE) /** + * @attention Unstable feature. + * * The accepted replies for the query. */ enum zc_reply_keyexpr_t accept_replies; @@ -724,6 +759,8 @@ typedef struct z_get_options_t { enum z_priority_t priority; #if defined(UNSTABLE) /** + * @attention Unstable feature. + * * The source info for the query. */ z_moved_source_info_t *source_info; @@ -773,6 +810,8 @@ typedef struct z_publisher_put_options_t { const struct z_timestamp_t *timestamp; #if defined(UNSTABLE) /** + * @attention Unstable feature. + * * The source info for the publication. */ z_moved_source_info_t *source_info; @@ -808,18 +847,24 @@ typedef struct z_put_options_t { struct z_timestamp_t *timestamp; #if defined(UNSTABLE) /** + * @attention Unstable feature. + * * The put operation reliability. */ enum z_reliability_t reliability; #endif #if defined(UNSTABLE) /** + * @attention Unstable feature. + * * The allowed destination of this message. */ enum zc_locality_t allowed_destination; #endif #if defined(UNSTABLE) /** + * @attention Unstable feature. + * * The source info for the message. */ z_moved_source_info_t *source_info; @@ -859,6 +904,8 @@ typedef struct z_query_reply_options_t { struct z_timestamp_t *timestamp; #if defined(UNSTABLE) /** + * @attention Unstable feature. + * * The source info for the reply. */ z_moved_source_info_t *source_info; @@ -891,6 +938,8 @@ typedef struct z_query_reply_del_options_t { struct z_timestamp_t *timestamp; #if defined(UNSTABLE) /** + * @attention Unstable feature. + * * The source info for the reply. */ z_moved_source_info_t *source_info; @@ -945,7 +994,8 @@ typedef struct z_scout_options_t { enum z_what_t what; } z_scout_options_t; /** - * A callbacks for ShmSegment + * @attention Unstable feature. + * @brief Callbacks for ShmSegment. */ #if (defined(SHARED_MEMORY) && defined(UNSTABLE)) typedef struct zc_shm_segment_callbacks_t { @@ -953,7 +1003,8 @@ typedef struct zc_shm_segment_callbacks_t { } zc_shm_segment_callbacks_t; #endif /** - * A ShmSegment + * @attention Unstable feature. + * @brief An ShmSegment. */ #if (defined(SHARED_MEMORY) && defined(UNSTABLE)) typedef struct z_shm_segment_t { @@ -962,7 +1013,8 @@ typedef struct z_shm_segment_t { } z_shm_segment_t; #endif /** - * A callbacks for ShmClient + * @attention Unstable feature. + * @brief Callback for ShmClient. */ #if (defined(SHARED_MEMORY) && defined(UNSTABLE)) typedef struct zc_shm_client_callbacks_t { @@ -970,7 +1022,8 @@ typedef struct zc_shm_client_callbacks_t { } zc_shm_client_callbacks_t; #endif /** - * A result of SHM buffer layouting + allocation operation + * @attention Unstable feature. + * @brief A result of SHM buffer layouting + allocation operation. */ #if (defined(SHARED_MEMORY) && defined(UNSTABLE)) typedef struct z_buf_layout_alloc_result_t { @@ -981,9 +1034,10 @@ typedef struct z_buf_layout_alloc_result_t { } z_buf_layout_alloc_result_t; #endif /** - * Unique protocol identifier. + * @attention Unstable feature. + * @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 + * and ShmProviderBackend implementations will never use the same ProtocolID. */ #if (defined(SHARED_MEMORY) && defined(UNSTABLE)) typedef uint32_t z_protocol_id_t; @@ -1015,7 +1069,8 @@ typedef struct zc_context_t { } zc_context_t; #endif /** - * A callbacks for ShmProviderBackend + * @attention Unstable feature. + * @brief Callbacks for ShmProviderBackend. */ #if (defined(SHARED_MEMORY) && defined(UNSTABLE)) typedef struct zc_shm_provider_backend_callbacks_t { @@ -1077,7 +1132,8 @@ typedef struct zc_moved_closure_log_t { struct zc_owned_closure_log_t _this; } zc_moved_closure_log_t; /** - * Loaned closure. + * @attention Unstable feature. + * @brief Loaned closure. */ #if defined(UNSTABLE) typedef struct zc_loaned_closure_matching_status_t { @@ -1085,7 +1141,8 @@ typedef struct zc_loaned_closure_matching_status_t { } zc_loaned_closure_matching_status_t; #endif /** - * A struct that indicates if there exist Subscribers matching the Publisher's key expression. + * @attention Unstable feature. + * @brief A struct that indicates if there exist Subscribers matching the Publisher's key expression. */ #if defined(UNSTABLE) typedef struct zc_matching_status_t { @@ -1096,7 +1153,8 @@ typedef struct zc_matching_status_t { } zc_matching_status_t; #endif /** - * A closure is a structure that contains all the elements for stateful, memory-leak-free callbacks: + * @attention Unstable feature. + * @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. * @@ -1122,7 +1180,8 @@ typedef struct zc_owned_closure_matching_status_t { } zc_owned_closure_matching_status_t; #endif /** - * Moved closure. + * @attention Unstable feature. + * @brief Moved closure. */ #if defined(UNSTABLE) typedef struct zc_moved_closure_matching_status_t { @@ -1130,7 +1189,8 @@ typedef struct zc_moved_closure_matching_status_t { } zc_moved_closure_matching_status_t; #endif /** - * The options for `zc_liveliness_declare_token()`. + * @attention Unstable feature. + * @brief The options for `zc_liveliness_declare_token()`. */ #if defined(UNSTABLE) typedef struct zc_liveliness_declaration_options_t { @@ -1138,7 +1198,8 @@ typedef struct zc_liveliness_declaration_options_t { } zc_liveliness_declaration_options_t; #endif /** - * The options for `zc_liveliness_declare_subscriber()` + * @attention Unstable feature. + * @brief The options for `zc_liveliness_declare_subscriber()` */ #if defined(UNSTABLE) typedef struct zc_liveliness_subscriber_options_t { @@ -1146,7 +1207,8 @@ typedef struct zc_liveliness_subscriber_options_t { } zc_liveliness_subscriber_options_t; #endif /** - * The options for `zc_liveliness_get()` + * @attention Unstable feature. + * @brief The options for `zc_liveliness_get()` */ #if defined(UNSTABLE) typedef struct zc_liveliness_get_options_t { @@ -1154,7 +1216,8 @@ typedef struct zc_liveliness_get_options_t { } zc_liveliness_get_options_t; #endif /** - * Options passed to the `ze_declare_publication_cache()` function. + * @attention Unstable feature. + * @brief Options passed to the `ze_declare_publication_cache()` function. */ #if defined(UNSTABLE) typedef struct ze_publication_cache_options_t { @@ -1183,7 +1246,8 @@ typedef struct ze_publication_cache_options_t { } ze_publication_cache_options_t; #endif /** - * A set of options that can be applied to a querying subscriber, + * @attention Unstable feature. + * @brief A set of options that can be applied to a querying subscriber, * upon its declaration via `ze_declare_querying_subscriber()`. * */ @@ -1277,7 +1341,8 @@ 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 /** - * Creates a new Alloc Layout for SHM Provider + * @attention Unstable feature. + * @brief Creates a new Alloc Layout for SHM Provider. */ #if (defined(SHARED_MEMORY) && defined(UNSTABLE)) ZENOHC_API @@ -1341,7 +1406,8 @@ ZENOHC_API z_result_t z_bytes_deserialize_into_int8(const struct z_loaned_bytes_t *this_, int8_t *dst); /** - * Deserializes data into a loaned SHM buffer + * @attention Unstable feature. + * @brief Deserializes data into a loaned SHM buffer. * * @param this_: Data to deserialize. * @param dst: An uninitialized memory location where to construct a deserialized SHM buffer. @@ -1352,7 +1418,8 @@ z_result_t z_bytes_deserialize_into_loaned_shm(const struct z_loaned_bytes_t *th const z_loaned_shm_t **dst); #endif /** - * Deserializes data into a mutably loaned SHM buffer + * @attention Unstable feature. + * @brief Deserializes data into a mutably loaned SHM buffer. * * @param this_: Data to deserialize. * @param dst: An uninitialized memory location where to construct a deserialized SHM buffer. @@ -1363,7 +1430,8 @@ z_result_t z_bytes_deserialize_into_mut_loaned_shm(struct z_loaned_bytes_t *this z_loaned_shm_t **dst); #endif /** - * Deserializes data into an owned SHM buffer by copying it's shared reference + * @attention Unstable feature. + * @brief Deserializes data into an owned SHM buffer by copying it's shared reference. * * @param this_: Data to deserialize. * @param dst: An uninitialized memory location where to construct a deserialized string. @@ -1633,13 +1701,15 @@ 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); /** - * Serializes from an immutable SHM buffer consuming it + * @attention Unstable feature. + * @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); #endif /** - * Serializes from a mutable SHM buffer consuming it + * @attention Unstable feature. + * @brief Serializes from a mutable SHM buffer consuming it. */ #if (defined(SHARED_MEMORY) && defined(UNSTABLE)) ZENOHC_API @@ -1718,20 +1788,23 @@ z_result_t z_bytes_writer_write_all(struct z_bytes_writer_t *this_, const uint8_t *src, size_t len); /** - * Deletes Chunk Alloc Result + * @attention Unstable feature. + * @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_); #endif /** - * Borrows Chunk Alloc Result + * @attention Unstable feature. + * @brief Borrows Chunk Alloc Result. */ #if (defined(SHARED_MEMORY) && defined(UNSTABLE)) ZENOHC_API const z_loaned_chunk_alloc_result_t *z_chunk_alloc_result_loan(const z_owned_chunk_alloc_result_t *this_); #endif /** - * Creates a new Chunk Alloc Result with Error value + * @attention Unstable feature. + * @brief Creates a new Chunk Alloc Result with Error value. */ #if (defined(SHARED_MEMORY) && defined(UNSTABLE)) ZENOHC_API @@ -1739,7 +1812,8 @@ void z_chunk_alloc_result_new_error(z_owned_chunk_alloc_result_t *this_, enum z_alloc_error_t alloc_error); #endif /** - * Creates a new Chunk Alloc Result with Ok value + * @attention Unstable feature. + * @brief Creates a new Chunk Alloc Result with Ok value. */ #if (defined(SHARED_MEMORY) && defined(UNSTABLE)) ZENOHC_API @@ -1832,7 +1906,8 @@ 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); /** - * Calls the closure. Calling an uninitialized closure is a no-op. + * @attention Unstable feature. + * @brief Calls the closure. Calling an uninitialized closure is a no-op. */ #if defined(UNSTABLE) ZENOHC_API @@ -1840,14 +1915,16 @@ void z_closure_zid_call(const struct z_loaned_closure_zid_t *closure, const z_id_t *z_id); #endif /** - * Drops the closure, resetting it to its gravestone state. Droping an uninitialized (null) closure is a no-op. + * @attention Unstable feature. + * @brief Drops the closure, resetting it to its gravestone state. Droping an uninitialized (null) closure is a no-op. */ #if defined(UNSTABLE) ZENOHC_API void z_closure_zid_drop(struct z_moved_closure_zid_t *closure_); #endif /** - * Vorrows closure. + * @attention Unstable feature. + * @brief Borrows closure. */ #if defined(UNSTABLE) ZENOHC_API @@ -2493,13 +2570,15 @@ 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); /** - * Returns the entity id of the entity global id. + * @attention Unstable feature. + * @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_); #endif /** - * Returns the zenoh id of entity global id. + * @attention Unstable feature. + * @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_); @@ -2645,19 +2724,22 @@ 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_); /** - * Returns id of Zenoh entity that transmitted hello message. + * @attention Unstable feature. + * @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_); #endif /** - * Formats the `z_id_t` into 16-digit hex string (LSB-first order) + * @attention Unstable feature. + * @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); #endif /** - * Fetches the Zenoh IDs of all connected peers. + * @attention Unstable feature. + * @brief Fetches the Zenoh IDs of all connected peers. * * `callback` will be called once for each ID, is guaranteed to never be called concurrently, * and is guaranteed to be dropped before this function exits. @@ -2670,7 +2752,8 @@ z_result_t z_info_peers_zid(const struct z_loaned_session_t *session, struct z_moved_closure_zid_t *callback); #endif /** - * Fetches the Zenoh IDs of all connected routers. + * @attention Unstable feature. + * @brief Fetches the Zenoh IDs of all connected routers. * * `callback` will be called once for each ID, is guaranteed to never be called concurrently, * and is guaranteed to be dropped before this function exits. @@ -2683,7 +2766,8 @@ z_result_t z_info_routers_zid(const struct z_loaned_session_t *session, struct z_moved_closure_zid_t *callback); #endif /** - * Returns the session's Zenoh ID. + * @attention Unstable feature. + * @brief Returns the session's Zenoh ID. * * Unless the `session` is invalid, that ID is guaranteed to be non-zero. * In other words, this function returning an array of 16 zeros means you failed @@ -2713,13 +2797,15 @@ 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_); /** - * Returns ``true`` if `this` is valid. + * @attention Unstable feature. + * @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_); #endif /** - * Constructs Chunk Alloc Result in its gravestone value. + * @attention Unstable feature. + * @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_); @@ -2757,13 +2843,15 @@ 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_); /** - * Returns ``true`` if closure is valid, ``false`` if it is in gravestone state. + * @attention Unstable feature. + * @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_); #endif /** - * Constructs a null closure. + * @attention Unstable feature. + * @brief Constructs a null closure. */ #if defined(UNSTABLE) ZENOHC_API void z_internal_closure_zid_null(struct z_owned_closure_zid_t *this_); @@ -2836,13 +2924,15 @@ 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_); /** - * Returns ``true`` if `this` is valid. + * @attention Unstable feature. + * @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_); #endif /** - * Constructs Memory Layout in its gravestone value. + * @attention Unstable feature. + * @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_); @@ -2939,61 +3029,71 @@ 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_); /** - * Returns ``true`` if `this` is valid. + * @attention Unstable feature. + * @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_); #endif /** - * Returns ``true`` if `this` is valid. + * @attention Unstable feature. + * @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_); #endif /** - * Constructs SHM client in its gravestone value. + * @attention Unstable feature. + * @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_); #endif /** - * Returns ``true`` if `this` is valid. + * @attention Unstable feature. + * @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_); #endif /** + * @attention Unstable feature. * 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_); #endif /** - * Returns ``true`` if `this` is valid. + * @attention Unstable feature. + * @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_); #endif /** - * Constructs ZShmMut slice in its gravestone value. + * @attention Unstable feature. + * @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_); #endif /** - * Constructs ZShm slice in its gravestone value. + * @attention Unstable feature. + * @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_); #endif /** - * Returns ``true`` if `this` is valid. + * @attention Unstable feature. + * @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_); #endif /** - * Constructs SHM Provider in its gravestone value. + * @attention Unstable feature. + * @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_); @@ -3007,13 +3107,15 @@ 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_); /** - * Returns ``true`` if source info is valid, ``false`` if it is in gravestone state. + * @attention Unstable feature. + * @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_); #endif /** - * Constructs source info in its gravestone state. + * @attention Unstable feature. + * @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_); @@ -3171,9 +3273,10 @@ 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_); /** - * Returns the relation between `left` and `right` from `left`'s point of view. + * @attention Unstable feature. + * @brief Returns the relation between `left` and `right` from `left`'s point of view. * - * Note that this is slower than `z_keyexpr_intersects` and `keyexpr_includes`, so you should favor these methods for most applications. + * @note This is slower than `z_keyexpr_intersects` and `keyexpr_includes`, so you should favor these methods for most applications. */ #if defined(UNSTABLE) ZENOHC_API @@ -3181,13 +3284,15 @@ enum z_keyexpr_intersection_level_t z_keyexpr_relation_to(const struct z_loaned_ const struct z_loaned_keyexpr_t *right); #endif /** - * Deletes Memory Layout + * @attention Unstable feature. + * @brief Deletes Memory Layout. */ #if (defined(SHARED_MEMORY) && defined(UNSTABLE)) ZENOHC_API void z_memory_layout_drop(z_moved_memory_layout_t *this_); #endif /** - * Extract data from Memory Layout + * @attention Unstable feature. + * @brief Extract data from Memory Layout. */ #if (defined(SHARED_MEMORY) && defined(UNSTABLE)) ZENOHC_API @@ -3196,14 +3301,16 @@ void z_memory_layout_get_data(size_t *out_size, const z_loaned_memory_layout_t *this_); #endif /** - * Borrows Memory Layout + * @attention Unstable feature. + * @brief Borrows Memory Layout. */ #if (defined(SHARED_MEMORY) && defined(UNSTABLE)) ZENOHC_API const z_loaned_memory_layout_t *z_memory_layout_loan(const z_owned_memory_layout_t *this_); #endif /** - * Creates a new Memory Layout + * @attention Unstable feature. + * @brief Creates a new Memory Layout. */ #if (defined(SHARED_MEMORY) && defined(UNSTABLE)) ZENOHC_API @@ -3249,7 +3356,8 @@ ZENOHC_API z_result_t z_open(struct z_owned_session_t *this_, struct z_moved_config_t *config); /** - * Constructs and opens a new Zenoh session with specified client storage. + * @attention Unstable feature. + * @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). */ @@ -3260,13 +3368,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 /** - * Creates a new POSIX SHM Client + * @attention Unstable feature. + * @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_); #endif /** - * Creates a new POSIX SHM Provider + * @attention Unstable feature. + * @brief Creates a new POSIX SHM Provider. */ #if (defined(SHARED_MEMORY) && defined(UNSTABLE)) ZENOHC_API @@ -3294,7 +3404,8 @@ 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_); /** - * Returns the ID of the publisher. + * @attention Unstable feature. + * @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); @@ -3513,7 +3624,8 @@ ZENOHC_API enum z_query_target_t z_query_target_default(void); */ ZENOHC_API void z_queryable_drop(struct z_moved_queryable_t *this_); /** - * Returns the ID of the queryable. + * @attention Unstable feature. + * @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); @@ -3544,11 +3656,15 @@ ZENOHC_API uint64_t z_random_u64(void); * Generates random `uint8_t`. */ ZENOHC_API uint8_t z_random_u8(void); +/** + * @attention Unstable feature. + */ #if (defined(SHARED_MEMORY) && defined(UNSTABLE)) ZENOHC_API void z_ref_shm_client_storage_global(z_owned_shm_client_storage_t *this_); #endif /** - * Returns the default value for `reliability`. + * @attention Unstable feature. + * @brief Returns the default value for `reliability`. */ #if defined(UNSTABLE) ZENOHC_API enum z_reliability_t z_reliability_default(void); @@ -3602,8 +3718,9 @@ 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_); /** - * Gets the id of the zenoh instance that answered this Reply. - * Returns `true` if id is present. + * @attention Unstable feature. + * @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); @@ -3756,13 +3873,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_); /** - * Returns the reliability setting the sample was delieverd with. + * @attention Unstable feature. + * @brief Returns the reliability setting the sample was delieverd with. */ #if defined(UNSTABLE) ZENOHC_API enum z_reliability_t z_sample_reliability(const struct z_loaned_sample_t *this_); #endif /** - * Returns the sample source_info. + * @attention Unstable feature. + * @brief Returns the sample source_info. */ #if defined(UNSTABLE) ZENOHC_API @@ -3808,13 +3927,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_); /** - * Deletes SHM Client + * @attention Unstable feature. + * @brief Deletes SHM Client. */ #if (defined(SHARED_MEMORY) && defined(UNSTABLE)) ZENOHC_API void z_shm_client_drop(z_moved_shm_client_t *this_); #endif /** - * Creates a new SHM Client + * @attention Unstable feature. + * @brief Creates a new SHM Client. */ #if (defined(SHARED_MEMORY) && defined(UNSTABLE)) ZENOHC_API @@ -3823,7 +3944,8 @@ void z_shm_client_new(z_owned_shm_client_t *this_, struct zc_shm_client_callbacks_t callbacks); #endif /** - * Performs a shallow copy of SHM Client Storage + * @attention Unstable feature. + * @brief Performs a shallow copy of SHM Client Storage. */ #if (defined(SHARED_MEMORY) && defined(UNSTABLE)) ZENOHC_API @@ -3831,111 +3953,137 @@ void z_shm_client_storage_clone(z_owned_shm_client_storage_t *this_, const z_loaned_shm_client_storage_t *from); #endif /** - * Derefs SHM Client Storage + * @attention Unstable feature. + * @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_); #endif /** - * Borrows SHM Client Storage + * @attention Unstable feature. + * @brief Borrows SHM Client Storage. */ #if (defined(SHARED_MEMORY) && defined(UNSTABLE)) 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. + */ #if (defined(SHARED_MEMORY) && defined(UNSTABLE)) ZENOHC_API z_result_t z_shm_client_storage_new(z_owned_shm_client_storage_t *this_, const zc_loaned_shm_client_list_t *clients, bool add_default_client_set); #endif +/** + * @attention Unstable feature. + */ #if (defined(SHARED_MEMORY) && defined(UNSTABLE)) ZENOHC_API void z_shm_client_storage_new_default(z_owned_shm_client_storage_t *this_); #endif /** - * Converts borrowed ZShm slice to owned ZShm slice by performing a shallow SHM reference copy + * @attention Unstable feature. + * @brief Converts borrowed ZShm slice to owned ZShm slice by performing a shallow SHM reference copy. */ #if (defined(SHARED_MEMORY) && defined(UNSTABLE)) -ZENOHC_API void z_shm_clone(z_owned_shm_t *out, const z_loaned_shm_t *this_); +ZENOHC_API +void z_shm_clone(z_owned_shm_t *out, + const z_loaned_shm_t *this_); #endif /** - * @return the pointer of the ZShm slice + * @attention Unstable feature. + * @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_); #endif /** - * Deletes ZShm slice + * @attention Unstable feature. + * @brief Deletes ZShm slice. */ #if (defined(SHARED_MEMORY) && defined(UNSTABLE)) ZENOHC_API void z_shm_drop(z_moved_shm_t *this_); #endif /** - * Constructs ZShm slice from ZShmMut slice + * @attention Unstable feature. + * @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); #endif /** - * @return the length of the ZShm slice + * @attention Unstable feature. + * @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_); #endif /** - * Borrows ZShm slice + * @attention Unstable feature. + * @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_); #endif /** - * Mutably borrows ZShm slice + * @brief Mutably borrows ZShm slice. */ #if (defined(SHARED_MEMORY) && defined(UNSTABLE)) ZENOHC_API z_loaned_shm_t *z_shm_loan_mut(z_owned_shm_t *this_); #endif /** - * @return the immutable pointer to the underlying data + * @attention Unstable feature. + * @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_); #endif /** - * @return the mutable pointer to the underlying data + * @attention Unstable feature. + * @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_); #endif /** - * Deletes ZShmMut slice + * @attention Unstable feature. + * @brief Deletes ZShmMut slice. */ #if (defined(SHARED_MEMORY) && defined(UNSTABLE)) ZENOHC_API void z_shm_mut_drop(z_moved_shm_mut_t *this_); #endif /** - * @return the length of the ZShmMut slice + * @attention Unstable feature. + * @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_); #endif /** - * Borrows ZShmMut slice + * @attention Unstable feature. + * @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_); #endif /** - * Mutably borrows ZShmMut slice + * @attention Unstable feature. + * @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_); #endif /** - * Tries to construct ZShmMut slice from ZShm slice + * @attention Unstable feature. + * @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); #endif +/** + * @attention Unstable feature. + */ #if (defined(SHARED_MEMORY) && defined(UNSTABLE)) ZENOHC_API void z_shm_provider_alloc(struct z_buf_layout_alloc_result_t *out_result, @@ -3943,6 +4091,9 @@ void z_shm_provider_alloc(struct z_buf_layout_alloc_result_t *out_result, size_t size, struct z_alloc_alignment_t alignment); #endif +/** + * @attention Unstable feature. + */ #if (defined(SHARED_MEMORY) && defined(UNSTABLE)) ZENOHC_API void z_shm_provider_alloc_gc(struct z_buf_layout_alloc_result_t *out_result, @@ -3950,6 +4101,9 @@ void z_shm_provider_alloc_gc(struct z_buf_layout_alloc_result_t *out_result, size_t size, struct z_alloc_alignment_t alignment); #endif +/** + * @attention Unstable feature. + */ #if (defined(SHARED_MEMORY) && defined(UNSTABLE)) ZENOHC_API void z_shm_provider_alloc_gc_defrag(struct z_buf_layout_alloc_result_t *out_result, @@ -3957,6 +4111,9 @@ void z_shm_provider_alloc_gc_defrag(struct z_buf_layout_alloc_result_t *out_resu size_t size, struct z_alloc_alignment_t alignment); #endif +/** + * @attention Unstable feature. + */ #if (defined(SHARED_MEMORY) && defined(UNSTABLE)) ZENOHC_API z_result_t z_shm_provider_alloc_gc_defrag_async(struct z_buf_layout_alloc_result_t *out_result, @@ -3967,6 +4124,9 @@ z_result_t z_shm_provider_alloc_gc_defrag_async(struct z_buf_layout_alloc_result void (*result_callback)(void*, struct z_buf_layout_alloc_result_t*)); #endif +/** + * @attention Unstable feature. + */ #if (defined(SHARED_MEMORY) && defined(UNSTABLE)) ZENOHC_API void z_shm_provider_alloc_gc_defrag_blocking(struct z_buf_layout_alloc_result_t *out_result, @@ -3974,6 +4134,9 @@ void z_shm_provider_alloc_gc_defrag_blocking(struct z_buf_layout_alloc_result_t size_t size, struct z_alloc_alignment_t alignment); #endif +/** + * @attention Unstable feature. + */ #if (defined(SHARED_MEMORY) && defined(UNSTABLE)) ZENOHC_API void z_shm_provider_alloc_gc_defrag_dealloc(struct z_buf_layout_alloc_result_t *out_result, @@ -3981,27 +4144,41 @@ void z_shm_provider_alloc_gc_defrag_dealloc(struct z_buf_layout_alloc_result_t * size_t size, struct z_alloc_alignment_t alignment); #endif +/** + * @attention Unstable feature. + */ #if (defined(SHARED_MEMORY) && defined(UNSTABLE)) ZENOHC_API size_t z_shm_provider_available(const z_loaned_shm_provider_t *provider); #endif +/** + * @attention Unstable feature. + */ #if (defined(SHARED_MEMORY) && defined(UNSTABLE)) ZENOHC_API size_t z_shm_provider_defragment(const z_loaned_shm_provider_t *provider); #endif /** - * Deletes SHM Provider + * @attention Unstable feature. + * @brief Deletes SHM Provider. */ #if (defined(SHARED_MEMORY) && defined(UNSTABLE)) ZENOHC_API void z_shm_provider_drop(z_moved_shm_provider_t *this_); #endif +/** + * @attention Unstable feature. + */ #if (defined(SHARED_MEMORY) && defined(UNSTABLE)) ZENOHC_API size_t z_shm_provider_garbage_collect(const z_loaned_shm_provider_t *provider); #endif /** - * Borrows SHM Provider + * @attention Unstable feature. + * @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_); #endif +/** + * @attention Unstable feature. + */ #if (defined(SHARED_MEMORY) && defined(UNSTABLE)) ZENOHC_API z_result_t z_shm_provider_map(z_owned_shm_mut_t *out_result, @@ -4010,7 +4187,8 @@ z_result_t z_shm_provider_map(z_owned_shm_mut_t *out_result, size_t len); #endif /** - * Creates a new SHM Provider + * @attention Unstable feature. + * @brief Creates a new SHM Provider. */ #if (defined(SHARED_MEMORY) && defined(UNSTABLE)) ZENOHC_API @@ -4020,7 +4198,8 @@ void z_shm_provider_new(z_owned_shm_provider_t *this_, struct zc_shm_provider_backend_callbacks_t callbacks); #endif /** - * Creates a new threadsafe SHM Provider + * @attention Unstable feature. + * @brief Creates a new threadsafe SHM Provider. */ #if (defined(SHARED_MEMORY) && defined(UNSTABLE)) ZENOHC_API @@ -4030,13 +4209,15 @@ void z_shm_provider_threadsafe_new(z_owned_shm_provider_t *this_, struct zc_shm_provider_backend_callbacks_t callbacks); #endif /** - * Mutably borrows ZShm slice as borrowed ZShmMut slice + * @attention Unstable feature. + * @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_); #endif /** - * Tries to reborrow mutably-borrowed ZShm slice as borrowed ZShmMut slice + * @attention Unstable feature. + * @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_); @@ -4107,25 +4288,29 @@ 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_); /** - * Frees the memory and invalidates the source info, resetting it to a gravestone state. + * @attention Unstable feature. + * @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_); #endif /** - * Returns the source_id of the source info. + * @attention Unstable feature. + * @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_); #endif /** - * Borrows source info. + * @attention Unstable feature. + * @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_); #endif /** - * Create source info + * @attention Unstable feature. + * @brief Creates source info. */ #if defined(UNSTABLE) ZENOHC_API @@ -4134,7 +4319,8 @@ z_result_t z_source_info_new(z_owned_source_info_t *this_, uint64_t source_sn); #endif /** - * Returns the source_sn of the source info. + * @attention Unstable feature. + * @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_); @@ -4318,7 +4504,8 @@ ZENOHC_API const char *z_time_now_as_str(const char *buf, size_t len); /** - * Returns id associated with this timestamp. + * @attention Unstable feature. + * @brief Returns id associated with this timestamp. */ #if defined(UNSTABLE) ZENOHC_API z_id_t z_timestamp_id(const struct z_timestamp_t *this_); @@ -4342,7 +4529,7 @@ ZENOHC_API z_result_t z_undeclare_keyexpr(struct z_moved_keyexpr_t *this_, const struct z_loaned_session_t *session); /** - * Undeclares the given publisher, droping and invalidating it. + * @brief Undeclares the given publisher, droping and invalidating it. * * @return 0 in case of success, negative error code otherwise. */ @@ -4526,7 +4713,8 @@ 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); /** - * Calls the closure. Calling an uninitialized closure is a no-op. + * @attention Unstable feature. + * @brief Calls the closure. Calling an uninitialized closure is a no-op. */ #if defined(UNSTABLE) ZENOHC_API @@ -4534,14 +4722,16 @@ void zc_closure_matching_status_call(const struct zc_loaned_closure_matching_sta const struct zc_matching_status_t *mathing_status); #endif /** - * Drops the closure, resetting it to its gravestone state. Droping an uninitialized closure is a no-op. + * @attention Unstable feature. + * @brief Drops the closure, resetting it to its gravestone state. Droping an uninitialized closure is a no-op. */ #if defined(UNSTABLE) ZENOHC_API void zc_closure_matching_status_drop(struct zc_moved_closure_matching_status_t *closure_); #endif /** - * Borrows closure. + * @attention Unstable feature. + * @brief Borrows closure. */ #if defined(UNSTABLE) ZENOHC_API @@ -4638,64 +4828,74 @@ 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_); /** - * Returns ``true`` if closure is valid, ``false`` if it is in gravestone state. + * @attention Unstable feature. + * @brief Returns ``true`` if closure is valid, ``false`` if it is in gravestone state. */ #if defined(UNSTABLE) ZENOHC_API bool zc_internal_closure_matching_status_check(const struct zc_owned_closure_matching_status_t *this_); #endif /** - * Constructs a null value of 'zc_owned_closure_matching_status_t' type + * @attention Unstable feature. + * @brief Constructs a null value of 'zc_owned_closure_matching_status_t' type */ #if defined(UNSTABLE) ZENOHC_API void zc_internal_closure_matching_status_null(struct zc_owned_closure_matching_status_t *this_); #endif /** - * Returns ``true`` if liveliness token is valid, ``false`` otherwise. + * @attention Unstable feature. + * @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_); #endif /** - * Constructs liveliness token in its gravestone state. + * @attention Unstable feature. + * @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_); #endif /** - * Checks the matching listener is for the gravestone state + * @attention Unstable feature. + * @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_); #endif /** - * Constructs an empty matching listener + * @attention Unstable feature. + * @brief Constructs an empty matching listener. */ #if defined(UNSTABLE) ZENOHC_API void zc_internal_matching_listener_null(zc_owned_matching_listener_t *this_); #endif /** - * Returns ``true`` if `this` is valid. + * @attention Unstable feature. + * @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_); #endif /** - * Constructs SHM client list in its gravestone value. + * @attention Unstable feature. + * @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_); #endif /** - * Constructs default value for `zc_liveliness_declaration_options_t`. + * @attention Unstable feature. + * @brief Constructs default value for `zc_liveliness_declaration_options_t`. */ #if defined(UNSTABLE) ZENOHC_API void zc_liveliness_declaration_options_default(struct zc_liveliness_declaration_options_t *this_); #endif /** - * Declares a subscriber on liveliness tokens that intersect `key_expr`. + * @attention Unstable feature. + * @brief Declares a subscriber on liveliness tokens that intersect `key_expr`. * * @param this_: An uninitialized memory location where subscriber will be constructed. * @param session: The Zenoh session. @@ -4714,7 +4914,8 @@ z_result_t zc_liveliness_declare_subscriber(struct z_owned_subscriber_t *this_, struct zc_liveliness_subscriber_options_t *_options); #endif /** - * Constructs and declares a liveliness token on the network. + * @attention Unstable feature. + * @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 * is achieved, and a DELETE sample if it's lost. @@ -4732,7 +4933,8 @@ z_result_t zc_liveliness_declare_token(zc_owned_liveliness_token_t *this_, const struct zc_liveliness_declaration_options_t *_options); #endif /** - * Queries liveliness tokens currently on the network with a key expression intersecting with `key_expr`. + * @attention Unstable feature. + * @brief Queries liveliness tokens currently on the network with a key expression intersecting with `key_expr`. * * @param session: The Zenoh session. * @param key_expr: The key expression to query liveliness tokens for. @@ -4747,45 +4949,52 @@ z_result_t zc_liveliness_get(const struct z_loaned_session_t *session, struct zc_liveliness_get_options_t *options); #endif /** - * Constructs default value `zc_liveliness_get_options_t`. + * @attention Unstable feature. + * @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_); #endif /** - * Constucts default value for `zc_liveliness_declare_subscriber_options_t`. + * @attention Unstable feature. + * @brief Constucts default value for `zc_liveliness_declare_subscriber_options_t`. */ #if defined(UNSTABLE) ZENOHC_API void zc_liveliness_subscriber_options_default(struct zc_liveliness_subscriber_options_t *this_); #endif /** - * Undeclares liveliness token, frees memory and resets it to a gravestone state. + * @attention Unstable feature. + * @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_); #endif /** - * Borrows token. + * @attention Unstable feature. + * @brief Borrows token. */ #if defined(UNSTABLE) ZENOHC_API const zc_loaned_liveliness_token_t *zc_liveliness_token_loan(const zc_owned_liveliness_token_t *this_); #endif /** - * Destroys a liveliness token, notifying subscribers of its destruction. + * @attention Unstable feature. + * @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_); #endif /** - * Returns default value of `zc_locality_t` + * @attention Unstable feature. + * @brief Returns default value of `zc_locality_t` */ #if defined(UNSTABLE) ZENOHC_API enum zc_locality_t zc_locality_default(void); #endif /** - * Gets publisher matching status - i.e. if there are any subscribers matching its key expression. + * @attention Unstable feature. + * @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). */ @@ -4795,7 +5004,8 @@ z_result_t zc_publisher_get_matching_status(const struct z_loaned_publisher_t *t struct zc_matching_status_t *matching_status); #endif /** - * Constructs matching listener, registering a callback for notifying subscribers matching with a given publisher. + * @attention Unstable feature. + * @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. * @param publisher: A publisher to associate with matching listener. @@ -4810,15 +5020,15 @@ z_result_t zc_publisher_matching_listener_declare(zc_owned_matching_listener_t * struct zc_moved_closure_matching_status_t *callback); #endif /** - * Undeclares the given matching listener, droping and invalidating it. - * - * @return 0 in case of success, negative error code otherwise. + * @attention Unstable feature. + * @brief Undeclares the given matching listener, droping and invalidating it. */ #if defined(UNSTABLE) -ZENOHC_API z_result_t 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 /** - * Undeclares the given matching listener, droping and invalidating it. + * @attention Unstable feature. + * @brief Undeclares the given matching listener, droping and invalidating it. * * @return 0 in case of success, negative error code otherwise. */ @@ -4826,11 +5036,15 @@ ZENOHC_API z_result_t zc_publisher_matching_listener_drop(zc_moved_matching_list ZENOHC_API z_result_t zc_publisher_matching_listener_undeclare(zc_moved_matching_listener_t *this_); #endif /** - * Returns the default value of #zc_reply_keyexpr_t. + * @attention Unstable feature. + * @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); #endif +/** + * @attention Unstable feature. + */ #if (defined(SHARED_MEMORY) && defined(UNSTABLE)) ZENOHC_API z_result_t zc_shm_client_list_add_client(z_protocol_id_t id, @@ -4838,27 +5052,31 @@ z_result_t zc_shm_client_list_add_client(z_protocol_id_t id, zc_loaned_shm_client_list_t *list); #endif /** - * Deletes list of SHM Clients + * @attention Unstable feature. + * @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_); #endif /** - * Borrows list of SHM Clients + * @attention Unstable feature. + * @brief Borrows list of SHM Clients. */ #if (defined(SHARED_MEMORY) && defined(UNSTABLE)) ZENOHC_API const zc_loaned_shm_client_list_t *zc_shm_client_list_loan(const zc_owned_shm_client_list_t *this_); #endif /** - * Mutably borrows list of SHM Clients + * @attention Unstable feature. + * @brief Mutably borrows list of SHM Clients. */ #if (defined(SHARED_MEMORY) && defined(UNSTABLE)) ZENOHC_API zc_loaned_shm_client_list_t *zc_shm_client_list_loan_mut(zc_owned_shm_client_list_t *this_); #endif /** - * Creates a new empty list of SHM Clients + * @attention Unstable feature. + * @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_); @@ -4872,7 +5090,8 @@ ZENOHC_API void zc_shm_client_list_new(zc_owned_shm_client_list_t *this_); ZENOHC_API void zc_stop_z_runtime(void); /** - * Constructs and declares a publication cache. + * @attention Unstable feature. + * @brief Constructs and declares a publication cache. * * @param this_: An uninitialized location in memory where publication cache will be constructed. * @param session: A Zenoh session. @@ -4889,7 +5108,8 @@ z_result_t ze_declare_publication_cache(ze_owned_publication_cache_t *this_, struct ze_publication_cache_options_t *options); #endif /** - * Constructs and declares a querying subscriber for a given key expression. + * @attention Unstable feature. + * @brief Constructs and declares a querying subscriber for a given key expression. * * @param this_: An uninitialized memory location where querying subscriber will be constructed. * @param session: A Zenoh session. @@ -4908,19 +5128,22 @@ z_result_t ze_declare_querying_subscriber(ze_owned_querying_subscriber_t *this_, struct ze_querying_subscriber_options_t *options); #endif /** - * Returns ``true`` if publication cache is valid, ``false`` otherwise. + * @attention Unstable feature. + * @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_); #endif /** - * Constructs a publication cache in a gravestone state. + * @attention Unstable feature. + * @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_); #endif /** - * Returns ``true`` if querying subscriber is valid, ``false`` otherwise. + * @attention Unstable feature. + * @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_); @@ -4932,39 +5155,45 @@ 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 /** - * Drops publication cache and resets it to its gravestone state. + * @attention Unstable feature. + * @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_); #endif /** - * Returns the key expression of the publication cache. + * @attention Unstable feature. + * @brief Returns the key expression of the publication cache. */ #if defined(UNSTABLE) ZENOHC_API const struct z_loaned_keyexpr_t *ze_publication_cache_keyexpr(const ze_loaned_publication_cache_t *this_); #endif /** - * Borrows querying subscriber. + * @attention Unstable feature. + * @brief Borrows querying subscriber. */ #if defined(UNSTABLE) ZENOHC_API const ze_loaned_publication_cache_t *ze_publication_cache_loan(const ze_owned_publication_cache_t *this_); #endif /** - * Constructs the default value for `ze_publication_cache_options_t`. + * @attention Unstable feature. + * @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_); #endif /** - * Drops querying subscriber. + * @attention Unstable feature. + * @brief Drops querying subscriber. */ #if defined(UNSTABLE) ZENOHC_API void ze_querying_subscriber_drop(ze_moved_querying_subscriber_t *this_); #endif /** - * Make querying subscriber perform an additional query on a specified selector. + * @attention Unstable feature. + * @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. */ @@ -4975,28 +5204,32 @@ z_result_t ze_querying_subscriber_get(const ze_loaned_querying_subscriber_t *thi struct z_get_options_t *options); #endif /** - * Borrows querying subscriber. + * @attention Unstable feature. + * @brief Borrows querying subscriber. */ #if defined(UNSTABLE) ZENOHC_API const ze_loaned_querying_subscriber_t *ze_querying_subscriber_loan(const ze_owned_querying_subscriber_t *this_); #endif /** - * Constructs the default value for `ze_querying_subscriber_options_t`. + * @attention Unstable feature. + * @brief Constructs the default value for `ze_querying_subscriber_options_t`. */ #if defined(UNSTABLE) ZENOHC_API void ze_querying_subscriber_options_default(struct ze_querying_subscriber_options_t *this_); #endif /** - * Undeclares and drops publication cache. + * @attention Unstable feature. + * @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_); #endif /** - * Undeclares the given querying subscriber, drops it and resets to a gravestone state. + * @attention Unstable feature. + * @brief Undeclares the given querying subscriber, drops it and resets to a gravestone state. * * @return 0 in case of success, negative error code otherwise. */ diff --git a/src/closures/matching_status_closure.rs b/src/closures/matching_status_closure.rs index 0597651f1..110b827dc 100644 --- a/src/closures/matching_status_closure.rs +++ b/src/closures/matching_status_closure.rs @@ -19,7 +19,8 @@ use crate::{ transmute::{LoanedCTypeRef, OwnedCTypeRef, TakeRustType}, zc_matching_status_t, }; -/// A closure is a structure that contains all the elements for stateful, memory-leak-free callbacks: +/// @attention Unstable feature. +/// @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. /// @@ -37,13 +38,15 @@ pub struct zc_owned_closure_matching_status_t { drop: Option, } -/// Loaned closure. +/// @attention Unstable feature. +/// @brief Loaned closure. #[repr(C)] pub struct zc_loaned_closure_matching_status_t { _0: [usize; 3], } -/// Moved closure. +/// @attention Unstable feature. +/// @brief Moved closure. #[repr(C)] pub struct zc_moved_closure_matching_status_t { _this: zc_owned_closure_matching_status_t, @@ -79,7 +82,8 @@ impl Drop for zc_owned_closure_matching_status_t { } } } -/// Constructs a null value of 'zc_owned_closure_matching_status_t' type +/// @attention Unstable feature. +/// @brief Constructs a null value of 'zc_owned_closure_matching_status_t' type #[no_mangle] #[allow(clippy::missing_safety_doc)] pub unsafe extern "C" fn zc_internal_closure_matching_status_null( @@ -88,7 +92,8 @@ pub unsafe extern "C" fn zc_internal_closure_matching_status_null( (*this).write(zc_owned_closure_matching_status_t::default()); } -/// Returns ``true`` if closure is valid, ``false`` if it is in gravestone state. +/// @attention Unstable feature. +/// @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( this: &zc_owned_closure_matching_status_t, @@ -96,7 +101,8 @@ pub extern "C" fn zc_internal_closure_matching_status_check( !this.is_empty() } -/// Calls the closure. Calling an uninitialized closure is a no-op. +/// @attention Unstable feature. +/// @brief Calls the closure. Calling an uninitialized closure is a no-op. #[no_mangle] pub extern "C" fn zc_closure_matching_status_call( closure: &zc_loaned_closure_matching_status_t, @@ -110,7 +116,9 @@ pub extern "C" fn zc_closure_matching_status_call( } } } -/// Drops the closure, resetting it to its gravestone state. Droping an uninitialized closure is a no-op. + +/// @attention Unstable feature. +/// @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( closure_: &mut zc_moved_closure_matching_status_t, @@ -139,7 +147,8 @@ impl From for zc_owned_closure_matching_status_ } } -/// Borrows closure. +/// @attention Unstable feature. +/// @brief Borrows closure. #[no_mangle] pub extern "C" fn zc_closure_matching_status_loan( closure: &zc_owned_closure_matching_status_t, diff --git a/src/closures/zenohid_closure.rs b/src/closures/zenohid_closure.rs index 6447515aa..04e3a3cc2 100644 --- a/src/closures/zenohid_closure.rs +++ b/src/closures/zenohid_closure.rs @@ -20,7 +20,8 @@ use crate::{ transmute::{LoanedCTypeRef, OwnedCTypeRef, TakeRustType}, z_id_t, }; -/// A closure is a structure that contains all the elements for stateful, memory-leak-free callbacks: +/// @attention Unstable feature. +/// @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,13 +39,15 @@ pub struct z_owned_closure_zid_t { drop: Option, } -/// Loaned closure. +/// @attention Unstable feature. +/// @brief Loaned closure. #[repr(C)] pub struct z_loaned_closure_zid_t { _0: [usize; 3], } -/// Moved closure. +/// @attention Unstable feature. +/// @brief Moved closure. #[repr(C)] pub struct z_moved_closure_zid_t { pub _this: z_owned_closure_zid_t, @@ -81,14 +84,16 @@ impl Drop for z_owned_closure_zid_t { } } -/// Returns ``true`` if closure is valid, ``false`` if it is in gravestone state. +/// @attention Unstable feature. +/// @brief Returns ``true`` if closure is valid, ``false`` if it is in gravestone state. #[no_mangle] #[allow(clippy::missing_safety_doc)] pub unsafe extern "C" fn z_internal_closure_zid_check(this_: &z_owned_closure_zid_t) -> bool { !this_.is_empty() } -/// Constructs a null closure. +/// @attention Unstable feature. +/// @brief Constructs a null closure. #[no_mangle] #[allow(clippy::missing_safety_doc)] pub unsafe extern "C" fn z_internal_closure_zid_null( @@ -96,7 +101,9 @@ pub unsafe extern "C" fn z_internal_closure_zid_null( ) { this_.write(z_owned_closure_zid_t::default()); } -/// Calls the closure. Calling an uninitialized closure is a no-op. + +/// @attention Unstable feature. +/// @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) { let closure = closure.as_owned_c_type_ref(); @@ -107,7 +114,9 @@ pub extern "C" fn z_closure_zid_call(closure: &z_loaned_closure_zid_t, z_id: &z_ } } } -/// Drops the closure, resetting it to its gravestone state. Droping an uninitialized (null) closure is a no-op. + +/// @attention Unstable feature. +/// @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) { let _ = closure_.take_rust_type(); @@ -131,7 +140,8 @@ impl From for z_owned_closure_zid_t { } } -/// Vorrows closure. +/// @attention Unstable feature. +/// @brief Borrows closure. #[no_mangle] pub extern "C" fn z_closure_zid_loan(closure: &z_owned_closure_zid_t) -> &z_loaned_closure_zid_t { closure.as_loaned_c_type_ref() diff --git a/src/commons.rs b/src/commons.rs index a148ad7b1..5d855dd82 100644 --- a/src/commons.rs +++ b/src/commons.rs @@ -93,7 +93,8 @@ pub extern "C" fn z_timestamp_ntp64_time(this_: &z_timestamp_t) -> u64 { } #[cfg(feature = "unstable")] -/// Returns id associated with this timestamp. +/// @attention Unstable feature. +/// @brief Returns id associated with this timestamp. #[no_mangle] pub extern "C" fn z_timestamp_id(this_: &z_timestamp_t) -> z_id_t { this_.as_rust_type_ref().get_id().to_le_bytes().into() @@ -150,7 +151,8 @@ pub extern "C" fn z_sample_attachment(this_: &z_loaned_sample_t) -> *const z_loa } } #[cfg(feature = "unstable")] -/// Returns the sample source_info. +/// @attention Unstable feature. +/// @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 { this_ @@ -188,7 +190,8 @@ pub extern "C" fn z_sample_congestion_control(this_: &z_loaned_sample_t) -> z_co } #[cfg(feature = "unstable")] -/// Returns the reliability setting the sample was delieverd with. +/// @attention Unstable feature. +/// @brief Returns the reliability setting the sample was delieverd 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() @@ -258,14 +261,16 @@ impl From for Locality { } #[cfg(feature = "unstable")] -/// Returns default value of `zc_locality_t` +/// @attention Unstable feature. +/// @brief Returns default value of `zc_locality_t` #[no_mangle] pub extern "C" fn zc_locality_default() -> zc_locality_t { Locality::default().into() } -/// The publisher reliability. -/// NOTE: Currently `reliability` does not trigger any data retransmission on the wire. +/// @attention Unstable feature. +/// @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). #[cfg(feature = "unstable")] #[allow(non_camel_case_types, clippy::upper_case_acronyms)] @@ -290,7 +295,8 @@ impl From for z_reliability_t { } #[cfg(feature = "unstable")] -/// Returns the default value for `reliability`. +/// @attention Unstable feature. +/// @brief Returns the default value for `reliability`. #[no_mangle] pub extern "C" fn z_reliability_default() -> z_reliability_t { Reliability::default().into() @@ -308,7 +314,8 @@ impl From for Reliability { } #[cfg(feature = "unstable")] -/// Key expressions types to which Queryable should reply to. +/// @attention Unstable feature. +/// @brief Key expressions types to which Queryable should reply to. #[repr(C)] #[derive(Clone, Copy, Debug)] pub enum zc_reply_keyexpr_t { @@ -339,7 +346,8 @@ impl From for ReplyKeyExpr { } #[cfg(feature = "unstable")] -/// Returns the default value of #zc_reply_keyexpr_t. +/// @attention Unstable feature. +/// @brief Returns the default value of #zc_reply_keyexpr_t. #[no_mangle] pub extern "C" fn zc_reply_keyexpr_default() -> zc_reply_keyexpr_t { ReplyKeyExpr::default().into() @@ -520,13 +528,15 @@ use crate::z_entity_global_id_t; decl_c_type!(copy(z_entity_global_id_t, EntityGlobalId)); #[cfg(feature = "unstable")] -/// Returns the zenoh id of entity global id. +/// @attention Unstable feature. +/// @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")] -/// Returns the entity id of the entity global id. +/// @attention Unstable feature. +/// @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 { this_.as_rust_type_ref().eid() @@ -540,7 +550,8 @@ decl_c_type!( ); #[cfg(feature = "unstable")] -/// Create source info +/// @attention Unstable feature. +/// @brief Creates source info. #[no_mangle] pub extern "C" fn z_source_info_new( this: &mut MaybeUninit, @@ -557,7 +568,8 @@ pub extern "C" fn z_source_info_new( } #[cfg(feature = "unstable")] -/// Returns the source_id of the source info. +/// @attention Unstable feature. +/// @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 { match this_.as_rust_type_ref().source_id { @@ -568,35 +580,40 @@ pub extern "C" fn z_source_info_id(this_: &z_loaned_source_info_t) -> z_entity_g } #[cfg(feature = "unstable")] -/// Returns the source_sn of the source info. +/// @attention Unstable feature. +/// @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 { this_.as_rust_type_ref().source_sn.unwrap_or(0) } #[cfg(feature = "unstable")] -/// Returns ``true`` if source info is valid, ``false`` if it is in gravestone state. +/// @attention Unstable feature. +/// @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 { this_.as_rust_type_ref().source_id.is_some() || this_.as_rust_type_ref().source_sn.is_some() } #[cfg(feature = "unstable")] -/// Borrows source info. +/// @attention Unstable feature. +/// @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 { this_.as_rust_type_ref().as_loaned_c_type_ref() } #[cfg(feature = "unstable")] -/// Frees the memory and invalidates the source info, resetting it to a gravestone state. +/// @attention Unstable feature. +/// @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) { let _ = this_.take_rust_type(); } #[cfg(feature = "unstable")] -/// Constructs source info in its gravestone state. +/// @attention Unstable feature. +/// @brief Constructs source info in its gravestone state. #[no_mangle] pub extern "C" fn z_internal_source_info_null(this_: &mut MaybeUninit) { this_.as_rust_type_mut_uninit().write(SourceInfo::default()); diff --git a/src/get.rs b/src/get.rs index 140301b6c..ce0037c81 100644 --- a/src/get.rs +++ b/src/get.rs @@ -151,8 +151,9 @@ pub unsafe extern "C" fn z_reply_err(this_: &z_loaned_reply_t) -> *const z_loane } #[cfg(feature = "unstable")] -/// Gets the id of the zenoh instance that answered this Reply. -/// Returns `true` if id is present. +/// @attention Unstable feature. +/// @brief Gets the id of the zenoh instance that answered this Reply. +/// @return `true` if id is present. #[no_mangle] #[allow(clippy::missing_safety_doc)] pub unsafe extern "C" fn z_reply_replier_id( @@ -196,14 +197,20 @@ 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. + /// /// The allowed destination for the query. pub allowed_destination: zc_locality_t, #[cfg(feature = "unstable")] + /// @attention Unstable feature. + /// /// 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. + /// /// The source info for the query. pub source_info: Option<&'static mut z_moved_source_info_t>, /// An optional attachment to attach to the query. diff --git a/src/info.rs b/src/info.rs index ffe8a158f..0636d12c4 100644 --- a/src/info.rs +++ b/src/info.rs @@ -30,14 +30,16 @@ impl From<[u8; 16]> for z_id_t { } } -/// Formats the `z_id_t` into 16-digit hex string (LSB-first order) +/// @attention Unstable feature. +/// @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) { let zid = zid.as_rust_type_ref(); dst.as_rust_type_mut_uninit().write(zid.to_string().into()); } -/// Returns the session's Zenoh ID. +/// @attention Unstable feature. +/// @brief Returns the session's Zenoh ID. /// /// Unless the `session` is invalid, that ID is guaranteed to be non-zero. /// In other words, this function returning an array of 16 zeros means you failed @@ -49,7 +51,8 @@ pub unsafe extern "C" fn z_info_zid(session: &z_loaned_session_t) -> z_id_t { session.info().zid().wait().into_c_type() } -/// Fetches the Zenoh IDs of all connected peers. +/// @attention Unstable feature. +/// @brief Fetches the Zenoh IDs of all connected peers. /// /// `callback` will be called once for each ID, is guaranteed to never be called concurrently, /// and is guaranteed to be dropped before this function exits. @@ -69,7 +72,8 @@ pub unsafe extern "C" fn z_info_peers_zid( result::Z_OK } -/// Fetches the Zenoh IDs of all connected routers. +/// @attention Unstable feature. +/// @brief Fetches the Zenoh IDs of all connected routers. /// /// `callback` will be called once for each ID, is guaranteed to never be called concurrently, /// and is guaranteed to be dropped before this function exits. diff --git a/src/keyexpr.rs b/src/keyexpr.rs index 81906d6f1..8e372a940 100644 --- a/src/keyexpr.rs +++ b/src/keyexpr.rs @@ -607,7 +607,8 @@ pub extern "C" fn z_keyexpr_join( } } #[cfg(feature = "unstable")] -/// Intersection level of 2 key expressions. +/// @attention Unstable feature. +/// @brief Intersection level of 2 key expressions. #[derive(Clone, Copy, Debug, PartialEq, Eq)] #[repr(C)] pub enum z_keyexpr_intersection_level_t { @@ -633,9 +634,10 @@ impl From for z_keyexpr_intersection_level_t { } #[cfg(feature = "unstable")] #[no_mangle] -/// Returns the relation between `left` and `right` from `left`'s point of view. +/// @attention Unstable feature. +/// @brief Returns the relation between `left` and `right` from `left`'s point of view. /// -/// Note that this is slower than `z_keyexpr_intersects` and `keyexpr_includes`, so you should favor these methods for most applications. +/// @note This is slower than `z_keyexpr_intersects` and `keyexpr_includes`, so you should favor these methods for most applications. pub extern "C" fn z_keyexpr_relation_to( left: &z_loaned_keyexpr_t, right: &z_loaned_keyexpr_t, diff --git a/src/liveliness.rs b/src/liveliness.rs index c13f19f66..8e8d12b1c 100644 --- a/src/liveliness.rs +++ b/src/liveliness.rs @@ -32,7 +32,8 @@ decl_c_type!( loaned(zc_loaned_liveliness_token_t), ); -/// Constructs liveliness token in its gravestone state. +/// @attention Unstable feature. +/// @brief Constructs liveliness token in its gravestone state. #[no_mangle] pub extern "C" fn zc_internal_liveliness_token_null( this_: &mut MaybeUninit, @@ -40,25 +41,29 @@ pub extern "C" fn zc_internal_liveliness_token_null( this_.as_rust_type_mut_uninit().write(None); } -/// Returns ``true`` if liveliness token is valid, ``false`` otherwise. +/// @attention Unstable feature. +/// @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() } -/// Undeclares liveliness token, frees memory and resets it to a gravestone state. +/// @attention Unstable feature. +/// @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(); } -/// The options for `zc_liveliness_declare_token()`. +/// @attention Unstable feature. +/// @brief The options for `zc_liveliness_declare_token()`. #[repr(C)] pub struct zc_liveliness_declaration_options_t { _dummy: u8, } -/// Constructs default value for `zc_liveliness_declaration_options_t`. +/// @attention Unstable feature. +/// @brief Constructs default value for `zc_liveliness_declaration_options_t`. #[no_mangle] pub extern "C" fn zc_liveliness_declaration_options_default( this: &mut MaybeUninit, @@ -66,7 +71,8 @@ pub extern "C" fn zc_liveliness_declaration_options_default( this.write(zc_liveliness_declaration_options_t { _dummy: 0 }); } -/// Borrows token. +/// @attention Unstable feature. +/// @brief Borrows token. #[no_mangle] #[allow(clippy::missing_safety_doc)] pub unsafe extern "C" fn zc_liveliness_token_loan( @@ -78,7 +84,8 @@ pub unsafe extern "C" fn zc_liveliness_token_loan( .as_loaned_c_type_ref() } -/// Constructs and declares a liveliness token on the network. +/// @attention Unstable feature. +/// @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 /// is achieved, and a DELETE sample if it's lost. @@ -110,7 +117,8 @@ pub extern "C" fn zc_liveliness_declare_token( } } -/// Destroys a liveliness token, notifying subscribers of its destruction. +/// @attention Unstable feature. +/// @brief Destroys a liveliness token, notifying subscribers of its destruction. #[no_mangle] pub extern "C" fn zc_liveliness_undeclare_token( this: &mut zc_moved_liveliness_token_t, @@ -124,13 +132,15 @@ pub extern "C" fn zc_liveliness_undeclare_token( result::Z_OK } -/// The options for `zc_liveliness_declare_subscriber()` +/// @attention Unstable feature. +/// @brief The options for `zc_liveliness_declare_subscriber()` #[repr(C)] pub struct zc_liveliness_subscriber_options_t { _dummy: u8, } -/// Constucts default value for `zc_liveliness_declare_subscriber_options_t`. +/// @attention Unstable feature. +/// @brief Constucts default value for `zc_liveliness_declare_subscriber_options_t`. #[no_mangle] pub extern "C" fn zc_liveliness_subscriber_options_default( this: &mut MaybeUninit, @@ -138,7 +148,8 @@ pub extern "C" fn zc_liveliness_subscriber_options_default( this.write(zc_liveliness_subscriber_options_t { _dummy: 0 }); } -/// Declares a subscriber on liveliness tokens that intersect `key_expr`. +/// @attention Unstable feature. +/// @brief Declares a subscriber on liveliness tokens that intersect `key_expr`. /// /// @param this_: An uninitialized memory location where subscriber will be constructed. /// @param session: The Zenoh session. @@ -180,13 +191,15 @@ pub extern "C" fn zc_liveliness_declare_subscriber( } } -/// The options for `zc_liveliness_get()` +/// @attention Unstable feature. +/// @brief The options for `zc_liveliness_get()` #[repr(C)] pub struct zc_liveliness_get_options_t { timeout_ms: u32, } -/// Constructs default value `zc_liveliness_get_options_t`. +/// @attention Unstable feature. +/// @brief Constructs default value `zc_liveliness_get_options_t`. #[no_mangle] pub extern "C" fn zc_liveliness_get_options_default( this: &mut MaybeUninit, @@ -194,7 +207,8 @@ pub extern "C" fn zc_liveliness_get_options_default( this.write(zc_liveliness_get_options_t { timeout_ms: 10000 }); } -/// Queries liveliness tokens currently on the network with a key expression intersecting with `key_expr`. +/// @attention Unstable feature. +/// @brief Queries liveliness tokens currently on the network with a key expression intersecting with `key_expr`. /// /// @param session: The Zenoh session. /// @param key_expr: The key expression to query liveliness tokens for. diff --git a/src/payload.rs b/src/payload.rs index 201fad7b5..a1bf5e867 100644 --- a/src/payload.rs +++ b/src/payload.rs @@ -152,7 +152,8 @@ pub unsafe extern "C" fn z_bytes_deserialize_into_slice( } #[cfg(all(feature = "shared-memory", feature = "unstable"))] -/// Deserializes data into an owned SHM buffer by copying it's shared reference +/// @attention Unstable feature. +/// @brief Deserializes data into an owned SHM buffer by copying it's shared reference. /// /// @param this_: Data to deserialize. /// @param dst: An uninitialized memory location where to construct a deserialized string. @@ -179,7 +180,8 @@ pub unsafe extern "C" fn z_bytes_deserialize_into_owned_shm( } #[cfg(all(feature = "shared-memory", feature = "unstable"))] -/// Deserializes data into a loaned SHM buffer +/// @attention Unstable feature. +/// @brief Deserializes data into a loaned SHM buffer. /// /// @param this_: Data to deserialize. /// @param dst: An uninitialized memory location where to construct a deserialized SHM buffer. @@ -205,7 +207,8 @@ pub unsafe extern "C" fn z_bytes_deserialize_into_loaned_shm( } #[cfg(all(feature = "shared-memory", feature = "unstable"))] -/// Deserializes data into a mutably loaned SHM buffer +/// @attention Unstable feature. +/// @brief Deserializes data into a mutably loaned SHM buffer. /// /// @param this_: Data to deserialize. /// @param dst: An uninitialized memory location where to construct a deserialized SHM buffer. @@ -810,7 +813,8 @@ pub extern "C" fn z_bytes_iterator_next( } #[cfg(all(feature = "shared-memory", feature = "unstable"))] -/// Serializes from an immutable SHM buffer consuming it +/// @attention Unstable feature. +/// @brief Serializes from an immutable SHM buffer consuming it. #[no_mangle] #[allow(clippy::missing_safety_doc)] pub unsafe extern "C" fn z_bytes_serialize_from_shm( @@ -826,7 +830,8 @@ pub unsafe extern "C" fn z_bytes_serialize_from_shm( } #[cfg(all(feature = "shared-memory", feature = "unstable"))] -/// Serializes from a mutable SHM buffer consuming it +/// @attention Unstable feature. +/// @brief Serializes from a mutable SHM buffer consuming it. #[no_mangle] #[allow(clippy::missing_safety_doc)] pub unsafe extern "C" fn z_bytes_serialize_from_shm_mut( diff --git a/src/publication_cache.rs b/src/publication_cache.rs index cfd17564e..384ed0fcb 100644 --- a/src/publication_cache.rs +++ b/src/publication_cache.rs @@ -25,7 +25,8 @@ use crate::{ #[cfg(feature = "unstable")] use crate::{zc_locality_default, zc_locality_t}; -/// Options passed to the `ze_declare_publication_cache()` function. +/// @attention Unstable feature. +/// @brief Options passed to the `ze_declare_publication_cache()` function. #[repr(C)] pub struct ze_publication_cache_options_t { /// The prefix used for queryable. @@ -41,7 +42,8 @@ pub struct ze_publication_cache_options_t { pub resources_limit: usize, } -/// Constructs the default value for `ze_publication_cache_options_t`. +/// @attention Unstable feature. +/// @brief Constructs the default value for `ze_publication_cache_options_t`. #[no_mangle] pub extern "C" fn ze_publication_cache_options_default( this: &mut MaybeUninit, @@ -67,7 +69,8 @@ decl_c_type!( loaned(ze_loaned_publication_cache_t), ); -/// Constructs and declares a publication cache. +/// @attention Unstable feature. +/// @brief Constructs and declares a publication cache. /// /// @param this_: An uninitialized location in memory where publication cache will be constructed. /// @param session: A Zenoh session. @@ -115,7 +118,8 @@ pub extern "C" fn ze_declare_publication_cache( } } -/// Constructs a publication cache in a gravestone state. +/// @attention Unstable feature. +/// @brief Constructs a publication cache in a gravestone state. #[no_mangle] #[allow(clippy::missing_safety_doc)] pub extern "C" fn ze_internal_publication_cache_null( @@ -124,7 +128,8 @@ pub extern "C" fn ze_internal_publication_cache_null( this_.as_rust_type_mut_uninit().write(None); } -/// Returns ``true`` if publication cache is valid, ``false`` otherwise. +/// @attention Unstable feature. +/// @brief Returns ``true`` if publication cache is valid, ``false`` otherwise. #[no_mangle] #[allow(clippy::missing_safety_doc)] pub extern "C" fn ze_internal_publication_cache_check( @@ -133,7 +138,8 @@ pub extern "C" fn ze_internal_publication_cache_check( this_.as_rust_type_ref().is_some() } -/// Undeclares and drops publication cache. +/// @attention Unstable feature. +/// @brief Undeclares and drops publication cache. /// @return 0 in case of success, negative error code otherwise. #[no_mangle] #[allow(clippy::missing_safety_doc)] @@ -149,14 +155,16 @@ pub extern "C" fn ze_undeclare_publication_cache( result::Z_OK } -/// Drops publication cache and resets it to its gravestone state. +/// @attention Unstable feature. +/// @brief Drops publication cache and resets it to its gravestone state. #[no_mangle] #[allow(clippy::missing_safety_doc)] pub extern "C" fn ze_publication_cache_drop(this: &mut ze_moved_publication_cache_t) { std::mem::drop(this.take_rust_type()) } -/// Returns the key expression of the publication cache. +/// @attention Unstable feature. +/// @brief Returns the key expression of the publication cache. #[no_mangle] pub extern "C" fn ze_publication_cache_keyexpr( this_: &ze_loaned_publication_cache_t, @@ -164,7 +172,8 @@ pub extern "C" fn ze_publication_cache_keyexpr( this_.as_rust_type_ref().key_expr().as_loaned_c_type_ref() } -/// Borrows querying subscriber. +/// @attention Unstable feature. +/// @brief Borrows querying subscriber. #[no_mangle] #[allow(clippy::missing_safety_doc)] pub unsafe extern "C" fn ze_publication_cache_loan( diff --git a/src/publisher.rs b/src/publisher.rs index 7f2af457b..5dcd3ab78 100644 --- a/src/publisher.rs +++ b/src/publisher.rs @@ -50,10 +50,14 @@ pub struct z_publisher_options_t { pub priority: z_priority_t, /// If true, Zenoh will not wait to batch this message with others to reduce the bandwith. pub is_express: bool, - /// The publisher reliability. #[cfg(feature = "unstable")] + /// @attention Unstable feature. + /// + /// The publisher reliability. pub reliability: z_reliability_t, #[cfg(feature = "unstable")] + /// @attention Unstable feature. + /// /// The allowed destination for this publisher. pub allowed_destination: zc_locality_t, } @@ -174,8 +178,10 @@ pub struct z_publisher_put_options_t { pub encoding: Option<&'static mut z_moved_encoding_t>, /// The timestamp of the publication. pub timestamp: Option<&'static z_timestamp_t>, - /// The source info for the publication. #[cfg(feature = "unstable")] + /// @attention Unstable feature. + /// + /// The source info for the publication. pub source_info: Option<&'static mut z_moved_source_info_t>, /// The attachment to attach to the publication. pub attachment: Option<&'static mut z_moved_bytes_t>, @@ -281,7 +287,8 @@ pub extern "C" fn z_publisher_delete( } } #[cfg(feature = "unstable")] -/// Returns the ID of the publisher. +/// @attention Unstable feature. +/// @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 { publisher.as_rust_type_ref().id().into_c_type() @@ -303,18 +310,20 @@ decl_c_type!( owned(zc_owned_matching_listener_t, option MatchingListener<'static, ()>), ); -/// Constructs an empty matching listener #[no_mangle] #[cfg(feature = "unstable")] +/// @attention Unstable feature. +/// @brief Constructs an empty matching listener. pub extern "C" fn zc_internal_matching_listener_null( this_: &mut MaybeUninit, ) { this_.as_rust_type_mut_uninit().write(None); } -/// Checks the matching listener is for the gravestone state #[no_mangle] #[cfg(feature = "unstable")] +/// @attention Unstable feature. +/// @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, ) -> bool { @@ -322,7 +331,8 @@ pub extern "C" fn zc_internal_matching_listener_check( } #[cfg(feature = "unstable")] -/// A struct that indicates if there exist Subscribers matching the Publisher's key expression. +/// @attention Unstable feature. +/// @brief A struct that indicates if there exist Subscribers matching the Publisher's key expression. #[repr(C)] #[derive(Debug, Clone, Copy)] pub struct zc_matching_status_t { @@ -331,7 +341,8 @@ pub struct zc_matching_status_t { } #[cfg(feature = "unstable")] -/// Constructs matching listener, registering a callback for notifying subscribers matching with a given publisher. +/// @attention Unstable feature. +/// @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. /// @param publisher: A publisher to associate with matching listener. @@ -370,7 +381,8 @@ pub extern "C" fn zc_publisher_matching_listener_declare( } #[cfg(feature = "unstable")] -/// Undeclares the given matching listener, droping and invalidating it. +/// @attention Unstable feature. +/// @brief Undeclares the given matching listener, droping and invalidating it. /// /// @return 0 in case of success, negative error code otherwise. #[no_mangle] @@ -388,19 +400,17 @@ pub extern "C" fn zc_publisher_matching_listener_undeclare( } #[cfg(feature = "unstable")] -/// Undeclares the given matching listener, droping and invalidating it. -/// -/// @return 0 in case of success, negative error code otherwise. +/// @attention Unstable feature. +/// @brief Undeclares the given matching listener, droping and invalidating it. #[no_mangle] #[allow(clippy::missing_safety_doc)] -pub extern "C" fn zc_publisher_matching_listener_drop( - this: &mut zc_moved_matching_listener_t, -) -> result::z_result_t { - zc_publisher_matching_listener_undeclare(this) +pub extern "C" fn zc_publisher_matching_listener_drop(this: &mut zc_moved_matching_listener_t) { + std::mem::drop(this.take_rust_type()) } #[cfg(feature = "unstable")] -/// Gets publisher matching status - i.e. if there are any subscribers matching its key expression. +/// @attention Unstable feature. +/// @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). #[no_mangle] @@ -423,11 +433,11 @@ pub extern "C" fn zc_publisher_get_matching_status( } } -/// Undeclares the given publisher, droping and invalidating it. -/// -/// @return 0 in case of success, negative error code otherwise. #[no_mangle] #[allow(clippy::missing_safety_doc)] +/// @brief Undeclares the given publisher, droping and invalidating it. +/// +/// @return 0 in case of success, negative error code otherwise. pub extern "C" fn z_undeclare_publisher(this_: &mut z_moved_publisher_t) -> result::z_result_t { if let Some(p) = this_.take_rust_type() { if let Err(e) = p.undeclare().wait() { diff --git a/src/put.rs b/src/put.rs index 0273e2e19..ffb668cfd 100644 --- a/src/put.rs +++ b/src/put.rs @@ -43,14 +43,20 @@ pub struct z_put_options_t { pub is_express: bool, /// The timestamp of this message. pub timestamp: Option<&'static mut z_timestamp_t>, - /// The put operation reliability. #[cfg(feature = "unstable")] + /// @attention Unstable feature. + /// + /// The put operation reliability. reliability: z_reliability_t, - /// The allowed destination of this message. #[cfg(feature = "unstable")] + /// @attention Unstable feature. + /// + /// The allowed destination of this message. pub allowed_destination: zc_locality_t, - /// The source info for the message. #[cfg(feature = "unstable")] + /// @attention Unstable feature. + /// + /// The source info for the message. pub source_info: Option<&'static mut z_moved_source_info_t>, /// The attachment to this message. pub attachment: Option<&'static mut z_moved_bytes_t>, @@ -141,11 +147,15 @@ pub struct z_delete_options_t { pub is_express: bool, /// The timestamp of this message. pub timestamp: Option<&'static mut z_timestamp_t>, - /// The delete operation reliability. #[cfg(feature = "unstable")] + /// @attention Unstable feature. + /// + /// The delete operation reliability. pub reliability: z_reliability_t, - /// The allowed destination of this message. #[cfg(feature = "unstable")] + /// @attention Unstable feature. + /// + /// The allowed destination of this message. pub allowed_destination: zc_locality_t, } diff --git a/src/queryable.rs b/src/queryable.rs index 79ebad94c..529f23109 100644 --- a/src/queryable.rs +++ b/src/queryable.rs @@ -126,8 +126,10 @@ pub struct z_query_reply_options_t { pub is_express: bool, /// The timestamp of the reply. pub timestamp: Option<&'static mut z_timestamp_t>, - /// The source info for the reply. #[cfg(feature = "unstable")] + /// @attention Unstable feature. + /// + /// The source info for the reply. pub source_info: Option<&'static mut z_moved_source_info_t>, /// The attachment to this reply. pub attachment: Option<&'static mut z_moved_bytes_t>, @@ -180,8 +182,10 @@ pub struct z_query_reply_del_options_t { pub is_express: bool, /// The timestamp of the reply. pub timestamp: Option<&'static mut z_timestamp_t>, - /// The source info for the reply. #[cfg(feature = "unstable")] + /// @attention Unstable feature. + /// + /// The source info for the reply. pub source_info: Option<&'static mut z_moved_source_info_t>, /// The attachment to this reply. pub attachment: Option<&'static mut z_moved_bytes_t>, @@ -280,7 +284,8 @@ pub extern "C" fn z_internal_queryable_check(this_: &z_owned_queryable_t) -> boo } #[cfg(feature = "unstable")] -/// Returns the ID of the queryable. +/// @attention Unstable feature. +/// @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 { queryable.as_rust_type_ref().id().into_c_type() diff --git a/src/querying_subscriber.rs b/src/querying_subscriber.rs index 9cc12db6d..37153b713 100644 --- a/src/querying_subscriber.rs +++ b/src/querying_subscriber.rs @@ -50,7 +50,8 @@ pub extern "C" fn ze_internal_querying_subscriber_null( this.as_rust_type_mut_uninit().write(None); } -/// A set of options that can be applied to a querying subscriber, +/// @attention Unstable feature. +/// @brief A set of options that can be applied to a querying subscriber, /// upon its declaration via `ze_declare_querying_subscriber()`. /// #[repr(C)] @@ -74,7 +75,8 @@ pub struct ze_querying_subscriber_options_t { query_timeout_ms: u64, } -/// Constructs the default value for `ze_querying_subscriber_options_t`. +/// @attention Unstable feature. +/// @brief Constructs the default value for `ze_querying_subscriber_options_t`. #[no_mangle] pub extern "C" fn ze_querying_subscriber_options_default( this: &mut MaybeUninit, @@ -92,7 +94,8 @@ pub extern "C" fn ze_querying_subscriber_options_default( }); } -/// Constructs and declares a querying subscriber for a given key expression. +/// @attention Unstable feature. +/// @brief Constructs and declares a querying subscriber for a given key expression. /// /// @param this_: An uninitialized memory location where querying subscriber will be constructed. /// @param session: A Zenoh session. @@ -152,7 +155,8 @@ pub unsafe extern "C" fn ze_declare_querying_subscriber( } } -/// Make querying subscriber perform an additional query on a specified selector. +/// @attention Unstable feature. +/// @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. #[allow(clippy::missing_safety_doc)] @@ -216,7 +220,8 @@ pub unsafe extern "C" fn ze_querying_subscriber_get( result::Z_OK } -/// Undeclares the given querying subscriber, drops it and resets to a gravestone state. +/// @attention Unstable feature. +/// @brief Undeclares the given querying subscriber, drops it and resets to a gravestone state. /// /// @return 0 in case of success, negative error code otherwise. #[no_mangle] @@ -232,13 +237,15 @@ pub extern "C" fn ze_undeclare_querying_subscriber( result::Z_OK } -/// Drops querying subscriber. +/// @attention Unstable feature. +/// @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()) } -/// Returns ``true`` if querying subscriber is valid, ``false`` otherwise. +/// @attention Unstable feature. +/// @brief Returns ``true`` if querying subscriber is valid, ``false`` otherwise. #[no_mangle] pub extern "C" fn ze_internal_querying_subscriber_check( this_: &ze_owned_querying_subscriber_t, @@ -246,7 +253,8 @@ pub extern "C" fn ze_internal_querying_subscriber_check( this_.as_rust_type_ref().is_some() } -/// Borrows querying subscriber. +/// @attention Unstable feature. +/// @brief Borrows querying subscriber. #[no_mangle] #[allow(clippy::missing_safety_doc)] pub unsafe extern "C" fn ze_querying_subscriber_loan( diff --git a/src/scouting.rs b/src/scouting.rs index a5f524437..4d199c065 100644 --- a/src/scouting.rs +++ b/src/scouting.rs @@ -64,7 +64,8 @@ pub extern "C" fn z_internal_hello_null(this_: &mut MaybeUninit } #[cfg(feature = "unstable")] -/// Returns id of Zenoh entity that transmitted hello message. +/// @attention Unstable feature. +/// @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 { this_.as_rust_type_ref().zid().into_c_type() diff --git a/src/session.rs b/src/session.rs index e70af592a..5307f676e 100644 --- a/src/session.rs +++ b/src/session.rs @@ -79,7 +79,8 @@ pub extern "C" fn z_open( } #[cfg(all(feature = "shared-memory", feature = "unstable"))] -/// Constructs and opens a new Zenoh session with specified client storage. +/// @attention Unstable feature. +/// @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). #[allow(clippy::missing_safety_doc)] diff --git a/src/shm/buffer/zshm.rs b/src/shm/buffer/zshm.rs index 1b401854c..9be89a5fa 100644 --- a/src/shm/buffer/zshm.rs +++ b/src/shm/buffer/zshm.rs @@ -29,7 +29,8 @@ decl_c_type!( loaned(z_loaned_shm_t, zshm), ); -/// Constructs ZShm slice from ZShmMut slice +/// @attention Unstable feature. +/// @brief Constructs ZShm slice from ZShmMut slice. #[no_mangle] pub extern "C" fn z_shm_from_mut( this_: &mut MaybeUninit, @@ -39,19 +40,22 @@ pub extern "C" fn z_shm_from_mut( this_.as_rust_type_mut_uninit().write(shm); } -/// Constructs ZShm slice in its gravestone value. +/// @attention Unstable feature. +/// @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); } -/// Returns ``true`` if `this` is valid. +/// @attention Unstable feature. +/// @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() } -/// Converts borrowed ZShm slice to owned ZShm slice by performing a shallow SHM reference copy +/// @attention Unstable feature. +/// @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) { let this = this_.as_rust_type_ref(); @@ -59,7 +63,8 @@ pub extern "C" fn z_shm_clone(out: &mut MaybeUninit, this_: &z_lo out.as_rust_type_mut_uninit().write(Some(copy)); } -/// Borrows ZShm slice +/// @attention Unstable feature. +/// @brief Borrows ZShm slice. #[no_mangle] #[allow(clippy::missing_safety_doc)] pub unsafe extern "C" fn z_shm_loan(this_: &z_owned_shm_t) -> &z_loaned_shm_t { @@ -71,7 +76,7 @@ pub unsafe extern "C" fn z_shm_loan(this_: &z_owned_shm_t) -> &z_loaned_shm_t { this.as_loaned_c_type_ref() } -/// Mutably borrows ZShm slice +/// @brief Mutably borrows ZShm slice. #[no_mangle] #[allow(clippy::missing_safety_doc)] pub unsafe extern "C" fn z_shm_loan_mut(this_: &mut z_owned_shm_t) -> &mut z_loaned_shm_t { @@ -83,7 +88,8 @@ pub unsafe extern "C" fn z_shm_loan_mut(this_: &mut z_owned_shm_t) -> &mut z_loa this.as_loaned_c_type_mut() } -/// Mutably borrows ZShm slice as borrowed ZShmMut slice +/// @attention Unstable feature. +/// @brief Mutably borrows ZShm slice as borrowed ZShmMut slice. #[no_mangle] #[allow(clippy::missing_safety_doc)] pub unsafe extern "C" fn z_shm_try_mut(this_: &mut z_owned_shm_t) -> *mut z_loaned_shm_mut_t { @@ -99,13 +105,15 @@ pub unsafe extern "C" fn z_shm_try_mut(this_: &mut z_owned_shm_t) -> *mut z_loan } } -/// Deletes ZShm slice +/// @attention Unstable feature. +/// @brief Deletes ZShm slice. #[no_mangle] pub extern "C" fn z_shm_drop(this_: &mut z_moved_shm_t) { let _ = this_.take_rust_type(); } -/// Tries to reborrow mutably-borrowed ZShm slice as borrowed ZShmMut slice +/// @attention Unstable feature. +/// @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 { let this = this_.as_rust_type_mut(); @@ -118,13 +126,15 @@ pub extern "C" fn z_shm_try_reloan_mut(this_: &mut z_loaned_shm_t) -> *mut z_loa } } -/// @return the length of the ZShm slice +/// @attention Unstable feature. +/// @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() } -/// @return the pointer of the ZShm slice +/// @attention Unstable feature. +/// @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 { let s = this_.as_rust_type_ref(); diff --git a/src/shm/buffer/zshmmut.rs b/src/shm/buffer/zshmmut.rs index f901ad607..3037b7090 100644 --- a/src/shm/buffer/zshmmut.rs +++ b/src/shm/buffer/zshmmut.rs @@ -29,7 +29,8 @@ decl_c_type!( loaned(z_loaned_shm_mut_t, zshmmut), ); -/// Tries to construct ZShmMut slice from ZShm slice +/// @attention Unstable feature. +/// @brief Tries to construct ZShmMut slice from ZShm slice. #[no_mangle] pub extern "C" fn z_shm_mut_try_from_immut( this: &mut MaybeUninit, @@ -42,19 +43,22 @@ pub extern "C" fn z_shm_mut_try_from_immut( this.as_rust_type_mut_uninit().write(shm); } -/// Constructs ZShmMut slice in its gravestone value. +/// @attention Unstable feature. +/// @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); } -/// Returns ``true`` if `this` is valid. +/// @attention Unstable feature. +/// @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() } -/// Borrows ZShmMut slice +/// @attention Unstable feature. +/// @brief Borrows ZShmMut slice. #[no_mangle] #[allow(clippy::missing_safety_doc)] pub unsafe extern "C" fn z_shm_mut_loan(this_: &z_owned_shm_mut_t) -> &z_loaned_shm_mut_t { @@ -66,7 +70,8 @@ pub unsafe extern "C" fn z_shm_mut_loan(this_: &z_owned_shm_mut_t) -> &z_loaned_ shmmut.as_loaned_c_type_ref() } -/// Mutably borrows ZShmMut slice +/// @attention Unstable feature. +/// @brief Mutably borrows ZShmMut slice. #[no_mangle] #[allow(clippy::missing_safety_doc)] pub unsafe extern "C" fn z_shm_mut_loan_mut( @@ -80,26 +85,30 @@ pub unsafe extern "C" fn z_shm_mut_loan_mut( shmmut.as_loaned_c_type_mut() } -/// Deletes ZShmMut slice +/// @attention Unstable feature. +/// @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(); } -/// @return the length of the ZShmMut slice +/// @attention Unstable feature. +/// @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() } -/// @return the immutable pointer to the underlying data +/// @attention Unstable feature. +/// @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 { let s = this_.as_rust_type_ref(); s.as_ref().as_ptr() } -/// @return the mutable pointer to the underlying data +/// @attention Unstable feature. +/// @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 { this_.as_rust_type_mut().as_mut().as_mut_ptr() diff --git a/src/shm/client/shm_client.rs b/src/shm/client/shm_client.rs index 2446ddab2..4a77c1f40 100644 --- a/src/shm/client/shm_client.rs +++ b/src/shm/client/shm_client.rs @@ -28,7 +28,8 @@ use crate::{ transmute::{RustTypeRef, RustTypeRefUninit, TakeRustType}, }; -/// A callbacks for ShmClient +/// @attention Unstable feature. +/// @brief Callback for ShmClient. #[derive(Debug)] #[repr(C)] pub struct zc_shm_client_callbacks_t { @@ -67,7 +68,8 @@ impl ShmClient for DynamicShmClient { } } -/// Creates a new SHM Client +/// @attention Unstable feature. +/// @brief Creates a new SHM Client. #[no_mangle] pub extern "C" fn z_shm_client_new( this: &mut MaybeUninit, @@ -78,19 +80,22 @@ pub extern "C" fn z_shm_client_new( this.as_rust_type_mut_uninit().write(Some(client)); } -/// Constructs SHM client in its gravestone value. +/// @attention Unstable feature. +/// @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); } -/// Returns ``true`` if `this` is valid. +/// @attention Unstable feature. +/// @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() } -/// Deletes SHM Client +/// @attention Unstable feature. +/// @brief Deletes SHM Client. #[no_mangle] pub extern "C" fn z_shm_client_drop(this_: &mut z_moved_shm_client_t) { let _ = this_.take_rust_type(); diff --git a/src/shm/client/shm_segment.rs b/src/shm/client/shm_segment.rs index 0af08a993..8d1724a0c 100644 --- a/src/shm/client/shm_segment.rs +++ b/src/shm/client/shm_segment.rs @@ -26,14 +26,16 @@ use crate::{ shm::common::types::z_chunk_id_t, }; -/// A callbacks for ShmSegment +/// @attention Unstable feature. +/// @brief Callbacks for ShmSegment. #[derive(Debug)] #[repr(C)] 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, } -/// A ShmSegment +/// @attention Unstable feature. +/// @brief An ShmSegment. #[derive(Debug)] #[repr(C)] pub struct z_shm_segment_t { diff --git a/src/shm/client_storage/mod.rs b/src/shm/client_storage/mod.rs index b4efd99bd..6c0949a64 100644 --- a/src/shm/client_storage/mod.rs +++ b/src/shm/client_storage/mod.rs @@ -30,14 +30,16 @@ decl_c_type!( loaned(zc_loaned_shm_client_list_t), ); -/// Creates a new empty list of SHM Clients +/// @attention Unstable feature. +/// @brief Creates a new empty list of SHM Clients. #[no_mangle] pub extern "C" fn zc_shm_client_list_new(this_: &mut MaybeUninit) { let client_list: Vec<(ProtocolID, Arc)> = Vec::default(); this_.as_rust_type_mut_uninit().write(Some(client_list)); } -/// Constructs SHM client list in its gravestone value. +/// @attention Unstable feature. +/// @brief Constructs SHM client list in its gravestone value. #[no_mangle] pub extern "C" fn zc_internal_shm_client_list_null( this_: &mut MaybeUninit, @@ -45,19 +47,22 @@ pub extern "C" fn zc_internal_shm_client_list_null( this_.as_rust_type_mut_uninit().write(None); } -/// Returns ``true`` if `this` is valid. +/// @attention Unstable feature. +/// @brief Returns ``true`` if `this` is valid. #[no_mangle] pub extern "C" fn zc_internal_shm_client_list_check(this_: &zc_owned_shm_client_list_t) -> bool { this_.as_rust_type_ref().is_some() } -/// Deletes list of SHM Clients +/// @attention Unstable feature. +/// @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(); } -/// Borrows list of SHM Clients +/// @attention Unstable feature. +/// @brief Borrows list of SHM Clients. #[no_mangle] #[allow(clippy::missing_safety_doc)] pub unsafe extern "C" fn zc_shm_client_list_loan( @@ -69,7 +74,8 @@ pub unsafe extern "C" fn zc_shm_client_list_loan( .as_loaned_c_type_ref() } -/// Mutably borrows list of SHM Clients +/// @attention Unstable feature. +/// @brief Mutably borrows list of SHM Clients. #[no_mangle] #[allow(clippy::missing_safety_doc)] pub unsafe extern "C" fn zc_shm_client_list_loan_mut( @@ -81,6 +87,7 @@ pub unsafe extern "C" fn zc_shm_client_list_loan_mut( .as_loaned_c_type_mut() } +/// @attention Unstable feature. #[no_mangle] pub extern "C" fn zc_shm_client_list_add_client( id: z_protocol_id_t, @@ -99,6 +106,7 @@ decl_c_type!( loaned(z_loaned_shm_client_storage_t), ); +/// @attention Unstable feature. #[no_mangle] pub extern "C" fn z_ref_shm_client_storage_global( this: &mut MaybeUninit, @@ -107,6 +115,7 @@ pub extern "C" fn z_ref_shm_client_storage_global( .write(Some(Arc::clone(&GLOBAL_CLIENT_STORAGE.read()))); } +/// @attention Unstable feature. #[no_mangle] pub extern "C" fn z_shm_client_storage_new_default( this: &mut MaybeUninit, @@ -118,6 +127,7 @@ pub extern "C" fn z_shm_client_storage_new_default( ))); } +/// @attention Unstable feature. #[no_mangle] pub extern "C" fn z_shm_client_storage_new( this: &mut MaybeUninit, @@ -140,7 +150,8 @@ pub extern "C" fn z_shm_client_storage_new( Z_OK } -/// Performs a shallow copy of SHM Client Storage +/// @attention Unstable feature. +/// @brief Performs a shallow copy of SHM Client Storage. #[no_mangle] pub extern "C" fn z_shm_client_storage_clone( this: &mut MaybeUninit, @@ -150,6 +161,7 @@ pub extern "C" fn z_shm_client_storage_clone( .write(Some(from.as_rust_type_ref().clone())); } +/// @attention Unstable feature. /// Constructs SHM Client Storage in its gravestone value. #[no_mangle] pub extern "C" fn z_internal_shm_client_storage_null( @@ -158,7 +170,8 @@ pub extern "C" fn z_internal_shm_client_storage_null( this_.as_rust_type_mut_uninit().write(None); } -/// Returns ``true`` if `this` is valid. +/// @attention Unstable feature. +/// @return ``true`` if `this` is valid. #[no_mangle] pub extern "C" fn z_internal_shm_client_storage_check( this_: &z_owned_shm_client_storage_t, @@ -166,13 +179,15 @@ pub extern "C" fn z_internal_shm_client_storage_check( this_.as_rust_type_ref().is_some() } -/// Derefs SHM Client Storage +/// @attention Unstable feature. +/// @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(); } -/// Borrows SHM Client Storage +/// @attention Unstable feature. +/// @brief Borrows SHM Client Storage. #[no_mangle] #[allow(clippy::missing_safety_doc)] pub unsafe extern "C" fn z_shm_client_storage_loan( diff --git a/src/shm/common/types.rs b/src/shm/common/types.rs index 735192c4d..86658543c 100644 --- a/src/shm/common/types.rs +++ b/src/shm/common/types.rs @@ -12,16 +12,19 @@ // ZettaScale Zenoh Team, // -/// Unique protocol identifier. +/// @attention Unstable feature. +/// @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 +/// and ShmProviderBackend implementations will never use the same ProtocolID. #[allow(non_camel_case_types)] pub type z_protocol_id_t = u32; -/// Unique segment identifier +/// @attention Unstable feature. +/// @brief Unique segment identifier. #[allow(non_camel_case_types)] pub type z_segment_id_t = u32; -/// Chunk id within it's segment +/// @attention Unstable feature. +/// @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 fd131395f..e36736645 100644 --- a/src/shm/protocol_implementations/posix/posix_shm_client.rs +++ b/src/shm/protocol_implementations/posix/posix_shm_client.rs @@ -18,7 +18,8 @@ use zenoh::shm::{PosixShmClient, ShmClient}; use crate::{transmute::RustTypeRefUninit, z_owned_shm_client_t}; -/// Creates a new POSIX SHM Client +/// @attention Unstable feature. +/// @brief Creates a new POSIX SHM Client. #[no_mangle] pub extern "C" fn z_posix_shm_client_new(this_: &mut MaybeUninit) { let client = Arc::new(PosixShmClient) as Arc; diff --git a/src/shm/protocol_implementations/posix/posix_shm_provider.rs b/src/shm/protocol_implementations/posix/posix_shm_provider.rs index 8ae35779b..291ce0c19 100644 --- a/src/shm/protocol_implementations/posix/posix_shm_provider.rs +++ b/src/shm/protocol_implementations/posix/posix_shm_provider.rs @@ -32,7 +32,8 @@ pub type PosixShmProvider = pub type PosixAllocLayout = AllocLayout<'static, StaticProtocolID, PosixShmProviderBackend>; -/// Creates a new POSIX SHM Provider +/// @attention Unstable feature. +/// @brief Creates a new POSIX SHM Provider. #[no_mangle] pub extern "C" fn z_posix_shm_provider_new( this: &mut MaybeUninit, diff --git a/src/shm/protocol_implementations/posix/protocol_id.rs b/src/shm/protocol_implementations/posix/protocol_id.rs index 2d6b4bca8..3d2fbc29f 100644 --- a/src/shm/protocol_implementations/posix/protocol_id.rs +++ b/src/shm/protocol_implementations/posix/protocol_id.rs @@ -15,6 +15,7 @@ use libc::c_uint; use zenoh::shm::POSIX_PROTOCOL_ID; -// Protocol identifier for POSIX SHM Protocol +/// @attention Unstable feature. +/// @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 d18a1c864..7e2c62c9d 100644 --- a/src/shm/provider/alloc_layout.rs +++ b/src/shm/provider/alloc_layout.rs @@ -50,7 +50,8 @@ decl_c_type!( loaned(z_loaned_alloc_layout_t), ); -/// Creates a new Alloc Layout for SHM Provider +/// @attention Unstable feature. +/// @brief Creates a new Alloc Layout for SHM Provider. #[no_mangle] pub extern "C" fn z_alloc_layout_new( this: &mut MaybeUninit, diff --git a/src/shm/provider/chunk.rs b/src/shm/provider/chunk.rs index cd977477b..bf1d1c94c 100644 --- a/src/shm/provider/chunk.rs +++ b/src/shm/provider/chunk.rs @@ -18,7 +18,8 @@ use zenoh::shm::{AllocatedChunk, ChunkDescriptor}; use crate::shm::common::types::{z_chunk_id_t, z_segment_id_t}; -/// A ChunkDescriptor +/// @attention Unstable feature. +/// @brief A ChunkDescriptor. #[repr(C)] pub struct z_chunk_descriptor_t { segment: z_segment_id_t, @@ -43,7 +44,8 @@ impl From<&ChunkDescriptor> for z_chunk_descriptor_t { } } -/// An AllocatedChunk +/// @attention Unstable feature. +/// @brief An AllocatedChunk. #[repr(C)] pub struct z_allocated_chunk_t { descriptpr: z_chunk_descriptor_t, diff --git a/src/shm/provider/shm_provider.rs b/src/shm/provider/shm_provider.rs index d93ddae1a..63c06a26c 100644 --- a/src/shm/provider/shm_provider.rs +++ b/src/shm/provider/shm_provider.rs @@ -54,7 +54,8 @@ decl_c_type!( loaned(z_loaned_shm_provider_t), ); -/// Creates a new SHM Provider +/// @attention Unstable feature. +/// @brief Creates a new SHM Provider. #[no_mangle] pub extern "C" fn z_shm_provider_new( this: &mut MaybeUninit, @@ -72,7 +73,8 @@ pub extern "C" fn z_shm_provider_new( .write(Some(CSHMProvider::Dynamic(provider))); } -/// Creates a new threadsafe SHM Provider +/// @attention Unstable feature. +/// @brief Creates a new threadsafe SHM Provider. #[no_mangle] pub extern "C" fn z_shm_provider_threadsafe_new( this: &mut MaybeUninit, @@ -90,19 +92,22 @@ pub extern "C" fn z_shm_provider_threadsafe_new( .write(Some(CSHMProvider::DynamicThreadsafe(provider))); } -/// Constructs SHM Provider in its gravestone value. +/// @attention Unstable feature. +/// @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); } -/// Returns ``true`` if `this` is valid. +/// @attention Unstable feature. +/// @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() } -/// Borrows SHM Provider +/// @attention Unstable feature. +/// @brief Borrows SHM Provider. #[no_mangle] #[allow(clippy::missing_safety_doc)] pub unsafe extern "C" fn z_shm_provider_loan( @@ -114,12 +119,14 @@ pub unsafe extern "C" fn z_shm_provider_loan( .as_loaned_c_type_ref() } -/// Deletes SHM Provider +/// @attention Unstable feature. +/// @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. #[no_mangle] pub extern "C" fn z_shm_provider_alloc( out_result: &mut MaybeUninit, @@ -130,6 +137,7 @@ pub extern "C" fn z_shm_provider_alloc( alloc::(out_result, provider, size, alignment) } +/// @attention Unstable feature. #[no_mangle] pub extern "C" fn z_shm_provider_alloc_gc( out_result: &mut MaybeUninit, @@ -140,6 +148,7 @@ pub extern "C" fn z_shm_provider_alloc_gc( alloc::(out_result, provider, size, alignment) } +/// @attention Unstable feature. #[no_mangle] pub extern "C" fn z_shm_provider_alloc_gc_defrag( out_result: &mut MaybeUninit, @@ -150,6 +159,7 @@ pub extern "C" fn z_shm_provider_alloc_gc_defrag( alloc::>(out_result, provider, size, alignment) } +/// @attention Unstable feature. #[no_mangle] pub extern "C" fn z_shm_provider_alloc_gc_defrag_dealloc( out_result: &mut MaybeUninit, @@ -160,6 +170,7 @@ pub extern "C" fn z_shm_provider_alloc_gc_defrag_dealloc( alloc::>>(out_result, provider, size, alignment) } +/// @attention Unstable feature. #[no_mangle] pub extern "C" fn z_shm_provider_alloc_gc_defrag_blocking( out_result: &mut MaybeUninit, @@ -170,6 +181,7 @@ pub extern "C" fn z_shm_provider_alloc_gc_defrag_blocking( alloc::>>(out_result, provider, size, alignment) } +/// @attention Unstable feature. #[no_mangle] pub extern "C" fn z_shm_provider_alloc_gc_defrag_async( out_result: &'static mut MaybeUninit, @@ -192,21 +204,25 @@ pub extern "C" fn z_shm_provider_alloc_gc_defrag_async( ) } +/// @attention Unstable feature. #[no_mangle] pub extern "C" fn z_shm_provider_defragment(provider: &z_loaned_shm_provider_t) -> usize { defragment(provider) } +/// @attention Unstable feature. #[no_mangle] pub extern "C" fn z_shm_provider_garbage_collect(provider: &z_loaned_shm_provider_t) -> usize { garbage_collect(provider) } +/// @attention Unstable feature. #[no_mangle] pub extern "C" fn z_shm_provider_available(provider: &z_loaned_shm_provider_t) -> usize { available(provider) } +/// @attention Unstable feature. #[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 640524b25..e636f1584 100644 --- a/src/shm/provider/shm_provider_backend.rs +++ b/src/shm/provider/shm_provider_backend.rs @@ -26,7 +26,8 @@ use crate::{ z_loaned_memory_layout_t, z_owned_chunk_alloc_result_t, z_owned_memory_layout_t, }; -/// A callbacks for ShmProviderBackend +/// @attention Unstable feature. +/// @brief Callbacks for ShmProviderBackend. #[derive(Debug)] #[repr(C)] pub struct zc_shm_provider_backend_callbacks_t { diff --git a/src/shm/provider/types.rs b/src/shm/provider/types.rs index a9c6cb9a5..ce3f55cdb 100644 --- a/src/shm/provider/types.rs +++ b/src/shm/provider/types.rs @@ -32,16 +32,16 @@ use crate::{ z_owned_shm_mut_t, }; -/// Allocation errors -/// -/// - **NEED_DEFRAGMENT**: defragmentation needed -/// - **OUT_OF_MEMORY**: the provider is out of memory -/// - **OTHER**: other error +/// @attention Unstable feature. +/// @brief Allocation errors #[repr(C)] #[derive(Clone, Copy)] pub enum z_alloc_error_t { + /// Defragmentation needed. NEED_DEFRAGMENT, + /// The provider is out of memory. OUT_OF_MEMORY, + /// Other error. OTHER, } @@ -67,14 +67,14 @@ impl From for ZAllocError { } } -/// Layouting errors -/// -/// INCORRECT_LAYOUT_ARGS: layout arguments are incorrect -/// PROVIDER_INCOMPATIBLE_LAYOUT: layout incompatible with provider +/// @attention Unstable feature. +/// @brief Layouting errors #[repr(C)] #[derive(Clone, Copy)] pub enum z_layout_error_t { + /// Layout arguments are incorrect. INCORRECT_LAYOUT_ARGS, + /// Layout incompatible with provider. PROVIDER_INCOMPATIBLE_LAYOUT, } @@ -102,7 +102,8 @@ impl From for ZLayoutError { } } -/// An AllocAlignment. +/// @attention Unstable feature. +/// @brief An AllocAlignment. #[repr(C)] #[derive(Clone, Copy)] pub struct z_alloc_alignment_t { @@ -116,7 +117,8 @@ decl_c_type_inequal!( loaned(z_loaned_memory_layout_t), ); -/// Creates a new Memory Layout +/// @attention Unstable feature. +/// @brief Creates a new Memory Layout. #[no_mangle] pub extern "C" fn z_memory_layout_new( this: &mut MaybeUninit, @@ -143,19 +145,22 @@ fn create_memory_layout( MemoryLayout::new(size, alignment) } -/// Constructs Memory Layout in its gravestone value. +/// @attention Unstable feature. +/// @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); } -/// Returns ``true`` if `this` is valid. +/// @attention Unstable feature. +/// @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() } -/// Borrows Memory Layout +/// @attention Unstable feature. +/// @brief Borrows Memory Layout. #[no_mangle] #[allow(clippy::missing_safety_doc)] pub unsafe extern "C" fn z_memory_layout_loan( @@ -167,13 +172,15 @@ pub unsafe extern "C" fn z_memory_layout_loan( .as_loaned_c_type_ref() } -/// Deletes Memory Layout +/// @attention Unstable feature. +/// @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(); } -/// Extract data from Memory Layout +/// @attention Unstable feature. +/// @brief Extract data from Memory Layout. #[no_mangle] pub extern "C" fn z_memory_layout_get_data( out_size: &mut MaybeUninit, @@ -190,7 +197,8 @@ decl_c_type!( loaned(z_loaned_chunk_alloc_result_t), ); -/// Creates a new Chunk Alloc Result with Ok value +/// @attention Unstable feature. +/// @brief Creates a new Chunk Alloc Result with Ok value. #[no_mangle] pub extern "C" fn z_chunk_alloc_result_new_ok( this: &mut MaybeUninit, @@ -205,7 +213,8 @@ pub extern "C" fn z_chunk_alloc_result_new_ok( } } -/// Creates a new Chunk Alloc Result with Error value +/// @attention Unstable feature. +/// @brief Creates a new Chunk Alloc Result with Error value. #[no_mangle] pub extern "C" fn z_chunk_alloc_result_new_error( this: &mut MaybeUninit, @@ -215,7 +224,8 @@ pub extern "C" fn z_chunk_alloc_result_new_error( .write(Some(Err(alloc_error.into()))); } -/// Constructs Chunk Alloc Result in its gravestone value. +/// @attention Unstable feature. +/// @brief Constructs Chunk Alloc Result in its gravestone value. #[no_mangle] pub extern "C" fn z_internal_chunk_alloc_result_null( this_: &mut MaybeUninit, @@ -223,7 +233,8 @@ pub extern "C" fn z_internal_chunk_alloc_result_null( this_.as_rust_type_mut_uninit().write(None); } -/// Returns ``true`` if `this` is valid. +/// @attention Unstable feature. +/// @return ``true`` if `this` is valid. #[no_mangle] pub extern "C" fn z_internal_chunk_alloc_result_check( this_: &z_owned_chunk_alloc_result_t, @@ -231,7 +242,8 @@ pub extern "C" fn z_internal_chunk_alloc_result_check( this_.as_rust_type_ref().is_some() } -/// Borrows Chunk Alloc Result +/// @attention Unstable feature. +/// @brief Borrows Chunk Alloc Result. #[no_mangle] #[allow(clippy::missing_safety_doc)] pub unsafe extern "C" fn z_chunk_alloc_result_loan( @@ -243,13 +255,15 @@ pub unsafe extern "C" fn z_chunk_alloc_result_loan( .as_loaned_c_type_ref() } -/// Deletes Chunk Alloc Result +/// @attention Unstable feature. +/// @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(); } -/// Status of SHM buffer allocation operation +/// @attention Unstable feature. +/// @brief Status of SHM buffer allocation operation. #[repr(C)] #[derive(Clone, Copy, Debug)] pub enum zc_buf_alloc_status_t { @@ -259,7 +273,8 @@ pub enum zc_buf_alloc_status_t { ALLOC_ERROR = 1, } -/// A result of SHM buffer allocation operation +/// @attention Unstable feature. +/// @brief A result of SHM buffer allocation operation. #[repr(C)] pub struct z_buf_alloc_result_t { status: zc_buf_alloc_status_t, @@ -293,7 +308,8 @@ impl From for z_buf_alloc_result_t { } } -/// Status of SHM buffer layouting + allocation operation +/// @attention Unstable feature. +/// @brief Status of SHM buffer layouting + allocation operation. #[repr(C)] #[derive(Clone, Copy, Debug)] pub enum zc_buf_layout_alloc_status_t { @@ -305,7 +321,8 @@ pub enum zc_buf_layout_alloc_status_t { LAYOUT_ERROR = 2, } -/// A result of SHM buffer layouting + allocation operation +/// @attention Unstable feature. +/// @brief A result of SHM buffer layouting + allocation operation. #[repr(C)] pub struct z_buf_layout_alloc_result_t { status: zc_buf_layout_alloc_status_t,