Skip to content

Commit

Permalink
Update comments and documentation
Browse files Browse the repository at this point in the history
  • Loading branch information
sashacmc committed Nov 16, 2023
1 parent 32b6d89 commit e5fd268
Show file tree
Hide file tree
Showing 5 changed files with 107 additions and 44 deletions.
23 changes: 22 additions & 1 deletion Cargo.lock

Some generated files are not rendered by default. Learn more about how customized files appear on GitHub.

36 changes: 35 additions & 1 deletion docs/api.rst
Original file line number Diff line number Diff line change
@@ -1,5 +1,5 @@
..
.. Copyright (c) 2022 ZettaScale Technology
.. 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
Expand Down Expand Up @@ -262,4 +262,38 @@ Functions
.. autocfunction:: zenoh_commons.h::z_closure_query_call
.. autocfunction:: zenoh_commons.h::z_closure_query_drop

Publication Cache
=================

Types
-----

.. autocstruct:: zenoh_commons.h::ze_publication_cache_options_t
.. autocstruct:: zenoh_commons.h::ze_owned_publication_cache_t

Functions
---------

.. autocfunction:: zenoh_commons.h::ze_declare_publication_cache
.. autocfunction:: zenoh_commons.h::ze_close_publication_cache
.. autocfunction:: zenoh_commons.h::ze_publication_cache_check
.. autocfunction:: zenoh_commons.h::ze_publication_cache_null
.. autocfunction:: zenoh_commons.h::ze_publication_cache_options_default

Querying Subscriber
===================

Types
-----

.. autocstruct:: zenoh_commons.h::ze_owned_querying_subscriber_t
.. autocstruct:: zenoh_commons.h::ze_querying_subscriber_options_t

Functions
---------

.. autocfunction:: zenoh_commons.h::ze_declare_querying_subscriber
.. autocfunction:: zenoh_commons.h::ze_undeclare_querying_subscriber
.. autocfunction:: zenoh_commons.h::ze_querying_subscriber_check
.. autocfunction:: zenoh_commons.h::ze_querying_subscriber_null
.. autocfunction:: zenoh_commons.h::ze_querying_subscriber_options_default
37 changes: 22 additions & 15 deletions include/zenoh_commons.h
Original file line number Diff line number Diff line change
Expand Up @@ -745,11 +745,11 @@ typedef struct ze_owned_publication_cache_t {
* Options passed to the :c:func:`ze_declare_publication_cache` function.
*
* Members:
* queryable_prefix: the prefix used for queryable
* queryable_origin: the restriction for the matching queries that will be receive by this
* z_keyexpr_t queryable_prefix: The prefix used for queryable
* zcu_locality_t queryable_origin: The restriction for the matching queries that will be receive by this
* publication cache
* history: the the history size
* resources_limit: the limit number of cached resources
* size_t history: The the history size
* size_t resources_limit: The limit number of cached resources
*/
typedef struct ze_publication_cache_options_t {
struct z_keyexpr_t queryable_prefix;
Expand Down Expand Up @@ -778,6 +778,13 @@ typedef struct ze_owned_querying_subscriber_t {
*
* Members:
* z_reliability_t reliability: The subscription reliability.
* zcu_locality_t allowed_origin: The restriction for the matching publications that will be
* receive by this subscriber.
* z_keyexpr_t query_selector: The selector to be used for queries.
* z_query_target_t query_target: The target to be used for queries.
* z_query_consolidation_t query_consolidation: The consolidation mode to be used for queries.
* zcu_reply_keyexpr_t query_accept_replies: The accepted replies for queries.
* uint64_t query_timeout_ms: The timeout to be used for queries.
*/
typedef struct ze_querying_subscriber_options_t {
enum z_reliability_t reliability;
Expand Down Expand Up @@ -2045,15 +2052,15 @@ ZENOHC_API enum zcu_reply_keyexpr_t zcu_reply_keyexpr_default(void);
ZENOHC_API
int8_t ze_close_publication_cache(struct ze_owned_publication_cache_t *pub_cache);
/**
* Declares a publication cache.
* Declares a Publication Cache.
*
* Parameters:
* session: the zenoh session.
* keyexpr: the key expression to publish.
* options: additional options for the publication_cache.
* z_session_t session: The zenoh session.
* z_keyexpr_t keyexpr: The key expression to publish.
* ze_publication_cache_options_t options: Additional options for the publication_cache.
*
* Returns:
* A :c:type:`ze_owned_publication_cache_t`.
* :c:type:`ze_owned_publication_cache_t`.
*
*
* Example:
Expand All @@ -2075,16 +2082,16 @@ struct ze_owned_publication_cache_t ze_declare_publication_cache(struct z_sessio
struct z_keyexpr_t keyexpr,
const struct ze_publication_cache_options_t *options);
/**
* Declares a querying subscriber for a given key expression.
* Declares a Querying Subscriber for a given key expression.
*
* Parameters:
* session: The zenoh session.
* keyexpr: The key expression to subscribe.
* callback: The callback function that will be called each time a data matching the subscribed expression is received.
* opts: additional options for the querying subscriber.
* z_session_t session: The zenoh session.
* z_keyexpr_t keyexpr: The key expression to subscribe.
* z_owned_closure_sample_t callback: The callback function that will be called each time a data matching the subscribed expression is received.
* ze_querying_subscriber_options_t options: Additional options for the querying subscriber.
*
* Returns:
* A :c:type:`ze_owned_subscriber_t`.
* :c:type:`ze_owned_subscriber_t`.
*
* To check if the subscription succeeded and if the querying subscriber is still valid,
* you may use `ze_querying_subscriber_check(&val)` or `z_check(val)` if your compiler supports `_Generic`, which will return `true` if `val` is valid.
Expand Down
18 changes: 9 additions & 9 deletions src/publication_cache.rs
Original file line number Diff line number Diff line change
Expand Up @@ -26,11 +26,11 @@ use crate::{
/// Options passed to the :c:func:`ze_declare_publication_cache` function.
///
/// Members:
/// queryable_prefix: the prefix used for queryable
/// queryable_origin: the restriction for the matching queries that will be receive by this
/// z_keyexpr_t queryable_prefix: The prefix used for queryable
/// zcu_locality_t queryable_origin: The restriction for the matching queries that will be receive by this
/// publication cache
/// history: the the history size
/// resources_limit: the limit number of cached resources
/// size_t history: The the history size
/// size_t resources_limit: The limit number of cached resources
#[repr(C)]
pub struct ze_publication_cache_options_t {
pub queryable_prefix: z_keyexpr_t,
Expand Down Expand Up @@ -94,15 +94,15 @@ impl ze_owned_publication_cache_t {
}
}

/// Declares a publication cache.
/// Declares a Publication Cache.
///
/// Parameters:
/// session: the zenoh session.
/// keyexpr: the key expression to publish.
/// options: additional options for the publication_cache.
/// z_session_t session: The zenoh session.
/// z_keyexpr_t keyexpr: The key expression to publish.
/// ze_publication_cache_options_t options: Additional options for the publication_cache.
///
/// Returns:
/// A :c:type:`ze_owned_publication_cache_t`.
/// :c:type:`ze_owned_publication_cache_t`.
///
///
/// Example:
Expand Down
37 changes: 19 additions & 18 deletions src/querying_subscriber.rs
Original file line number Diff line number Diff line change
@@ -1,5 +1,5 @@
//
// Copyright (c) 2017, 2022 ZettaScale Technology.
// 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
Expand All @@ -12,11 +12,6 @@
// ZettaScale Zenoh team, <[email protected]>
//

use crate::commons::*;
use crate::z_closure_sample_call;
use crate::z_owned_closure_sample_t;
use crate::z_reliability_t;
use crate::LOG_INVALID_SESSION;
use zenoh::prelude::sync::SyncResolve;
use zenoh::prelude::SessionDeclarations;
use zenoh::prelude::SplitBuffer;
Expand All @@ -25,14 +20,13 @@ use zenoh_protocol::core::SubInfo;
use zenoh_util::core::zresult::ErrNo;

use crate::{
impl_guarded_transmute, z_keyexpr_t, z_query_consolidation_default, z_query_consolidation_t,
z_query_target_default, z_query_target_t, z_session_t, zcu_locality_default, zcu_locality_t,
zcu_reply_keyexpr_default, zcu_reply_keyexpr_t, GuardedTransmute,
impl_guarded_transmute, z_closure_sample_call, z_keyexpr_t, z_owned_closure_sample_t,
z_query_consolidation_default, z_query_consolidation_t, z_query_target_default,
z_query_target_t, z_reliability_t, z_sample_t, z_session_t, zcu_locality_default,
zcu_locality_t, zcu_reply_keyexpr_default, zcu_reply_keyexpr_t, GuardedTransmute,
LOG_INVALID_SESSION,
};

/**************************************/
/* DECLARATION */
/**************************************/
type FetchingSubscriber = Option<Box<zenoh_ext::FetchingSubscriber<'static, ()>>>;

/// An owned zenoh querying subscriber. Destroying the subscriber cancels the subscription.
Expand Down Expand Up @@ -99,6 +93,13 @@ pub extern "C" fn ze_querying_subscriber_null() -> ze_owned_querying_subscriber_
///
/// Members:
/// z_reliability_t reliability: The subscription reliability.
/// zcu_locality_t allowed_origin: The restriction for the matching publications that will be
/// receive by this subscriber.
/// z_keyexpr_t query_selector: The selector to be used for queries.
/// z_query_target_t query_target: The target to be used for queries.
/// z_query_consolidation_t query_consolidation: The consolidation mode to be used for queries.
/// zcu_reply_keyexpr_t query_accept_replies: The accepted replies for queries.
/// uint64_t query_timeout_ms: The timeout to be used for queries.
#[repr(C)]
#[allow(non_camel_case_types)]
pub struct ze_querying_subscriber_options_t {
Expand All @@ -125,16 +126,16 @@ pub extern "C" fn ze_querying_subscriber_options_default() -> ze_querying_subscr
}
}

/// Declares a querying subscriber for a given key expression.
/// Declares a Querying Subscriber for a given key expression.
///
/// Parameters:
/// session: The zenoh session.
/// keyexpr: The key expression to subscribe.
/// callback: The callback function that will be called each time a data matching the subscribed expression is received.
/// opts: additional options for the querying subscriber.
/// z_session_t session: The zenoh session.
/// z_keyexpr_t keyexpr: The key expression to subscribe.
/// z_owned_closure_sample_t callback: The callback function that will be called each time a data matching the subscribed expression is received.
/// ze_querying_subscriber_options_t options: Additional options for the querying subscriber.
///
/// Returns:
/// A :c:type:`ze_owned_subscriber_t`.
/// :c:type:`ze_owned_subscriber_t`.
///
/// To check if the subscription succeeded and if the querying subscriber is still valid,
/// you may use `ze_querying_subscriber_check(&val)` or `z_check(val)` if your compiler supports `_Generic`, which will return `true` if `val` is valid.
Expand Down

0 comments on commit e5fd268

Please sign in to comment.