From 35d3d94484d96da60d0315a2594969b222cae8fe Mon Sep 17 00:00:00 2001 From: Alexander Bushnev Date: Tue, 1 Oct 2024 16:14:28 +0200 Subject: [PATCH] Rework common and system types --- docs/api.rst | 195 +++++++++++++++----- include/zenoh-pico/system/platform_common.h | 18 +- 2 files changed, 155 insertions(+), 58 deletions(-) diff --git a/docs/api.rst b/docs/api.rst index 2171790b9..f3376840e 100644 --- a/docs/api.rst +++ b/docs/api.rst @@ -26,6 +26,9 @@ Represents an array of bytes. Types ^^^^^ + +See details at :ref:`owned_types_concept` + .. c:type:: z_owned_slice_t .. c:type:: z_view_slice_t .. c:type:: z_loaned_slice_t @@ -35,13 +38,6 @@ Types Functions ^^^^^^^^^ -.. c:function:: const z_loaned_slice_t * z_view_slice_loan(const struct z_view_slice_t * slice) -.. c:function:: const z_loaned_slice_t * z_slice_loan(const struct z_owned_slice_t * slice) -.. c:function:: void z_slice_drop(struct z_moved_slice_t * slice) -.. c:function:: void z_slice_clone(struct z_owned_slice_t * dst, const struct z_loaned_slice_t * slice) - - See :ref:`owned_types_concept` - .. autocfunction:: primitives.h::z_slice_empty .. autocfunction:: primitives.h::z_slice_copy_from_buf .. autocfunction:: primitives.h::z_slice_from_buf @@ -55,6 +51,19 @@ Functions See :c:func:`z_slice_empty` +Ownership Functions +^^^^^^^^^^^^^^^^^^^ + +See details at :ref:`owned_types_concept` + +.. c:function:: void z_slice_drop(z_moved_slice_t * slice) +.. c:function:: void z_slice_clone(z_owned_slice_t * dst, const z_loaned_slice_t * slice) +.. c:function:: const z_loaned_slice_t * z_view_slice_loan(const z_view_slice_t * slice) +.. c:function:: z_loaned_slice_t * z_view_slice_loan_mut(z_view_slice_t * slice) +.. c:function:: const z_loaned_slice_t * z_slice_loan(const z_owned_slice_t * slice) +.. c:function:: z_loaned_slice_t * z_slice_loan_mut(z_owned_slice_t * slice) + + String ------ @@ -62,6 +71,9 @@ Represents a string without null-terminator. Types ^^^^^ + +See details at :ref:`owned_types_concept` + .. c:type:: z_owned_string_t .. c:type:: z_view_string_t .. c:type:: z_loaned_string_t @@ -69,10 +81,6 @@ Types Functions ^^^^^^^^^ -.. TODO .. autocfunction:: primitives.h::z_string_loan -.. TODO .. autocfunction:: primitives.h::z_view_string_loan -.. TODO .. autocfunction:: primitives.h::z_string_drop -.. TODO .. autocfunction:: primitives.h::z_string_clone .. autocfunction:: primitives.h::z_string_empty .. autocfunction:: primitives.h::z_string_copy_from_str @@ -88,7 +96,17 @@ Functions See :c:func:`z_string_empty` +Ownership Functions +^^^^^^^^^^^^^^^^^^^ +See details at :ref:`owned_types_concept` + +.. c:function:: void z_string_drop(z_moved_string_t * string) +.. c:function:: void z_string_clone(z_owned_string_t * dst, const z_loaned_string_t * string) +.. c:function:: const z_loaned_string_t * z_view_string_loan(const z_view_string_t * string) +.. c:function:: z_loaned_string_t * z_view_string_loan_mut(z_view_string_t * string) +.. c:function:: const z_loaned_string_t * z_string_loan(const z_owned_string_t * string) +.. c:function:: z_loaned_string_t * z_string_loan_mut(z_owned_string_t * string) String Array @@ -98,17 +116,15 @@ Represents an array of non null-terminated string. Types ^^^^^ + +See details at :ref:`owned_types_concept` + .. c:type:: z_owned_string_array_t .. c:type:: z_loaned_string_array_t .. c:type:: z_moved_string_array_t Functions ^^^^^^^^^ -.. TODO .. autocfunction:: primitives.h::z_string_array_loan -.. TODO .. autocfunction:: primitives.h::z_string_array_loan_mut -.. TODO .. autocfunction:: primitives.h::z_string_array_clone -.. TODO .. autocfunction:: primitives.h::z_string_array_drop - .. autocfunction:: primitives.h::z_string_array_new .. autocfunction:: primitives.h::z_string_array_push_by_alias .. autocfunction:: primitives.h::z_string_array_push_by_copy @@ -116,6 +132,17 @@ Functions .. autocfunction:: primitives.h::z_string_array_len .. autocfunction:: primitives.h::z_string_array_is_empty +Ownership Functions +^^^^^^^^^^^^^^^^^^^ + +See details at :ref:`owned_types_concept` + +.. c:function:: void z_string_array_drop(z_moved_string_array_t * string_array) +.. c:function:: void z_string_array_clone(z_owned_string_array_t * dst, const z_loaned_string_array_t * string_array) +.. c:function:: const z_loaned_string_array_t * z_string_array_loan(const z_owned_string_array_t * string_array) +.. c:function:: z_loaned_string_array_t * z_string_array_loan_mut(z_owned_string_array_t * string_array) + + Common ====== @@ -126,12 +153,15 @@ Represents a key expression in Zenoh. Types ^^^^^ + +See details at :ref:`owned_types_concept` + .. c:type:: z_owned_keyexpr_t .. c:type:: z_view_keyexpr_t .. c:type:: z_loaned_keyexpr_t .. c:type:: z_moved_keyexpr_t + .. autocenum:: constants.h::z_keyexpr_intersection_level_t -.. autocenum:: constants.h::z_whatami_t .. autocenum:: constants.h::zp_keyexpr_canon_status_t Functions @@ -141,18 +171,12 @@ Functions .. autocfunction:: primitives.h::z_keyexpr_from_str_autocanonize .. autocfunction:: primitives.h::z_view_keyexpr_from_str_autocanonize .. autocfunction:: primitives.h::z_view_keyexpr_from_str_unchecked - .. autocfunction:: primitives.h::z_keyexpr_from_substr .. autocfunction:: primitives.h::z_view_keyexpr_from_substr .. autocfunction:: primitives.h::z_keyexpr_from_substr_autocanonize .. autocfunction:: primitives.h::z_view_keyexpr_from_substr_autocanonize .. autocfunction:: primitives.h::z_view_keyexpr_from_substr_unchecked -.. TODO .. autocfunction:: primitives.h::z_keyexpr_loan -.. TODO .. autocfunction:: primitives.h::z_view_keyexpr_loan -.. TODO .. autocfunction:: primitives.h::z_keyexpr_clone -.. TODO .. autocfunction:: primitives.h::z_keyexpr_drop - .. autocfunction:: primitives.h::z_keyexpr_as_view_string .. autocfunction:: primitives.h::z_keyexpr_canonize @@ -168,29 +192,53 @@ Functions .. autocfunction:: primitives.h::z_declare_keyexpr .. autocfunction:: primitives.h::z_undeclare_keyexpr +Ownership Functions +^^^^^^^^^^^^^^^^^^^ + +See details at :ref:`owned_types_concept` + +.. c:function:: void z_keyexpr_drop(z_moved_keyexpr_t * keyexpr) +.. c:function:: void z_keyexpr_clone(z_owned_keyexpr_t * dst, const z_loaned_keyexpr_t * keyexpr) +.. c:function:: const z_loaned_keyexpr_t * z_view_keyexpr_loan(const z_view_keyexpr_t * keyexpr) +.. c:function:: z_loaned_keyexpr_t * z_view_keyexpr_loan_mut(z_view_keyexpr_t * keyexpr) +.. c:function:: const z_loaned_keyexpr_t * z_keyexpr_loan(const z_owned_keyexpr_t * keyexpr) +.. c:function:: z_loaned_keyexpr_t * z_keyexpr_loan_mut(z_owned_keyexpr_t * keyexpr) + + Encoding -------- + +Represents the encoding of a payload, in a MIME-like format. + Types ^^^^^ + +See details at :ref:`owned_types_concept` + .. c:type:: z_owned_encoding_t .. c:type:: z_loaned_encoding_t .. c:type:: z_moved_encoding_t - Represents the encoding of a payload, in a MIME-like format. - Functions ^^^^^^^^^ -.. TODO .. autocfunction:: encoding.h::z_encoding_loan -.. TODO .. autocfunction:: encoding.h::z_encoding_loan_mut -.. TODO .. autocfunction:: encoding.h::z_encoding_drop -.. TODO (add method) .. autocfunction:: encoding.h::z_encoding_loan_default - .. autocfunction:: primitives.h::z_encoding_from_str .. autocfunction:: primitives.h::z_encoding_from_substr .. autocfunction:: primitives.h::z_encoding_set_schema_from_str .. autocfunction:: primitives.h::z_encoding_set_schema_from_substr .. autocfunction:: primitives.h::z_encoding_to_string .. autocfunction:: primitives.h::z_encoding_equals +.. TODO (add method) .. autocfunction:: encoding.h::z_encoding_loan_default + +Ownership Functions +^^^^^^^^^^^^^^^^^^^ + +See details at :ref:`owned_types_concept` + +.. c:function:: void z_encoding_drop(z_moved_encoding_t * encoding) +.. c:function:: void z_encoding_clone(z_owned_encoding_t * dst, const z_loaned_encoding_t * encoding) +.. c:function:: const z_loaned_encoding_t * z_encoding_loan(const z_owned_encoding_t * encoding) +.. c:function:: z_loaned_encoding_t * z_encoding_loan_mut(z_owned_encoding_t * encoding) + Predefined Encodings ^^^^^^^^^^^^^^^^^^^^ @@ -263,39 +311,51 @@ Predefined Encodings Reply Error ----------- + +Represents a Zenoh reply error value. + Types ^^^^^ + +See details at :ref:`owned_types_concept` + .. c:type:: z_owned_reply_err_t .. c:type:: z_loaned_reply_err_t - - Represents a Zenoh reply error value. +.. c:type:: z_moved_reply_err_t Functions ^^^^^^^^^ .. autocfunction:: primitives.h::z_reply_err_payload .. autocfunction:: primitives.h::z_reply_err_encoding -.. TODO .. autocfunction:: primitives.h::z_reply_err_loan -.. TODO .. autocfunction:: primitives.h::z_reply_err_clone -.. TODO .. autocfunction:: primitives.h::z_reply_err_drop +Ownership Functions +^^^^^^^^^^^^^^^^^^^ + +See details at :ref:`owned_types_concept` + +.. c:function:: void z_reply_err_drop(z_moved_reply_err_t * reply_err) +.. c:function:: void z_reply_err_clone(z_owned_reply_err_t * dst, const z_loaned_reply_err_t * reply_err) +.. c:function:: const z_loaned_reply_err_t * z_reply_err_loan(const z_owned_reply_err_t * reply_err) + Sample ------ + +Represents a data sample. + Types ^^^^^ + +See details at :ref:`owned_types_concept` + .. c:type:: z_owned_sample_t .. c:type:: z_loaned_sample_t .. c:type:: z_moved_sample_t - Represents a data sample. - .. autocenum:: constants.h::z_sample_kind_t Functions ^^^^^^^^^ -.. TODO .. autocfunction:: primitives.h::z_sample_loan -.. TODO .. autocfunction:: primitives.h::z_sample_drop - .. autocfunction:: primitives.h::z_sample_timestamp .. autocfunction:: primitives.h::z_sample_attachment .. autocfunction:: primitives.h::z_sample_encoding @@ -306,6 +366,15 @@ Functions .. autocfunction:: primitives.h::z_sample_express .. autocfunction:: primitives.h::z_sample_reliability +Ownership Functions +^^^^^^^^^^^^^^^^^^^ + +See details at :ref:`owned_types_concept` + +.. c:function:: void z_sample_drop(z_moved_sample_t * sample) +.. c:function:: void z_sample_clone(z_owned_sample_t * dst, const z_loaned_sample_t * sample) +.. c:function:: const z_loaned_sample_t * z_sample_loan(const z_owned_sample_t * sample) + Timestamp --------- @@ -364,51 +433,76 @@ Mutex ----- Types ^^^^^ + +See details at :ref:`owned_types_concept` + .. c:type:: z_owned_mutex_t .. c:type:: z_loaned_mutex_t .. c:type:: z_moved_mutex_t Functions ^^^^^^^^^ -.. TODO .. autocfunction:: platform_common.h::z_mutex_loan_mut -.. autocfunction:: platform_common.h::z_mutex_drop -.. TODO .. autocfunction:: platform_common.h::z_mutex_init +.. autocfunction:: platform_common.h::z_mutex_init .. autocfunction:: platform_common.h::z_mutex_lock .. autocfunction:: platform_common.h::z_mutex_unlock .. autocfunction:: platform_common.h::z_mutex_try_lock +Ownership Functions +^^^^^^^^^^^^^^^^^^^ + +See details at :ref:`owned_types_concept` + +.. c:function:: void z_mutex_drop(z_moved_mutex_t * mutex) +.. c:function:: void z_mutex_clone(z_owned_mutex_t * dst, const z_loaned_mutex_t * mutex) +.. c:function:: const z_loaned_mutex_t * z_mutex_loan(const z_owned_mutex_t * mutex) + Conditional Variable -------------------- Types ^^^^^ + +See details at :ref:`owned_types_concept` + .. c:type:: z_owned_condvar_t .. c:type:: z_loaned_condvar_t .. c:type:: z_moved_condvar_t Functions ^^^^^^^^^ -.. TODO .. autocfunction:: platform_common.h::z_condvar_loan -.. TODO .. autocfunction:: platform_common.h::z_condvar_drop - -.. TODO .. autocfunction:: platform_common.h::z_condvar_init +.. autocfunction:: platform_common.h::z_condvar_init .. autocfunction:: platform_common.h::z_condvar_wait .. autocfunction:: platform_common.h::z_condvar_signal +Ownership Functions +^^^^^^^^^^^^^^^^^^^ + +See details at :ref:`owned_types_concept` + +.. c:function:: void z_condvar_drop(z_moved_condvar_t * condvar) +.. c:function:: void z_condvar_clone(z_owned_condvar_t * dst, const z_loaned_condvar_t * condvar) +.. c:function:: const z_loaned_condvar_t * z_condvar_loan(const z_owned_condvar_t * condvar) + Task ---- Types ^^^^^ .. c:type:: z_owned_task_t -.. c:type:: z_loaned_task_t .. c:type:: z_moved_task_t Functions ^^^^^^^^^ .. autocfunction:: platform_common.h::z_task_join -.. TODO .. autocfunction:: platform_common.h::z_task_detach +.. autocfunction:: platform_common.h::z_task_detach + +Ownership Functions +^^^^^^^^^^^^^^^^^^^ + +See details at :ref:`owned_types_concept` + +.. c:function:: void z_task_drop(z_moved_task_t * task) Session ======= @@ -767,6 +861,9 @@ It is guaranteed that: Zenoh Functions --------------- +.. TODO +.. autocenum:: constants.h::z_whatami_t + Macros ^^^^^^ .. autocmacro:: macros.h::z_loan diff --git a/include/zenoh-pico/system/platform_common.h b/include/zenoh-pico/system/platform_common.h index ba5103000..c2b3b65a2 100644 --- a/include/zenoh-pico/system/platform_common.h +++ b/include/zenoh-pico/system/platform_common.h @@ -108,18 +108,21 @@ typedef void *z_task_attr_t; #endif /*------------------ Thread ------------------*/ +_Z_OWNED_TYPE_VALUE(_z_task_t, task) +_Z_OWNED_FUNCTIONS_SYSTEM_DEF(task) + z_result_t _z_task_init(_z_task_t *task, z_task_attr_t *attr, void *(*fun)(void *), void *arg); z_result_t _z_task_join(_z_task_t *task); z_result_t _z_task_cancel(_z_task_t *task); void _z_task_free(_z_task_t **task); -_Z_OWNED_TYPE_VALUE(_z_task_t, task) -_Z_OWNED_FUNCTIONS_SYSTEM_DEF(task) - z_result_t z_task_init(z_owned_task_t *task, z_task_attr_t *attr, void *(*fun)(void *), void *arg); z_result_t z_task_join(z_owned_task_t *task); /*------------------ Mutex ------------------*/ +_Z_OWNED_TYPE_VALUE(_z_mutex_t, mutex) +_Z_OWNED_FUNCTIONS_SYSTEM_DEF(mutex) + z_result_t _z_mutex_init(_z_mutex_t *m); z_result_t _z_mutex_drop(_z_mutex_t *m); @@ -127,9 +130,6 @@ z_result_t _z_mutex_lock(_z_mutex_t *m); z_result_t _z_mutex_try_lock(_z_mutex_t *m); z_result_t _z_mutex_unlock(_z_mutex_t *m); -_Z_OWNED_TYPE_VALUE(_z_mutex_t, mutex) -_Z_OWNED_FUNCTIONS_SYSTEM_DEF(mutex) - /** * Constructs a mutex. * @@ -171,6 +171,9 @@ z_result_t z_mutex_try_lock(z_loaned_mutex_t *m); z_result_t z_mutex_unlock(z_loaned_mutex_t *m); /*------------------ CondVar ------------------*/ +_Z_OWNED_TYPE_VALUE(_z_condvar_t, condvar) +_Z_OWNED_FUNCTIONS_SYSTEM_DEF(condvar) + z_result_t _z_condvar_init(_z_condvar_t *cv); z_result_t _z_condvar_drop(_z_condvar_t *cv); @@ -178,9 +181,6 @@ z_result_t _z_condvar_signal(_z_condvar_t *cv); z_result_t _z_condvar_signal_all(_z_condvar_t *cv); z_result_t _z_condvar_wait(_z_condvar_t *cv, _z_mutex_t *m); -_Z_OWNED_TYPE_VALUE(_z_condvar_t, condvar) -_Z_OWNED_FUNCTIONS_SYSTEM_DEF(condvar) - z_result_t z_condvar_init(z_owned_condvar_t *cv); z_result_t z_condvar_drop(z_moved_condvar_t *cv);