From 8c8c3254fce29766a27a940e9b31cdb1ade40770 Mon Sep 17 00:00:00 2001 From: Alexander Bushnev Date: Mon, 7 Oct 2024 16:56:53 +0200 Subject: [PATCH] Add docs for system functions --- docs/api.rst | 35 ++- include/zenoh-pico/system/platform_common.h | 227 +++++++++++++++++++- 2 files changed, 245 insertions(+), 17 deletions(-) diff --git a/docs/api.rst b/docs/api.rst index 519e640fd..da91a1b1f 100644 --- a/docs/api.rst +++ b/docs/api.rst @@ -680,28 +680,35 @@ Time Types ^^^^^ -.. c:type:: z_clock_t .. c:type:: z_time_t +A time value that is accurate to the nearest microsecond but also has a range of years. + +.. c:type:: z_clock_t + +This is like a :c:type:`z_time_t` but has nanoseconds instead of microseconds. + Functions ^^^^^^^^^ -.. autocfunction:: platform_common.h::z_clock_now -.. autocfunction:: platform_common.h::z_clock_elapsed_s -.. autocfunction:: platform_common.h::z_clock_elapsed_ms -.. autocfunction:: platform_common.h::z_clock_elapsed_us - .. autocfunction:: platform_common.h::z_time_now .. autocfunction:: platform_common.h::z_time_elapsed_s .. autocfunction:: platform_common.h::z_time_elapsed_ms .. autocfunction:: platform_common.h::z_time_elapsed_us .. autocfunction:: platform_common.h::z_time_now_as_str +.. autocfunction:: platform_common.h::z_clock_now +.. autocfunction:: platform_common.h::z_clock_elapsed_s +.. autocfunction:: platform_common.h::z_clock_elapsed_ms +.. autocfunction:: platform_common.h::z_clock_elapsed_us + Mutex ----- Types ^^^^^ +Represents a mutual exclusion (mutex) object used to ensure exclusive access to shared resources. + See details at :ref:`owned_types_concept` .. c:type:: z_owned_mutex_t @@ -730,6 +737,14 @@ Conditional Variable Types ^^^^^ +Represents a condition variable, which is a synchronization primitive +that allows threads to wait until a particular condition occurs. + +A condition variable is used in conjunction with mutexes to enable threads to +wait for signals from other threads. When a thread calls the wait function +on a condition variable, it releases the associated mutex and enters a wait +state until another thread signals the condition variable. + See details at :ref:`owned_types_concept` .. c:type:: z_owned_condvar_t @@ -755,6 +770,14 @@ Task ---- Types ^^^^^ + +Represents a task that can be executed by a thread. + +A task is an abstraction for encapsulating a unit of work that can +be scheduled and executed by a thread. Tasks are typically +used to represent asynchronous operations, allowing the program to perform +multiple operations concurrently. + .. c:type:: z_owned_task_t .. c:type:: z_moved_task_t diff --git a/include/zenoh-pico/system/platform_common.h b/include/zenoh-pico/system/platform_common.h index d6956aba9..225162e70 100644 --- a/include/zenoh-pico/system/platform_common.h +++ b/include/zenoh-pico/system/platform_common.h @@ -91,12 +91,44 @@ uint64_t z_random_u64(void); /** * Fills buffer with random data. + * + * Parameters: + * buf: Pointer to the buffer that will be filled with random data. + * len: Number of bytes to fill in the buffer. */ void z_random_fill(void *buf, size_t len); /*------------------ Memory ------------------*/ + +/** + * Allocates memory of the specified size. + * + * Parameters: + * size: The number of bytes to allocate. + * + * Returns: + * A pointer to the allocated memory, or NULL if the allocation fails. + */ void *z_malloc(size_t size); + +/** + * Reallocates the given memory block to a new size. + * + * Parameters: + * ptr: Pointer to the previously allocated memory. Can be NULL, in which case it behaves like z_malloc(). + * size: The new size for the memory block in bytes. + * + * Returns: + * A pointer to the reallocated memory, or NULL if the reallocation fails. + */ void *z_realloc(void *ptr, size_t size); + +/** + * Frees the memory previously allocated by z_malloc or z_realloc. + * + * Parameters: + * ptr: Pointer to the memory to be freed. If NULL, no action is taken. + */ void z_free(void *ptr); #if Z_FEATURE_MULTI_THREAD == 0 @@ -132,7 +164,10 @@ void _z_task_free(_z_task_t **task); z_result_t z_task_init(z_owned_task_t *task, z_task_attr_t *attr, void *(*fun)(void *), void *arg); /** - * Joins the task and releases all allocated resources + * Joins the task and releases all allocated resources. + * + * Parameters: + * task: Pointer to a :c:type:`z_moved_task_t` representing the task to be joined. * * Returns: * ``0`` in case of success, negative error code otherwise. @@ -142,13 +177,19 @@ z_result_t z_task_join(z_moved_task_t *task); /** * Detaches the task and releases all allocated resources. * + * Parameters: + * task: Pointer to a :c:type:`z_moved_task_t` representing the task to be detached. + * * Returns: * ``0`` in case of success, negative error code otherwise. */ z_result_t z_task_detach(z_moved_task_t *task); /** - * Drop the task. Same as :c:func:`z_task_detach`. Use :c:func:`z_task_join` to wait for the task completion. + * Drops the task. Same as :c:func:`z_task_detach`. Use :c:func:`z_task_join` to wait for the task completion. + * + * Parameters: + * task: Pointer to a :c:type:`z_moved_task_t` representing the task to be dropped. * * Returns: * ``0`` in case of success, negative error code otherwise. @@ -169,40 +210,55 @@ z_result_t _z_mutex_unlock(_z_mutex_t *m); /** * Constructs a mutex. * + * Parameters: + * m: Pointer to an uninitialized :c:type:`z_owned_mutex_t` that will be constructed. + * * Returns: - * 0 in case of success, negative error code otherwise. + * ``0`` in case of success, negative error code otherwise. */ z_result_t z_mutex_init(z_owned_mutex_t *m); /** - * Drops mutex and resets it to its gravestone state. + * Drops a mutex and resets it to its gravestone state. + * + * Parameters: + * m: Pointer to a :c:type:`z_moved_mutex_t` that will be dropped. * * Returns: - * 0 in case of success, negative error code otherwise. + * ``0`` in case of success, negative error code otherwise. */ z_result_t z_mutex_drop(z_moved_mutex_t *m); /** - * Locks mutex. If mutex is already locked, blocks the thread until it aquires the lock. + * Locks a mutex. If the mutex is already locked, blocks the thread until it acquires the lock. + * + * Parameters: + * m: Pointer to a :c:type:`z_loaned_mutex_t` that will be locked. * * Returns: - * 0 in case of success, negative error code otherwise. + * ``0`` in case of success, negative error code otherwise. */ z_result_t z_mutex_lock(z_loaned_mutex_t *m); /** - * Tries to lock mutex. If mutex is already locked, return immediately. + * Tries to lock a mutex. If the mutex is already locked, the function returns immediately. + * + * Parameters: + * m: Pointer to a :c:type:`z_loaned_mutex_t` that will be locked if not already locked. * * Returns: - * 0 in case of success, negative error code otherwise. + * ``0`` in case of success, negative error code otherwise. */ z_result_t z_mutex_try_lock(z_loaned_mutex_t *m); /** - * Unlocks previously locked mutex. If mutex was not locked by the current thread, the behaviour is undefined. + * Unlocks a previously locked mutex. If the mutex was not locked by the current thread, the behavior is undefined. + * + * Parameters: + * m: Pointer to a :c:type:`z_loaned_mutex_t` that will be unlocked. * * Returns: - * 0 in case of success, negative error code otherwise. + * ``0`` in case of success, negative error code otherwise. */ z_result_t z_mutex_unlock(z_loaned_mutex_t *m); @@ -217,28 +273,177 @@ 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); +/** + * Initializes a condition variable. + * + * Parameters: + * cv: Pointer to an uninitialized :c:type:`z_owned_condvar_t` that will be initialized. + * + * Returns: + * ``0`` if the initialization is successful, a negative value otherwise. + */ z_result_t z_condvar_init(z_owned_condvar_t *cv); + +/** + * Destroys a condition variable and releases its resources. + * + * Parameters: + * cv: Pointer to a :c:type:`z_moved_condvar_t` that will be destroyed. + * + * Returns: + * ``0`` if the destruction is successful, a negative value otherwise. + */ z_result_t z_condvar_drop(z_moved_condvar_t *cv); +/** + * Signals (wakes up) one thread waiting on the condition variable. + * + * Parameters: + * cv: Pointer to a :c:type:`z_loaned_condvar_t` that will be signaled. + * + * Returns: + * ``0`` if the signal is successful, a negative value otherwise. + */ z_result_t z_condvar_signal(z_loaned_condvar_t *cv); + +/** + * Waits for a signal on the condition variable while holding a mutex. + * + * The calling thread is blocked until the condition variable is signaled. + * The associated mutex must be locked by the calling thread, and it will be automatically unlocked while waiting. + * + * Parameters: + * cv: Pointer to a :c:type:`z_loaned_condvar_t` on which to wait. + * m: Pointer to a :c:type:`z_loaned_mutex_t` that will be unlocked during the wait. + * + * Returns: + * ``0`` if the wait is successful, a negative value otherwise. + */ z_result_t z_condvar_wait(z_loaned_condvar_t *cv, z_loaned_mutex_t *m); /*------------------ Sleep ------------------*/ +/** + * Suspends execution for a specified amount of time in microseconds. + * + * Parameters: + * time: The amount of time to sleep, in microseconds. + * + * Returns: + * ``0`` if the sleep is successful, a negative value otherwise. + */ z_result_t z_sleep_us(size_t time); + +/** + * Suspends execution for a specified amount of time in milliseconds. + * + * Parameters: + * time: The amount of time to sleep, in milliseconds. + * + * Returns: + * ``0`` if the sleep is successful, a negative value otherwise. + */ z_result_t z_sleep_ms(size_t time); + +/** + * Suspends execution for a specified amount of time in seconds. + * + * Parameters: + * time: The amount of time to sleep, in seconds. + * + * Returns: + * ``0`` if the sleep is successful, a negative value otherwise. + */ z_result_t z_sleep_s(size_t time); /*------------------ Clock ------------------*/ +/** + * Returns monotonic clock time point corresponding to the current time instant. + */ z_clock_t z_clock_now(void); + +/** + * Returns the elapsed time in microseconds since a given clock time. + * + * Parameters: + * time: Pointer to a `z_clock_t` representing the starting time. + * + * Returns: + * The elapsed time in microseconds. + */ unsigned long z_clock_elapsed_us(z_clock_t *time); + +/** + * Returns the elapsed time in milliseconds since a given clock time. + * + * Parameters: + * time: Pointer to a `z_clock_t` representing the starting time. + * + * Returns: + * The elapsed time in milliseconds. + */ unsigned long z_clock_elapsed_ms(z_clock_t *time); + +/** + * Returns the elapsed time in seconds since a given clock time. + * + * Parameters: + * time: Pointer to a `z_clock_t` representing the starting time. + * + * Returns: + * The elapsed time in seconds. + */ unsigned long z_clock_elapsed_s(z_clock_t *time); /*------------------ Time ------------------*/ + +/** + * Returns system clock time point corresponding to the current time instant. + */ z_time_t z_time_now(void); + +/** + * Gets the current time as a string. + * + * Parameters: + * buf: Pointer to a buffer where the time string will be written. + * buflen: The length of the buffer. + * + * Returns: + * A pointer to the buffer containing the time string. + */ const char *z_time_now_as_str(char *const buf, unsigned long buflen); + +/** + * Returns the elapsed time in microseconds since a given time. + * + * Parameters: + * time: Pointer to a `z_time_t` representing the starting time. + * + * Returns: + * The elapsed time in microseconds. + */ unsigned long z_time_elapsed_us(z_time_t *time); + +/** + * Returns the elapsed time in milliseconds since a given time. + * + * Parameters: + * time: Pointer to a `z_time_t` representing the starting time. + * + * Returns: + * The elapsed time in milliseconds. + */ unsigned long z_time_elapsed_ms(z_time_t *time); + +/** + * Returns the elapsed time in seconds since a given time. + * + * Parameters: + * time: Pointer to a `z_time_t` representing the starting time. + * + * Returns: + * The elapsed time in seconds. + */ unsigned long z_time_elapsed_s(z_time_t *time); typedef struct {