Add channels

docs/api.rst

@@ -530,6 +530,131 @@ See details at :ref:`owned_types_concept`
 .. c:function:: void z_closure_zid_drop(z_moved_closure_zid_t * closure) 
 
 
+.. _channels_concept:
+
+Channels
+========
+
+The concept of channels and handlers revolves around managing communication between different components using two types of channels: FIFO (First-In-First-Out) and Ring Buffers. These channels support handling various item types such as sample, reply, and query, with distinct methods available for each.
+
+The FIFO channel ensures that data is received in the order it was sent. It supports blocking and non-blocking (try) reception of data.
+If the channel is dropped, the handlers transition into a "gravestone" state, signifying that no more data will be sent or received.
+
+The Ring channel differs from FIFO in that data is overwritten if the buffer is full, but it still supports blocking and non-blocking reception of data. As with the FIFO channel, the handler can be dropped, resetting it to a gravestone state.
+
+The methods are common for all channles:
+
+- `z_yyy_channel_xxx_new`: Constructs the send and receive ends of the `yyy` (`fifo` or `ring`) channel for items type `xxx`.
+- `z_yyy_handler_xxx_recv`: Receives an item from the channel (blocking). If no more items are available or the channel is dropped, the item transitions to the gravestone state.
+- `z_yyy_handler_xxx_try_recv`: Attempts to receive an item immediately (non-blocking). Returns a gravestone state if no data is available.
+- `z_yyy_handler_xxx_loan`: Borrows the handler for access.
+- `z_yyy_handler_xxx_drop`: Drops the the handler, setting it to a gravestone state.
+
+
+Sample channel
+--------------
+
+Types
+^^^^^
+
+See details at :ref:`owned_types_concept`
+
+.. c:type:: z_owned_fifo_handler_sample_t
+.. c:type:: z_loaned_fifo_handler_sample_t
+.. c:type:: z_owned_ring_handler_sample_t
+.. c:type:: z_loaned_ring_handler_sample_t
+
+Methods
+^^^^^^^
+.. c:function:: void z_fifo_channel_sample_new(z_owned_closure_sample_t * callback, z_owned_fifo_handler_sample_t * handler, size_t capacity)
+.. c:function:: void z_ring_channel_sample_new(z_owned_closure_sample_t * callback, z_owned_ring_handler_sample_t * handler, size_t capacity)
+
+See details at :ref:`channels_concept`
+
+.. c:function:: z_result_t z_fifo_handler_sample_recv(const z_loaned_fifo_handler_sample_t * handler, z_owned_sample_t * sample) 
+.. c:function:: z_result_t z_fifo_handler_sample_try_recv(const z_loaned_fifo_handler_sample_t * handler, z_owned_sample_t * sample) 
+.. c:function:: z_result_t z_ring_handler_sample_recv(const z_loaned_ring_handler_sample_t * handler, z_owned_sample_t * sample) 
+.. c:function:: z_result_t z_ring_handler_sample_try_recv(const z_loaned_ring_handler_sample_t * handler, z_owned_sample_t * sample) 
+
+See details at :ref:`channels_concept`
+
+.. c:function:: const z_loaned_fifo_handler_sample_t * z_fifo_handler_sample_loan(const z_owned_fifo_handler_sample_t * handler) 
+.. c:function:: void z_fifo_handler_sample_drop(z_moved_fifo_handler_sample_t * handler) 
+.. c:function:: const z_loaned_ring_handler_sample_t * z_ring_handler_sample_loan(const z_owned_ring_handler_sample_t * handler) 
+.. c:function:: void z_ring_handler_sample_drop(z_moved_ring_handler_sample_t * handler) 
+
+See details at :ref:`owned_types_concept`
+
+
+Query channel
+-------------
+
+Types
+^^^^^
+
+See details at :ref:`owned_types_concept`
+
+.. c:type:: z_owned_fifo_handler_query_t
+.. c:type:: z_loaned_fifo_handler_query_t
+.. c:type:: z_owned_ring_handler_query_t
+.. c:type:: z_loaned_ring_handler_query_t
+
+Methods
+^^^^^^^
+.. c:function:: void z_fifo_channel_query_new(z_owned_closure_query_t * callback, z_owned_fifo_handler_query_t * handler, size_t capacity)
+.. c:function:: void z_ring_channel_query_new(z_owned_closure_query_t * callback, z_owned_ring_handler_query_t * handler, size_t capacity)
+
+See details at :ref:`channels_concept`
+
+.. c:function:: z_result_t z_fifo_handler_query_recv(const z_loaned_fifo_handler_query_t * handler, z_owned_query_t * query) 
+.. c:function:: z_result_t z_fifo_handler_query_try_recv(const z_loaned_fifo_handler_query_t * handler, z_owned_query_t * query) 
+.. c:function:: z_result_t z_ring_handler_query_recv(const z_loaned_ring_handler_query_t * handler, z_owned_query_t * query) 
+.. c:function:: z_result_t z_ring_handler_query_try_recv(const z_loaned_ring_handler_query_t * handler, z_owned_query_t * query) 
+
+See details at :ref:`channels_concept`
+
+.. c:function:: const z_loaned_fifo_handler_query_t * z_fifo_handler_query_loan(const z_owned_fifo_handler_query_t * handler) 
+.. c:function:: void z_fifo_handler_query_drop(z_moved_fifo_handler_query_t * handler) 
+.. c:function:: const z_loaned_ring_handler_query_t * z_ring_handler_query_loan(const z_owned_ring_handler_query_t * handler) 
+.. c:function:: void z_ring_handler_query_drop(z_moved_ring_handler_query_t * handler) 
+
+See details at :ref:`owned_types_concept`
+
+Reply channel
+-------------
+
+Types
+^^^^^
+
+See details at :ref:`owned_types_concept`
+
+.. c:type:: z_owned_fifo_handler_reply_t
+.. c:type:: z_loaned_fifo_handler_reply_t
+.. c:type:: z_owned_ring_handler_reply_t
+.. c:type:: z_loaned_ring_handler_reply_t
+
+Methods
+^^^^^^^
+.. c:function:: void z_fifo_channel_reply_new(z_owned_closure_reply_t * callback, z_owned_fifo_handler_reply_t * handler, size_t capacity)
+.. c:function:: void z_ring_channel_reply_new(z_owned_closure_reply_t * callback, z_owned_ring_handler_reply_t * handler, size_t capacity)
+
+See details at :ref:`channels_concept`
+
+.. c:function:: z_result_t z_fifo_handler_reply_recv(const z_loaned_fifo_handler_reply_t * handler, z_owned_reply_t * reply) 
+.. c:function:: z_result_t z_fifo_handler_reply_try_recv(const z_loaned_fifo_handler_reply_t * handler, z_owned_reply_t * reply) 
+.. c:function:: z_result_t z_ring_handler_reply_recv(const z_loaned_ring_handler_reply_t * handler, z_owned_reply_t * reply) 
+.. c:function:: z_result_t z_ring_handler_reply_try_recv(const z_loaned_ring_handler_reply_t * handler, z_owned_reply_t * reply) 
+
+See details at :ref:`channels_concept`
+
+.. c:function:: const z_loaned_fifo_handler_reply_t * z_fifo_handler_reply_loan(const z_owned_fifo_handler_reply_t * handler) 
+.. c:function:: void z_fifo_handler_reply_drop(z_moved_fifo_handler_reply_t * handler) 
+.. c:function:: const z_loaned_ring_handler_reply_t * z_ring_handler_reply_loan(const z_owned_ring_handler_reply_t * handler) 
+.. c:function:: void z_ring_handler_reply_drop(z_moved_ring_handler_reply_t * handler) 
+
+See details at :ref:`owned_types_concept`
+
+
 System
 ======
 Random
@@ -781,6 +906,7 @@ Types
 -----
 
 Represents a Zenoh Subscriber entity.
+See details at :ref:`owned_types_concept`
 
 .. c:type:: z_owned_subscriber_t
 .. c:type:: z_loaned_subscriber_t
@@ -791,11 +917,6 @@ Option Types
 
 .. autoctype:: types.h::z_subscriber_options_t
 
-.. TODO .. c:type:: z_owned_fifo_handler_sample_t
-.. TODO .. c:type:: z_loaned_fifo_handler_sample_t
-.. TODO .. c:type:: z_owned_ring_handler_sample_t
-.. TODO .. c:type:: z_loaned_ring_handler_sample_t
-
 Functions
 ---------
 
@@ -805,19 +926,6 @@ Functions
 .. autocfunction:: primitives.h::z_subscriber_options_default
 .. autocfunction:: primitives.h::z_subscriber_keyexpr
 
-.. TODO .. autocfunction:: primitives.h::z_fifo_channel_sample_new
-.. TODO .. autocfunction:: primitives.h::z_ring_channel_sample_new
-
-.. TODO .. autocfunction:: primitives.h::z_fifo_handler_sample_drop
-.. TODO .. autocfunction:: primitives.h::z_fifo_handler_sample_loan
-.. TODO .. autocfunction:: primitives.h::z_fifo_handler_sample_recv
-.. TODO .. autocfunction:: primitives.h::z_fifo_handler_sample_try_recv
-
-.. TODO .. autocfunction:: primitives.h::z_ring_handler_sample_drop
-.. TODO .. autocfunction:: primitives.h::z_ring_handler_sample_loan
-.. TODO .. autocfunction:: primitives.h::z_ring_handler_sample_recv
-.. TODO .. autocfunction:: primitives.h::z_ring_handler_sample_try_recv
-
 Ownership Functions
 -------------------
 
@@ -834,12 +942,14 @@ Types
 -----
 
 Represents a Zenoh Queryable entity.
+See details at :ref:`owned_types_concept`
 
 .. c:type:: z_owned_queryable_t
 .. c:type:: z_loaned_queryable_t
 .. c:type:: z_moved_queryable_t
 
 Represents a Zenoh Query entity, received by Zenoh queryable entities.
+See details at :ref:`owned_types_concept`
 
 .. c:type:: z_owned_query_t
 .. c:type:: z_loaned_query_t
@@ -853,11 +963,6 @@ Option Types
 .. autoctype:: types.h::z_query_reply_err_options_t
 .. autoctype:: types.h::z_query_reply_del_options_t
 
-.. TODO .. c:type:: z_owned_fifo_handler_query_t
-.. TODO .. c:type:: z_loaned_fifo_handler_query_t
-.. TODO .. c:type:: z_owned_ring_handler_query_t
-.. TODO .. c:type:: z_loaned_ring_handler_query_t
-
 Functions
 ---------
 .. autocfunction:: primitives.h::z_declare_queryable
@@ -877,19 +982,6 @@ Functions
 .. autocfunction:: primitives.h::z_query_reply_err
 .. autocfunction:: primitives.h::z_query_reply_del
 
-.. TODO .. autocfunction:: primitives.h::z_fifo_channel_query_new
-.. TODO .. autocfunction:: primitives.h::z_ring_channel_query_new
-
-.. TODO .. autocfunction:: primitives.h::z_fifo_handler_query_drop
-.. TODO .. autocfunction:: primitives.h::z_fifo_handler_query_loan
-.. TODO .. autocfunction:: primitives.h::z_fifo_handler_query_recv
-.. TODO .. autocfunction:: primitives.h::z_fifo_handler_query_try_recv
-
-.. TODO .. autocfunction:: primitives.h::z_ring_handler_query_drop
-.. TODO .. autocfunction:: primitives.h::z_ring_handler_query_loan
-.. TODO .. autocfunction:: primitives.h::z_ring_handler_query_recv
-.. TODO .. autocfunction:: primitives.h::z_ring_handler_query_try_recv
-
 Ownership Functions
 -------------------
 
@@ -921,12 +1013,6 @@ Option Types
 .. autocenum:: constants.h::z_consolidation_mode_t
 .. autoctype:: types.h::z_query_consolidation_t
 
-.. TODO .. c:type:: z_owned_fifo_handler_reply_t
-.. TODO .. c:type:: z_loaned_fifo_handler_reply_t
-.. TODO .. c:type:: z_owned_ring_handler_reply_t
-.. TODO .. c:type:: z_loaned_ring_handler_reply_t
-
-
 Functions
 ---------
 
@@ -944,19 +1030,6 @@ Functions
 .. autocfunction:: primitives.h::z_reply_ok
 .. autocfunction:: primitives.h::z_reply_err
 
-.. TODO .. autocfunction:: primitives.h::z_fifo_channel_reply_new
-.. TODO .. autocfunction:: primitives.h::z_ring_channel_reply_new
-
-.. TODO .. autocfunction:: primitives.h::z_fifo_handler_reply_drop
-.. TODO .. autocfunction:: primitives.h::z_fifo_handler_reply_loan
-.. TODO .. autocfunction:: primitives.h::z_fifo_handler_reply_recv
-.. TODO .. autocfunction:: primitives.h::z_fifo_handler_reply_try_recv
-
-.. TODO .. autocfunction:: primitives.h::z_ring_handler_reply_drop
-.. TODO .. autocfunction:: primitives.h::z_ring_handler_reply_loan
-.. TODO .. autocfunction:: primitives.h::z_ring_handler_reply_recv
-.. TODO .. autocfunction:: primitives.h::z_ring_handler_reply_try_recv
-
 Ownership Functions
 -------------------
 
@@ -974,6 +1047,7 @@ Types
 -----
 
 Represents the content of a `hello` message returned by a zenoh entity as a reply to a `scout` message.
+See details at :ref:`owned_types_concept`
 
 .. c:type:: z_owned_hello_t
 .. c:type:: z_loaned_hello_t
@@ -983,7 +1057,6 @@ Option Types
 ------------
 
 .. autoctype:: types.h::z_scout_options_t
-.. TODO .. autoctype:: types.h::z_owned_closure_hello_t
 
 Functions
 ---------