From c1c7959bdb9a1ad0cbf956b6b1998928477e1dee Mon Sep 17 00:00:00 2001 From: ligr Date: Tue, 19 Nov 2024 20:26:31 +0800 Subject: [PATCH] [components/libc/posix]add comments for condition variable APIs. --- components/libc/posix/pthreads/pthread_cond.c | 185 +++++++++++++++++- 1 file changed, 184 insertions(+), 1 deletion(-) diff --git a/components/libc/posix/pthreads/pthread_cond.c b/components/libc/posix/pthreads/pthread_cond.c index 6c3db2eb11..1241ef835d 100644 --- a/components/libc/posix/pthreads/pthread_cond.c +++ b/components/libc/posix/pthreads/pthread_cond.c @@ -1,5 +1,5 @@ /* - * Copyright (c) 2006-2021, RT-Thread Development Team + * Copyright (c) 2006-2024 RT-Thread Development Team * * SPDX-License-Identifier: Apache-2.0 * @@ -72,6 +72,30 @@ int pthread_condattr_setpshared(pthread_condattr_t *attr, int pshared) } RTM_EXPORT(pthread_condattr_setpshared); +/** + * @brief Initializes a condition variable. + * + * This function initializes the condition variable pointed to by `cond` with the attributes + * specified by `attr`. If `attr` is NULL, the condition variable is initialized with the + * default attributes. + * + * @param cond A pointer to the condition variable to be initialized. + * Must point to valid memory. + * @param attr A pointer to the condition variable attributes object. + * If NULL, default attributes are used. + * + * @return + * - `0` on success. + * - A non-zero error code on failure, including: + * - `EINVAL`: Invalid attributes, invalid condition variable pointer, or semaphore init failed. + * + * @note + * - The condition variable must not be used until it has been initialized. + * - Each condition variable must be destroyed using `pthread_cond_destroy()` + * once it is no longer needed. + * + * @see pthread_cond_destroy, pthread_cond_wait, pthread_cond_signal, pthread_cond_broadcast + */ int pthread_cond_init(pthread_cond_t *cond, const pthread_condattr_t *attr) { rt_err_t result; @@ -110,6 +134,30 @@ int pthread_cond_init(pthread_cond_t *cond, const pthread_condattr_t *attr) } RTM_EXPORT(pthread_cond_init); +/** + * @brief Destroys a condition variable. + * + * This function destroys the condition variable pointed to by `cond`. After a condition + * variable is destroyed, it must not be used until it is reinitialized with + * `pthread_cond_init`. + * + * @param cond A pointer to the condition variable to be destroyed. + * Must point to a valid, previously initialized condition variable. + * + * @return + * - `0` on success. + * - A non-zero error code on failure, including: + * - `EBUSY`: The condition variable is currently in use by other threads. + * - `EINVAL`: The condition variable is invalid or uninitialized. + * + * @note + * - The condition variable must not be destroyed while it is being used by other threads + * (e.g., in `pthread_cond_wait` or `pthread_cond_timedwait`). + * - Attempting to destroy a condition variable that has not been initialized results in + * undefined behavior. + * + * @see pthread_cond_init, pthread_cond_wait, pthread_cond_signal, pthread_cond_broadcast + */ int pthread_cond_destroy(pthread_cond_t *cond) { rt_err_t result; @@ -143,6 +191,30 @@ __retry: } RTM_EXPORT(pthread_cond_destroy); +/** + * @brief Unblocks all threads waiting on the specified condition variable. + * + * This function wakes up all threads that are currently blocked on the condition variable + * pointed to by `cond`. The condition variable must be associated with a mutex, and + * threads waiting on the condition variable should recheck the condition after being + * unblocked. + * + * @param cond A pointer to the condition variable. + * Must point to a valid, initialized condition variable. + * + * @return + * - `0` on success. + * - A non-zero error code on failure, including: + * - `EINVAL`: The condition variable is invalid or uninitialized. + * + * @note + * - Calling this function does not release the associated mutex. + * - Waking up threads does not guarantee that any specific thread will acquire the + * mutex immediately, as thread scheduling depends on the system. + * - Typically used when the condition might allow multiple waiting threads to proceed. + * + * @see pthread_cond_signal, pthread_cond_wait, pthread_cond_init, pthread_cond_destroy + */ int pthread_cond_broadcast(pthread_cond_t *cond) { rt_err_t result; @@ -177,6 +249,30 @@ int pthread_cond_broadcast(pthread_cond_t *cond) } RTM_EXPORT(pthread_cond_broadcast); +/** + * @brief Wakes up one thread waiting on the specified condition variable. + * + * This function unblocks one thread that is currently waiting on the + * condition variable `cond`. If multiple threads are waiting, the thread to wake + * up is determined by the system's scheduling policies. + * + * @param cond A pointer to the condition variable to signal. + * Must point to a valid and initialized condition variable. + * + * @return + * - `0` on success. + * - A non-zero error code on failure, including: + * - `EINVAL`: The condition variable is invalid or uninitialized. + * + * @note + * - This function does not release the associated mutex. + * - If no threads are currently waiting on the condition variable, the call has no effect. + * - The awakened thread will not run until it can reacquire the associated mutex and + * re-evaluate the waiting condition. + * - It is typically used when only one waiting thread should be allowed to proceed. + * + * @see pthread_cond_broadcast, pthread_cond_wait, pthread_cond_init, pthread_cond_destroy + */ int pthread_cond_signal(pthread_cond_t *cond) { rt_base_t temp; @@ -210,6 +306,35 @@ int pthread_cond_signal(pthread_cond_t *cond) } RTM_EXPORT(pthread_cond_signal); +/** + * @brief Waits on a condition variable with a timeout. + * + * This function causes the calling thread to block on the condition variable `cond`, + * releasing the associated mutex `mutex`. The thread will remain blocked until + * one of the following occurs: + * - It is signaled or broadcast using `pthread_cond_signal` or `pthread_cond_broadcast`. + * - The specified timeout expires. + * + * @param cond A pointer to the condition variable to wait on. + * Must point to a valid, initialized condition variable. + * @param mutex A pointer to the mutex associated with the condition variable. + * Must be locked by the calling thread before invoking this function. + * @param timeout The timeout duration in milliseconds. A value of `RT_WAITING_FOREVER` + * indicates the thread will wait indefinitely. + * + * @return + * - `RT_EOK` on successful wakeup (signaled or broadcast). + * - `-RT_ETIMEOUT` if the timeout expires before the condition variable is signaled. + * - `-RT_ERROR` if an error occurs (e.g., invalid parameters). + * + * @note + * - The mutex is automatically released while the thread waits and re-acquired before + * the function returns. + * - If `timeout` is 0, the function behaves as a non-blocking check. + * - Ensure the condition variable and mutex are properly initialized before use. + * + * @see pthread_cond_signal, pthread_cond_broadcast, pthread_mutex_lock, pthread_mutex_unlock + */ rt_err_t _pthread_cond_timedwait(pthread_cond_t *cond, pthread_mutex_t *mutex, rt_int32_t timeout) @@ -327,6 +452,33 @@ rt_err_t _pthread_cond_timedwait(pthread_cond_t *cond, } RTM_EXPORT(_pthread_cond_timedwait); +/** + * @brief Waits on a condition variable. + * + * This function blocks the calling thread on the condition variable `cond` and releases + * the associated mutex `mutex`. The thread remains blocked until it is signaled or + * broadcast using `pthread_cond_signal` or `pthread_cond_broadcast`. When the thread + * is awakened, it re-acquires the mutex and resumes execution. + * + * @param cond A pointer to the condition variable to wait on. + * Must point to a valid, initialized condition variable. + * @param mutex A pointer to the mutex associated with the condition variable. + * Must be locked by the calling thread before invoking this function. + * + * @return + * - `0` on success. + * - A non-zero error code on failure, including: + * - `EINVAL`: The condition variable or mutex is invalid or uninitialized. + * + * @note + * - The mutex must be locked before calling this function. + * - Upon returning, the mutex is locked again by the calling thread. + * - Spurious wakeups may occur, so the thread should always recheck the waiting + * condition upon wakeup. + * - This function may block indefinitely unless the condition is signaled or broadcast. + * + * @see pthread_cond_signal, pthread_cond_broadcast, pthread_cond_timedwait, pthread_mutex_lock + */ int pthread_cond_wait(pthread_cond_t *cond, pthread_mutex_t *mutex) { rt_err_t result; @@ -349,6 +501,37 @@ __retry: } RTM_EXPORT(pthread_cond_wait); +/** + * @brief Waits on a condition variable with a timeout. + * + * This function blocks the calling thread on the condition variable `cond`, releasing + * the associated mutex `mutex`. The thread remains blocked until one of the following occurs: + * - The condition variable is signaled or broadcast using `pthread_cond_signal` or `pthread_cond_broadcast`. + * - The specified absolute timeout `abstime` is reached. + * - A spurious wakeup occurs (requiring the thread to recheck the condition). + * + * @param cond A pointer to the condition variable to wait on. + * Must point to a valid, initialized condition variable. + * @param mutex A pointer to the mutex associated with the condition variable. + * Must be locked by the calling thread before invoking this function. + * @param abstime A pointer to a `struct timespec` specifying the absolute timeout (in seconds and nanoseconds + * since the Epoch). If the time specified is already reached, the function immediately returns. + * + * @return + * - `0` on successful wakeup (signaled or broadcast). + * - `ETIMEDOUT` if the timeout expires before the condition variable is signaled. + * - A non-zero error code on failure, including: + * - `EINVAL`: The condition variable, mutex, or `abstime` is invalid. + * - `EPERM`: The mutex is not owned by the calling thread. + * + * @note + * - The mutex is released while the thread is waiting and re-acquired before the function returns. + * - Spurious wakeups may occur, so the thread must always recheck the waiting condition upon wakeup. + * - The timeout is specified in absolute time, not relative duration. + * - Ensure the condition variable and mutex are properly initialized before use. + * + * @see pthread_cond_wait, pthread_cond_signal, pthread_cond_broadcast, pthread_mutex_lock + */ int pthread_cond_timedwait(pthread_cond_t *cond, pthread_mutex_t *mutex, const struct timespec *abstime)