Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

mark unstable features in the docs #207

Merged
merged 1 commit into from
Sep 10, 2024
Merged
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
3 changes: 2 additions & 1 deletion include/zenoh/api/enums.hxx
Original file line number Diff line number Diff line change
@@ -99,7 +99,8 @@ inline std::string_view whatami_as_str(WhatAmI whatami) {
}

#if defined(ZENOHCXX_ZENOHC) && defined(UNSTABLE)
/// The locality of samples to be received by subscribers or targeted by publishers.
/// @warning This API has been marked as unstable: it works as advertised, but it may be changed in a future release.
/// @brief The locality of samples to be received by subscribers or targeted by publishers.
///
/// Values:
/// - **ZC_LOCALITY_ANY**: Any.
2 changes: 2 additions & 0 deletions include/zenoh/api/hello.hxx
Original file line number Diff line number Diff line change
@@ -31,6 +31,8 @@ class Hello : public Owned<::z_owned_hello_t> {
/// @name Methods

#if defined UNSTABLE
/// @warning This API has been marked as unstable: it works as advertised, but it may be changed in a future
/// release.
/// @brief Get ``Id`` of the entity.
/// @return ``Id`` of the entity.
Id get_id() const { return interop::into_copyable_cpp_obj<Id>(::z_hello_zid(interop::as_loaned_c_ptr(*this))); };
2 changes: 2 additions & 0 deletions include/zenoh/api/id.hxx
Original file line number Diff line number Diff line change
@@ -22,6 +22,7 @@
#include "interop.hxx"

namespace zenoh {
/// @warning This API has been marked as unstable: it works as advertised, but it may be changed in a future release.
/// @brief A representation a Zenoh ID.
///
/// In general, valid Zenoh IDs are LSB-first 128bit unsigned and non-zero integers.
@@ -40,6 +41,7 @@ class Id : public Copyable<::z_id_t> {
const std::array<uint8_t, 16>& bytes() const { return *reinterpret_cast<const std::array<uint8_t, 16>*>(&_0.id); }
};

/// @warning This API has been marked as unstable: it works as advertised, but it may be changed in a future release.
/// @brief Print ``Id`` in the hex format.
inline std::ostream& operator<<(std::ostream& os, const Id& id) {
auto id_ptr = reinterpret_cast<const ::z_id_t*>(&id)->id;
5 changes: 3 additions & 2 deletions include/zenoh/api/keyexpr.hxx
Original file line number Diff line number Diff line change
@@ -120,8 +120,9 @@ class KeyExpr : public Owned<::z_owned_keyexpr_t> {
return ::z_keyexpr_intersects(interop::as_loaned_c_ptr(*this), interop::as_loaned_c_ptr(other));
}
#if defined(UNSTABLE)
///
/// Intersection level of 2 key expressions.
/// @warning This API has been marked as unstable: it works as advertised, but it may be changed in a future
/// release.
/// @brief Intersection level of 2 key expressions.
///
/// Values:
/// - **Z_KEYEXPR_INTERSECTION_LEVEL_DISJOINT**: 2 key expression do not intersect.
3 changes: 2 additions & 1 deletion include/zenoh/api/liveliness.hxx
Original file line number Diff line number Diff line change
@@ -20,7 +20,8 @@ namespace zenoh {

class Session;

/// @brief // A liveliness token that can be used to provide the network with information about connectivity to its
/// @warning This API has been marked as unstable: it works as advertised, but it may be changed in a future release.
/// @brief A liveliness token that can be used to provide the network with information about connectivity to its
/// declarer.
///
/// When constructed, a PUT sample will be received by liveliness subscribers on intersecting key expressions.
4 changes: 4 additions & 0 deletions include/zenoh/api/publisher.hxx
Original file line number Diff line number Diff line change
@@ -44,6 +44,8 @@ class Publisher : public Owned<::z_owned_publisher_t> {
/// @brief the timestamp of this message.
std::optional<Timestamp> timestamp = {};
#if defined(ZENOHCXX_ZENOHC) && defined(UNSTABLE)
/// @warning This API has been marked as unstable: it works as advertised, but it may be changed in a future
/// release.
/// @brief The source info of this message.
std::optional<SourceInfo> source_info = {};
#endif
@@ -107,6 +109,8 @@ class Publisher : public Owned<::z_owned_publisher_t> {
}
#endif
#if defined(ZENOHCXX_ZENOHC) && defined(UNSTABLE)
/// @warning This API has been marked as unstable: it works as advertised, but it may be changed in a future
/// release.
/// @brief Get the id of the publisher.
/// @return id of this publisher.
EntityGlobalId get_id() const {
4 changes: 4 additions & 0 deletions include/zenoh/api/query.hxx
Original file line number Diff line number Diff line change
@@ -94,6 +94,8 @@ class Query : public Owned<::z_owned_query_t> {
/// @brief The timestamp of this message.
std::optional<Timestamp> timestamp = {};
#if defined(ZENOHCXX_ZENOHC) && defined(UNSTABLE)
/// @warning This API has been marked as unstable: it works as advertised, but it may be changed in a future
/// release.
/// @brief The source info of this reply message.
std::optional<SourceInfo> source_info = {};
#endif
@@ -171,6 +173,8 @@ class Query : public Owned<::z_owned_query_t> {
/// @brief the timestamp of this message.
std::optional<Timestamp> timestamp = {};
#if defined(ZENOHCXX_ZENOHC) && defined(UNSTABLE)
/// @warning This API has been marked as unstable: it works as advertised, but it may be changed in a future
/// release.
/// @brief The source info of this reply message.
std::optional<SourceInfo> source_info = {};
#endif
2 changes: 2 additions & 0 deletions include/zenoh/api/reply.hxx
Original file line number Diff line number Diff line change
@@ -72,6 +72,8 @@ class Reply : public Owned<::z_owned_reply_t> {
}

#if defined(UNSTABLE)
/// @warning This API has been marked as unstable: it works as advertised, but it may be changed in a future
/// release.
/// @brief Get the id of the Zenoh instance that issued this reply.
/// @return Zenoh instance id, or an empty optional if the id was not set.
std::optional<Id> get_replier_id() const {
4 changes: 4 additions & 0 deletions include/zenoh/api/sample.hxx
Original file line number Diff line number Diff line change
@@ -91,13 +91,17 @@ class Sample : public Owned<::z_owned_sample_t> {
/// @return ``CongestionControl`` value.
bool get_express() const { return ::z_sample_express(interop::as_loaned_c_ptr(*this)); }
#if defined(ZENOHCXX) && defined(UNSTABLE)
/// @warning This API has been marked as unstable: it works as advertised, but it may be changed in a future
/// release.
/// @brief Get the source info of this sample.
const SourceInfo& get_source_info() const {
return interop::as_owned_cpp_ref<SourceInfo>(::z_sample_source_info(interop::as_loaned_c_ptr(*this)));
}
#endif

#if defined(UNSTABLE)
/// @warning This API has been marked as unstable: it works as advertised, but it may be changed in a future
/// release.
/// @brief Get the reliability this sample was sent with.
/// @return ``Reliability`` value.
Reliability reliability() const { return ::z_sample_reliability(interop::as_loaned_c_ptr(*this)); }
20 changes: 20 additions & 0 deletions include/zenoh/api/session.hxx
Original file line number Diff line number Diff line change
@@ -131,6 +131,8 @@ class Session : public Owned<::z_owned_session_t> {
}

#if defined UNSTABLE
/// @warning This API has been marked as unstable: it works as advertised, but it may be changed in a future
/// release.
/// @brief Get the unique identifier of the zenoh node associated to this ``Session``.
/// @return the unique identifier ``Id``.
Id get_zid() const { return interop::into_copyable_cpp_obj<Id>(::z_info_zid(interop::as_loaned_c_ptr(*this))); }
@@ -178,6 +180,8 @@ class Session : public Owned<::z_owned_session_t> {
/// @brief An optional encoding of the query payload and/or attachment.
std::optional<Encoding> encoding = {};
#if defined(ZENOHCXX_ZENOHC) && defined(UNSTABLE)
/// @warning This API has been marked as unstable: it works as advertised, but it may be changed in a future
/// release.
/// @brief The source info for the query.
std::optional<SourceInfo> source_info = {};
#endif
@@ -278,6 +282,8 @@ class Session : public Owned<::z_owned_session_t> {
/// @brief Whether Zenoh will NOT wait to batch delete message with others to reduce the bandwith.
bool is_express = false;
#if defined(UNSTABLE)
/// @warning This API has been marked as unstable: it works as advertised, but it may be changed in a future
/// release.
/// @brief The delete operation reliability.
Reliability reliability = Reliability::Z_RELIABILITY_BEST_EFFORT;
#endif
@@ -320,6 +326,8 @@ class Session : public Owned<::z_owned_session_t> {
/// @brief Whether Zenoh will NOT wait to batch this message with others to reduce the bandwith.
bool is_express = false;
#if defined(ZENOHCXX_ZENOHC) && defined(UNSTABLE)
/// @warning This API has been marked as unstable: it works as advertised, but it may be changed in a future
/// release.
/// @brief Allowed destination.
Locality allowed_destination = ::zc_locality_default();
#endif
@@ -328,10 +336,14 @@ class Session : public Owned<::z_owned_session_t> {
/// @brief An optional encoding of the message payload and/or attachment.
std::optional<Encoding> encoding = {};
#if defined(UNSTABLE)
/// @warning This API has been marked as unstable: it works as advertised, but it may be changed in a future
/// release.
/// @brief The put operation reliability.
Reliability reliability = Reliability::Z_RELIABILITY_BEST_EFFORT;
#endif
#if defined(ZENOHCXX_ZENOHC) && defined(UNSTABLE)
/// @warning This API has been marked as unstable: it works as advertised, but it may be changed in a future
/// release.
/// @brief The source info of this message.
std::optional<SourceInfo> source_info = {};
#endif
@@ -529,10 +541,14 @@ class Session : public Owned<::z_owned_session_t> {
/// @brief If true, Zenoh will not wait to batch this message with others to reduce the bandwith.
bool is_express = false;
#if defined(UNSTABLE)
/// @warning This API has been marked as unstable: it works as advertised, but it may be changed in a future
/// release.
/// @brief The publisher reliability.
Reliability reliability = Reliability::Z_RELIABILITY_BEST_EFFORT;
#endif
#if defined(ZENOHCXX_ZENOHC) && defined(UNSTABLE)
/// @warning This API has been marked as unstable: it works as advertised, but it may be changed in a future
/// release.
/// @brief Allowed destination.
Locality allowed_destination = ::zc_locality_default();
#endif
@@ -574,6 +590,8 @@ class Session : public Owned<::z_owned_session_t> {
}

#if defined(ZENOHCXX_ZENOHC) && defined(UNSTABLE)
/// @warning This API has been marked as unstable: it works as advertised, but it may be changed in a future
/// release.
/// @brief Fetches the Zenoh IDs of all connected routers.
/// @param err if not null, the result code will be written to this location, otherwise ZException exception will be
/// thrown in case of error.
@@ -674,6 +692,8 @@ class Session : public Owned<::z_owned_session_t> {
#endif

#if defined(ZENOHCXX_ZENOHC) && defined(UNSTABLE)
/// @warning This API has been marked as unstable: it works as advertised, but it may be changed in a future
/// release.
/// @brief Options to pass to ``Session::liveliness_declare_token``.
struct LivelinessDeclarationOptions {
protected:
1 change: 1 addition & 0 deletions include/zenoh/api/shm/buffer/zshm.hxx
Original file line number Diff line number Diff line change
@@ -22,6 +22,7 @@

namespace zenoh {

/// @warning This API has been marked as unstable: it works as advertised, but it may be changed in a future release.
/// @brief An immutable SHM buffer
class ZShm : public Owned<::z_owned_shm_t> {
friend class ZShmMut;
1 change: 1 addition & 0 deletions include/zenoh/api/shm/buffer/zshmmut.hxx
Original file line number Diff line number Diff line change
@@ -18,6 +18,7 @@

namespace zenoh {

/// @warning This API has been marked as unstable: it works as advertised, but it may be changed in a future release.
/// @brief A mutable SHM buffer
class ZShmMut : public Owned<::z_owned_shm_mut_t> {
friend class ZShm;
2 changes: 2 additions & 0 deletions include/zenoh/api/shm/client/shm_client.hxx
Original file line number Diff line number Diff line change
@@ -22,6 +22,7 @@

namespace zenoh {

/// @warning This API has been marked as unstable: it works as advertised, but it may be changed in a future release.
/// @brief An interface for making custom SHM clients
class CppShmClient {
public:
@@ -46,6 +47,7 @@ inline void _z_cpp_shm_client_drop_fn(void* context) { delete static_cast<CppShm
}
} // namespace shm::client::closures

/// @warning This API has been marked as unstable: it works as advertised, but it may be changed in a future release.
/// @brief An SHM client for reading shared memory buffers
class ShmClient : public Owned<::z_owned_shm_client_t> {
friend class ShmClientStorage;
1 change: 1 addition & 0 deletions include/zenoh/api/shm/client/shm_segment.hxx
Original file line number Diff line number Diff line change
@@ -16,6 +16,7 @@

namespace zenoh {

/// @warning This API has been marked as unstable: it works as advertised, but it may be changed in a future release.
/// @brief An interface for accessing custom SHM segments
class CppShmSegment {
public:
1 change: 1 addition & 0 deletions include/zenoh/api/shm/client_storage/client_storage.hxx
Original file line number Diff line number Diff line change
@@ -22,6 +22,7 @@

namespace zenoh {

/// @warning This API has been marked as unstable: it works as advertised, but it may be changed in a future release.
/// @brief A storage for SHM clients. Session constructed with instance of this type
/// gets capabilities to read SHM buffers for Protocols added to this instance.
class ShmClientStorage : public Owned<::z_owned_shm_client_storage_t> {
Original file line number Diff line number Diff line change
@@ -17,6 +17,7 @@

namespace zenoh {

/// @warning This API has been marked as unstable: it works as advertised, but it may be changed in a future release.
/// @brief Client factory implementation for particular shared memory protocol
class PosixShmClient : public ShmClient {
public:
Original file line number Diff line number Diff line change
@@ -18,6 +18,7 @@

namespace zenoh {

/// @warning This API has been marked as unstable: it works as advertised, but it may be changed in a future release.
/// @brief An SHM provider implementing zenoh-standard POSIX shared memory protocol
class PosixShmProvider : public ShmProvider {
public:
1 change: 1 addition & 0 deletions include/zenoh/api/shm/provider/alloc_layout.hxx
Original file line number Diff line number Diff line change
@@ -46,6 +46,7 @@ inline void _z_alloc_layout_async_interface_drop_fn(void* context) {
}
} // namespace shm::provider::closures

/// @warning This API has been marked as unstable: it works as advertised, but it may be changed in a future release.
class AllocLayout : public Owned<::z_owned_alloc_layout_t> {
public:
/// @name Constructors
6 changes: 4 additions & 2 deletions include/zenoh/api/shm/provider/chunk.hxx
Original file line number Diff line number Diff line change
@@ -15,10 +15,12 @@

namespace zenoh {

/// A ChunkDescriptor
/// @warning This API has been marked as unstable: it works as advertised, but it may be changed in a future release.
/// @brief A ChunkDescriptor.
typedef z_chunk_descriptor_t ChunkDescriptor;

/// An AllocatedChunk
/// @warning This API has been marked as unstable: it works as advertised, but it may be changed in a future release.
/// @brief An AllocatedChunk.
typedef z_allocated_chunk_t AllocatedChunk;

} // end of namespace zenoh
1 change: 1 addition & 0 deletions include/zenoh/api/shm/provider/shm_provider.hxx
Original file line number Diff line number Diff line change
@@ -104,6 +104,7 @@ class ShmProvider : public Owned<::z_owned_shm_provider_t> {
}
};

/// @warning This API has been marked as unstable: it works as advertised, but it may be changed in a future release.
class CppShmProvider : public ShmProvider {
friend class AllocLayout;

37 changes: 20 additions & 17 deletions include/zenoh/api/shm/provider/types.hxx
Original file line number Diff line number Diff line change
@@ -21,26 +21,26 @@

namespace zenoh {

/**
* Allocation errors
*
* - **NEED_DEFRAGMENT**: defragmentation needed
* - **OUT_OF_MEMORY**: the provider is out of memory
* - **OTHER**: other error
*/
/// @warning This API has been marked as unstable: it works as advertised, but it may be changed in a future release.
/// @brief Allocation errors.
///
/// - **NEED_DEFRAGMENT**: defragmentation needed
/// - **OUT_OF_MEMORY**: the provider is out of memory
/// - **OTHER**: other error
typedef ::z_alloc_error_t AllocError;

/**
* Layouting errors
*
* Z_LAYOUT_ERROR_INCORRECT_LAYOUT_ARGS: layout arguments are incorrect
* Z_LAYOUT_ERROR_PROVIDER_INCOMPATIBLE_LAYOUT: layout incompatible with provider
*/
/// @warning This API has been marked as unstable: it works as advertised, but it may be changed in a future release.
/// @brief Layouting errors.
///
/// * Z_LAYOUT_ERROR_INCORRECT_LAYOUT_ARGS: layout arguments are incorrect
/// * Z_LAYOUT_ERROR_PROVIDER_INCOMPATIBLE_LAYOUT: layout incompatible with provider
typedef ::z_layout_error_t LayoutError;

/// An AllocAlignment.
/// @warning This API has been marked as unstable: it works as advertised, but it may be changed in a future release.
/// @brief An AllocAlignment.
typedef ::z_alloc_alignment_t AllocAlignment;

/// @warning This API has been marked as unstable: it works as advertised, but it may be changed in a future release.
class MemoryLayout : public Owned<::z_owned_memory_layout_t> {
friend class PosixShmProvider;
MemoryLayout(zenoh::detail::null_object_t) : Owned(nullptr) {}
@@ -74,7 +74,8 @@ class MemoryLayout : public Owned<::z_owned_memory_layout_t> {
}
};

/// SHM chunk allocation result
/// @warning This API has been marked as unstable: it works as advertised, but it may be changed in a future release.
/// @brief SHM chunk allocation result
class ChunkAllocResult : public Owned<::z_owned_chunk_alloc_result_t> {
friend class CppShmProviderBackend;

@@ -90,10 +91,12 @@ class ChunkAllocResult : public Owned<::z_owned_chunk_alloc_result_t> {
ChunkAllocResult(AllocError error) : Owned(nullptr) { ::z_chunk_alloc_result_new_error(&this->_0, error); }
};

/// SHM buffer allocation result
/// @warning This API has been marked as unstable: it works as advertised, but it may be changed in a future release.
/// @brief SHM buffer allocation result
typedef std::variant<ZShmMut, AllocError> BufAllocResult;

/// SHM buffer layouting and allocation result
/// @warning This API has been marked as unstable: it works as advertised, but it may be changed in a future release.
/// @brief SHM buffer layouting and allocation result
typedef std::variant<ZShmMut, AllocError, LayoutError> BufLayoutAllocResult;

} // end of namespace zenoh
4 changes: 3 additions & 1 deletion include/zenoh/api/source_info.hxx
Original file line number Diff line number Diff line change
@@ -22,7 +22,8 @@

namespace zenoh {
#ifdef ZENOHCXX_ZENOHC
/// The global unique id of a Zenoh entity.
/// @warning This API has been marked as unstable: it works as advertised, but it may be changed in a future release.
/// @brief The global unique id of a Zenoh entity.
class EntityGlobalId : public Copyable<::z_entity_global_id_t> {
using Copyable::Copyable;
friend struct interop::detail::Converter;
@@ -37,6 +38,7 @@ class EntityGlobalId : public Copyable<::z_entity_global_id_t> {
uint32_t eid() const { return ::z_entity_global_id_eid(&this->inner()); }
};

/// @warning This API has been marked as unstable: it works as advertised, but it may be changed in a future release.
/// @brief Informations on the Zenoh source.
class SourceInfo : public Owned<::z_owned_source_info_t> {
public:
2 changes: 2 additions & 0 deletions include/zenoh/api/timestamp.hxx
Original file line number Diff line number Diff line change
@@ -33,6 +33,8 @@ class Timestamp : public Copyable<::z_timestamp_t> {
uint64_t get_time() const { return ::z_timestamp_ntp64_time(&this->inner()); }

#if defined UNSTABLE
/// @warning This API has been marked as unstable: it works as advertised, but it may be changed in a future
/// release.
/// @brief Get the unique id of the timestamp.
/// @return Id associated with this timestamp.
Id get_id() const { return interop::into_copyable_cpp_obj<Id>(::z_timestamp_id(&this->inner())); }