added docs for channels and examples

docs/api.rst

@@ -28,5 +28,4 @@ API Reference
    publish_subscribe
    query_reply
    serialization_deserialization
-
    channels

docs/channels.rst

@@ -15,8 +15,18 @@
 Channels
 ========
 
-The functions allowing to receive data in synchronous mode, without a callback
+Classes providing stream interface for Zenoh messages.
 
-.. doxygenfunction:: reply_fifo_new
+.. doxygenclass:: zenoh::channels::FifoChannel
+    :members:
 
-.. doxygenfunction:: reply_non_blocking_fifo_new
+.. doxygenclass:: zenoh::channels::FifoHandler
+   :members:
+   :membergroups: Constructors Operators Methods
+
+.. doxygenclass:: zenoh::channels::RingChannel
+    :members:
+
+.. doxygenclass:: zenoh::channels::RingHandler
+   :members:
+   :membergroups: Constructors Operators Methods

docs/pubsub.rst

@@ -27,13 +27,13 @@ Publisher example:
 
    int main(int argc, char **argv) {
       Config config;
-      auto session = expect<Session>(open(std::move(config)));
+      auto session = Session::open(std::move(config));
       // Publish without creating a Publisher object
-      session.put("demo/example/simple", "Simple!");
+      session.put(KeyExpr("demo/example/simple"), Bytes::serialize("Simple!"));
 
       // Publish from a Publisher object
-      auto publisher = expect<Publisher>(session.declare_publisher("demo/example/simple"));
-      publisher.put("Simple!");
+      auto publisher = session.declare_publisher(KeyExpr("demo/example/simple"));
+      publisher.put(Bytes::serialize("Simple!"));
    }
 
 Subscriber example:
@@ -46,12 +46,41 @@ Subscriber example:
 
    int main(int argc, char **argv) {
       Config config;
-      auto session = expect<Session>(open(std::move(config)));
-      auto subscriber = expect<Subscriber>(
-         session.declare_subscriber("demo/example/simple", [](const Sample& sample) {
-            std::cout << "Received: " << sample.get_payload().as_string_view() << std::endl;
-         })
+      auto session = Session::open(std::move(config));
+      auto subscriber = session.declare_subscriber(
+         KeyExpr("demo/example/simple"), 
+         [](const Sample& sample) {
+            std::cout << "Received: " << sample.get_payload().deserialize<std::string>() << std::endl;
+         }
       );
       // Wait for a key press to exit
       char c = getchar();
    }
+
+Subscriber example with non-blocking stream interface:
+
+.. code-block:: c++
+
+   #include "zenoh.hxx"
+   #include <iostream>
+   #include <thread>
+   #include <chrono>
+   using namespace zenoh;
+   using namespace std::chrono_literals;
+
+   int main(int argc, char **argv) {
+      Config config;
+      auto session = Session::open(std::move(config));
+      auto subscriber = session.declare_subscriber(
+         KeyExpr("demo/example/simple"),
+         channels::FifoChannel(16), // use FIFO buffer to store unprocessed messages 
+      );
+      auto [sample, alive] = subscriber.handler().try_recv();
+      for (; alive; std::tie(sample, alive) = subscriber.handler().try_recv()) {
+         if (!sample) { // no messages in the buffer
+            std::this_thread::sleep_for(1s); // do some other work
+         } else {
+            std::cout << "Received: " << sample.get_payload().deserialize<std::string>() << std::endl;
+         }
+      }
+   }

docs/query_reply.rst

@@ -29,5 +29,9 @@ Classes related to query-reply pattern.
    :membergroups: Constructors Operators Methods
 
 .. doxygenclass:: zenoh::Reply
+   :members:
+   :membergroups: Constructors Operators Methods
+
+.. doxygenclass:: zenoh::ReplyError
    :members:
    :membergroups: Constructors Operators Methods

docs/queryable.rst

@@ -27,16 +27,17 @@ Queryable example:
    using namespace zenoh;
 
    int main(int argc, char **argv) {
-      auto queryable_keyexpr = "demo/example/simple";
+      auto queryable_keyexpr = KeyExpr("demo/example/simple");
       Config config;
-      auto session = expect<Session>(open(std::move(config)));
-      auto queryable = expect<Queryable>(
-         session.declare_queryable(queryable_keyexpr, [](const Query& query) {
-            std::cout << "Received Query '" 
-                      << query.get_keyexpr().as_string_view() 
-                      << "?" << query.get_parameters().as_string_view() << std::endl;
-            query.reply(queryable_expr, "42");
-         })
+      auto session = Session::open(std::move(config));
+      auto queryable = session.declare_queryable(
+            queryable_keyexpr, 
+            [&queryable_expr](const Query& query) {
+               std::cout << "Received Query '" 
+                        << query.get_keyexpr().as_string_view() 
+                        << "?" << query.get_parameters() << std::endl;
+               query.reply(queryable_expr, Bytes::serialize("42"));
+         }
       );
       // Wait for a key press to exit
       c = getchar();
@@ -52,15 +53,17 @@ Also notice that the callback is processed asynchronously, so the client must no
 
    int main(int argc, char **argv) {
       Config config;
-      auto session = expect<Session>(open(std::move(config)));
-
-      auto on_reply = [](Reply&& reply) {
-         auto result = reply.get();
-         if (auto sample = std::get_if<Sample>(&result)) {
-            std::cout << "Received ('" << sample->get_keyexpr().as_string_view() << "' : '"
-                      << sample->get_payload().as_string_view() << "')\n";
-         } else if (auto error = std::get_if<ErrorMessage>(&result)) {
-            std::cout << "Received an error :" << error->as_string_view() << "\n";
+      auto session = Session::open(std::move(config));
+
+      auto on_reply = [](const Reply& reply) {
+         if (reply.is_ok()) {
+            auto&& sample = reply.get_ok();
+            std::cout << "Received ('" << sample.get_keyexpr().as_string_view() << "' : '"
+                      << sample.get_payload().deserialize<std::string>() << "')\n";
+         } else {
+            auto&& err = reply.get_err();
+            std::cout << "Received an error :" 
+                      << error.get_payload().deserialzie<std::string>() << "\n";
          }
       };
 
@@ -70,9 +73,41 @@ Also notice that the callback is processed asynchronously, so the client must no
 
       // Send a query and pass two callbacks: one for processing the reply 
       // and one for handle the end of replies
-      session.get("demo/example/simple", {on_reply, on_done});
+      session.get(KeyExpr("demo/example/simple"), "", on_reply, on_done);
 
       // Do not exit immediately, give time to process replies
       // Better to wait on a mutex signalled by the on_done callback
       c = getchar();
    }
+
+Client example using blocking stream interface. Notice that reply callback may receive error message instead of a sample.
+Also notice that the callback is processed asynchronously, so the client must not exit immediately.
+
+.. code-block:: c++
+
+   #include "zenoh.hxx"
+   using namespace zenoh;
+
+   int main(int argc, char **argv) {
+      Config config;
+      auto session = Session::open(std::move(config));
+
+      // Send a query and receive a stream providing replies.
+      // We will receive a FIFO buffer to store unprocessed replies (with size of 16).
+      auto replies = session.get(KeyExpr("demo/example/simple"), "", channels::FifoChannel(16));
+      auto&& [reply, is_alive] = replies.recv()
+      for (; is_alive; std::tie(reply, is_alive) = replies.recv()) {
+      // is_alive will become false once there are no more replies to process, termianting the loop
+         if (reply.is_ok()) {
+            auto&& sample = reply.get_ok();
+            std::cout << "Received ('" << sample.get_keyexpr().as_string_view() << "' : '"
+                      << sample.get_payload().deserialize<std::string>() << "')\n";
+         } else {
+            auto&& err = reply.get_err();
+            std::cout << "Received an error :" 
+                      << error.get_payload().deserialzie<std::string>() << "\n";
+         }
+      }
+
+      std::cout << "No more replies" << std::endl;
+   }

docs/serialization_deserialization.rst

@@ -13,7 +13,7 @@
 ..
 
 Serialization/Deserialziation
-=================
+=============================
 .. doxygenclass:: zenoh::Bytes
    :members:
    :membergroups: Constructors Operators Methods

docs/session.rst

@@ -25,10 +25,3 @@ Session
    :members:
    :membergroups: Constructors Operators Methods Fields
 
-Scouting
---------
-
-.. doxygenstruct:: zenoh::ScoutOptions
-   :members:
-
-.. doxygenfunction:: zenoh::scout

docs/session_ex.rst

@@ -15,8 +15,9 @@
 Session
 =======
 
-The zenoh session is created using the :cpp:func:`zenoh::open` function, 
+The zenoh session is created using the :cpp:func:`zenoh::Session::open` function, 
 consuming the configuration object :cpp:class:`zenoh::Config`.
+Then a string is published on "demo/example/simple" key expression.
 
 .. code-block:: c++
 
@@ -26,11 +27,9 @@ consuming the configuration object :cpp:class:`zenoh::Config`.
    int main(int argc, char **argv) {
       try {
          Config config;
-         // take Session from std::variant
-         auto session = expect<Session>(open(std::move(config)));
-         session.put("demo/example/simple", "Simple!");
-      } catch (ErrorMessage e) {
-         // Exception comes from ``expect``, the zenoh-cpp itself does not throw any exception
-         std::cout << "Received an error :" << e.as_string_view() << "\n";
+         auto session = Session::open(std::move(config));
+         session.put(KeyExpr("demo/example/simple"), Bytes::serialize("Simple!"));
+      } catch (ZException e) {
+         std::cout << "Received an error :" << e.what() << "\n";
       }
    }