From 1509aeeac16fc1eb3c96ea7b5b65d36bb3178e54 Mon Sep 17 00:00:00 2001 From: Michael Ilyin Date: Wed, 2 Aug 2023 18:45:20 +0200 Subject: [PATCH] queryable, publisher, hello documented --- docs/api.rst | 1 + docs/data.rst | 9 ++++ docs/entities.rst | 34 ++++++++++++ include/zenohcxx/api.hxx | 112 ++++++++++++++++++++++++++++++++------- 4 files changed, 137 insertions(+), 19 deletions(-) create mode 100644 docs/entities.rst diff --git a/docs/api.rst b/docs/api.rst index 64e3e2ea..2cf97c7d 100644 --- a/docs/api.rst +++ b/docs/api.rst @@ -25,6 +25,7 @@ API Reference generic keyexpr config + entities data shm options diff --git a/docs/data.rst b/docs/data.rst index 1a81680b..bbe802a1 100644 --- a/docs/data.rst +++ b/docs/data.rst @@ -17,6 +17,10 @@ Data The classes representing the data which is sent and received through the network +.. doxygenclass:: zenoh::Hello + :members: + :membergroups: Constructors Operators Methods + .. doxygenstruct:: zenoh::HelloView :members: :membergroups: Constructors Operators Methods @@ -28,3 +32,8 @@ The classes representing the data which is sent and received through the network .. doxygenclass:: zenoh::Query :members: :membergroups: Constructors Operators Methods + +.. doxygenclass:: zenoh::Reply + :members: + :membergroups: Constructors Operators Methods + diff --git a/docs/entities.rst b/docs/entities.rst new file mode 100644 index 00000000..98c2ad72 --- /dev/null +++ b/docs/entities.rst @@ -0,0 +1,34 @@ +.. +.. Copyright (c) 2023 ZettaScale Technology +.. +.. This program and the accompanying materials are made available under the +.. terms of the Eclipse Public License 2.0 which is available at +.. http://www.eclipse.org/legal/epl-2.0, or the Apache License, Version 2.0 +.. which is available at https://www.apache.org/licenses/LICENSE-2.0. +.. +.. SPDX-License-Identifier: EPL-2.0 OR Apache-2.0 +.. +.. Contributors: +.. ZettaScale Zenoh Team, +.. + +Entities +======== + +The classes which performs the Zenoh network operations + +.. doxygenclass:: zenoh::Subscriber + :members: + :membergroups: Constructors Operators Methods + +.. doxygenclass:: zenoh::PullSubscriber + :members: + :membergroups: Constructors Operators Methods + +.. doxygenclass:: zenoh::Queryable + :members: + :membergroups: Constructors Operators Methods + +.. doxygenclass:: zenoh::Publisher + :members: + :membergroups: Constructors Operators Methods \ No newline at end of file diff --git a/include/zenohcxx/api.hxx b/include/zenohcxx/api.hxx index 5d497d9c..5a9f1ba0 100644 --- a/include/zenohcxx/api.hxx +++ b/include/zenohcxx/api.hxx @@ -306,7 +306,7 @@ struct Id : public Copyable<::z_id_t> { /// @return the output stream std::ostream& operator<<(std::ostream& os, const z::Id& id); -/// The non-owning read-only view to a "hello" message returned by a zenoh entity as a reply to a "scout" +/// The non-owning read-only view to a ``Hello`` message returned by a zenoh entity as a reply to a "scout" /// message. struct HelloView : public Copyable<::z_hello_t> { using Copyable::Copyable; @@ -558,6 +558,7 @@ struct Timestamp : Copyable<::z_timestamp_t> { /// Reference to data buffer in shared memory with reference counting. When all instances of ``Payload`` are destroyed, /// the buffer is freed. /// It can be convenient if it's necessary to resend the buffer to one or multiple receivers without copying it. +/// This can be performed with ``Publisher::put_owned`` method. /// /// @note zenoh-c only class Payload : public Owned<::zc_owned_payload_t> { @@ -1498,13 +1499,19 @@ std::variant config_client(const z::StrArrayView& peers std::variant config_client(const std::initializer_list& peers); #endif -// -// An owned reply to get operation -// +/// An owned reply from queryable to ``Session::get`` operation class Reply : public Owned<::z_owned_reply_t> { public: using Owned::Owned; + + /// @name Methods + + /// @brief Check if the reply is OK + /// @return true if the reply is OK bool is_ok() const { return ::z_reply_is_ok(&_0); } + + /// @brief Get the reply value + /// @return the ``Sample`` value of the reply if reply is OK, otherwise ``zenoh::ErrorMessage`` std::variant get() const { if (is_ok()) { return z::Sample{::z_reply_ok(&_0)}; @@ -1514,54 +1521,118 @@ class Reply : public Owned<::z_owned_reply_t> { } }; -// -// An owned zenoh subscriber. Destroying subscriber cancels the subscription -// +/// An owned zenoh subscriber. Destroying subscriber cancels the subscription +/// Constructed by ``Session::declare_subscriber`` method class Subscriber : public Owned<::z_owned_subscriber_t> { public: using Owned::Owned; }; -// -// An owned zenoh pull subscriber. Destroying the subscriber cancels the subscription. -// +/// An owned zenoh pull subscriber. Destroying the subscriber cancels the subscription. +/// Constructed by ``Session::declare_pull_subscriber`` method class PullSubscriber : public Owned<::z_owned_pull_subscriber_t> { public: using Owned::Owned; + + /// @name Methods + + /// @brief Pull the next sample + /// @return true if the sample was pulled, false otherwise bool pull() { return ::z_subscriber_pull(::z_loan(_0)) == 0; } + + /// @brief Pull the next sample + /// @param error the error code + /// @return true if the sample was pulled, false otherwise bool pull(ErrNo& error) { error = ::z_subscriber_pull(::z_loan(_0)); return error == 0; } }; -// -// An owned zenoh queryable -// +/// An owned zenoh queryable. Constructed by ``Session::declare_queryable`` method class Queryable : public Owned<::z_owned_queryable_t> { public: using Owned::Owned; }; -// -// An owned zenoh publisher -// +/// An owned zenoh publisher. Constructed by ``Session::declare_publisher`` method class Publisher : public Owned<::z_owned_publisher_t> { public: using Owned::Owned; + + /// @name Methods + + /// @brief Publish the payload + /// @param payload ``Payload`` to publish + /// @param options ``PublisherPutOptions`` + /// @param error the error code ``zenoh::ErrNo`` + /// @return true if the payload was published, false otherwise bool put(const z::BytesView& payload, const z::PublisherPutOptions& options, ErrNo& error); + + /// @brief Publish the payload + /// @param payload ``Payload`` to publish + /// @param error the error code ``zenoh::ErrNo`` + /// @return true if the payload was published, false otherwise bool put(const z::BytesView& payload, ErrNo& error); + + /// @brief Publish the payload + /// @param payload ``Payload`` to publish + /// @param options ``PublisherPutOptions`` + /// @return true if the payload was published, false otherwise bool put(const z::BytesView& payload, const z::PublisherPutOptions& options); + + /// @brief Publish the payload + /// @param payload ``Payload`` to publish + /// @return true if the payload was published, false otherwise bool put(const z::BytesView& payload); + + /// @brief Send a delete request + /// @param options ``PublisherDeleteOptions`` + /// @param error the error code ``zenoh::ErrNo`` + /// @return true if the request was sent, false otherwise bool delete_resource(const z::PublisherDeleteOptions& options, ErrNo& error); + + /// @brief Send a delete request + /// @param error the error code ``zenoh::ErrNo`` + /// @return true if the request was sent, false otherwise bool delete_resource(ErrNo& error); + + /// @brief Send a delete request + /// @param options ``PublisherDeleteOptions`` + /// @return true if the request was sent, false otherwise bool delete_resource(const z::PublisherDeleteOptions& options); + + /// @brief Send a delete request + /// @return true if the request was sent, false otherwise bool delete_resource(); #ifdef __ZENOHCXX_ZENOHC + /// @brief Publish the payload got from ``ShmBuf`` or from ``Sample`` + /// @param payload ``Payload`` to publish + /// @param options ``PublisherPutOptions`` + /// @param error the error code ``zenoh::ErrNo`` + /// @return true if the payload was published, false otherwise + /// @note zenoh-c only bool put_owned(z::Payload&& payload, const z::PublisherPutOptions& options, ErrNo& error); + + /// @brief Publish the payload got from ``ShmBuf`` or from ``Sample`` + /// @param payload ``Payload`` to publish + /// @param error the error code ``zenoh::ErrNo`` + /// @return true if the payload was published, false otherwise + /// @note zenoh-c only bool put_owned(z::Payload&& payload, ErrNo& error); + + /// @brief Publish the payload got from ``ShmBuf`` or from ``Sample`` + /// @param payload ``Payload`` to publish + /// @param options ``PublisherPutOptions`` + /// @return true if the payload was published, false otherwise + /// @note zenoh-c only bool put_owned(z::Payload&& payload, const z::PublisherPutOptions& options); + + /// @brief Publish the payload got from ``ShmBuf`` or from ``Sample`` + /// @param payload ``Payload`` to publish + /// @return true if the payload was published, false otherwise + /// @note zenoh-c only bool put_owned(z::Payload&& payload); #endif @@ -1573,12 +1644,15 @@ class Publisher : public Owned<::z_owned_publisher_t> { #endif }; -// -// A zenoh-allocated hello message returned by a zenoh entity to a scout message sent with scout operation -// +/// A zenoh-allocated hello message returned by a zenoh entity to a scout message sent with scout operation class Hello : public Owned<::z_owned_hello_t> { public: using Owned::Owned; + + /// @name Operators + + /// @brief Get the content of the hello message + /// @return the content of the hello message as ``HelloView`` operator z::HelloView() const { return z::HelloView(::z_hello_loan(&_0)); } };