From 09d4f64eab9f425a36e740b4fce774814e94cb4a Mon Sep 17 00:00:00 2001 From: Alexander Bushnev Date: Tue, 1 Oct 2024 18:56:03 +0200 Subject: [PATCH] Add channels --- docs/api.rst | 185 +++++++++++++++++++++++++++++++++++---------------- 1 file changed, 129 insertions(+), 56 deletions(-) diff --git a/docs/api.rst b/docs/api.rst index df2eaf96c..133f8b772 100644 --- a/docs/api.rst +++ b/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 ---------