[components/libc/posix]add comments for rwlock APIs.

components/libc/posix/pthreads/pthread_rwlock.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
  *
@@ -50,6 +50,31 @@ int pthread_rwlockattr_setpshared(pthread_rwlockattr_t *attr, int pshared)
 }
 RTM_EXPORT(pthread_rwlockattr_setpshared);
 
+/**
+ * @brief Initializes a read-write lock.
+ *
+ * This function initializes the read-write lock object pointed to by `rwlock` with the
+ * attributes specified by `attr`. If `attr` is `NULL`, the default attributes are used.
+ * A read-write lock allows multiple threads to read or a single thread to write, but not both simultaneously.
+ *
+ * @param rwlock A pointer to the read-write lock object to be initialized.
+ *               Must point to valid memory.
+ * @param attr A pointer to the attributes for the read-write lock.
+ *             If `NULL`, default attributes are applied.
+ *
+ * @return
+ * - `0` on success.
+ * - A non-zero error code on failure, including:
+ *   - `EINVAL`: Invalid attributes.
+ *
+ * @note
+ * - The read-write lock must be destroyed using `pthread_rwlock_destroy()` when it is no longer needed.
+ * - 'rw_mutex' is used for protecting rwlock data.
+ *   'rw_condreaders' is a condition variable for controlling readers.
+ *   'rw_condwriters' is a condition variable for controlling writers.
+ *
+ * @see pthread_rwlock_destroy, pthread_rwlock_rdlock, pthread_rwlock_wrlock, pthread_rwlock_unlock
+ */
 int pthread_rwlock_init(pthread_rwlock_t           *rwlock,
                         const pthread_rwlockattr_t *attr)
 {
@@ -69,6 +94,30 @@ int pthread_rwlock_init(pthread_rwlock_t           *rwlock,
 }
 RTM_EXPORT(pthread_rwlock_init);
 
+/**
+ * @brief Destroys a read-write lock.
+ *
+ * This function destroys the read-write lock object pointed to by `rwlock`. After
+ * the lock is destroyed, it cannot be used until it is reinitialized with
+ * `pthread_rwlock_init`. Any threads currently blocked on the lock are affected by the destruction.
+ *
+ * @param rwlock A pointer to the read-write lock object to be destroyed.
+ *               Must point to a valid, initialized read-write lock.
+ *
+ * @return
+ * - `0` on success.
+ * - A non-zero error code on failure, including:
+ *   - `EINVAL`: The `rwlock` is invalid or uninitialized.
+ *   - `EBUSY`: The lock is currently in use by a thread, and cannot be destroyed.
+ *
+ * @note
+ * - The read-write lock must not be in use (i.e., no threads should be blocked on it)
+ *   when `pthread_rwlock_destroy` is called.
+ * - Calling this function on an uninitialized or destroyed lock will result in undefined behavior.
+ * - Ensure that all threads have unlocked the lock before attempting to destroy it.
+ *
+ * @see pthread_rwlock_init, pthread_rwlock_rdlock, pthread_rwlock_wrlock, pthread_rwlock_unlock
+ */
 int pthread_rwlock_destroy (pthread_rwlock_t *rwlock)
 {
     int result;
@@ -122,6 +171,29 @@ int pthread_rwlock_destroy (pthread_rwlock_t *rwlock)
 }
 RTM_EXPORT(pthread_rwlock_destroy);
 
+/**
+ * @brief Acquire a read lock on a read-write lock.
+ *
+ * This function locks the specified read-write lock for reading. If the lock
+ * is already held by one or more threads for reading, the calling thread
+ * can acquire the lock as well (shared access). However, if the lock is
+ * held by another writer thread, or other writer thread has been waiting
+ * for the lock, the calling thread will block until the write lock is released.
+ *
+ * @param rwlock A pointer to the read-write lock to be locked.
+ *
+ * @return - 0 on success.
+ *         - EINVAL if the rwlock is invalid.
+ *         - EDEADLK if a deadlock condition is detected (optional; implementation-dependent).
+ *
+ * @note A thread that has acquired a read lock must eventually release it
+ *       using `pthread_rwlock_unlock`. Multiple read locks can be held
+ *       simultaneously, but a write lock excludes all other locks.
+ *
+ * @see pthread_rwlock_unlock
+ * @see pthread_rwlock_wrlock
+ * @see pthread_rwlock_tryrdlock
+ */
 int pthread_rwlock_rdlock(pthread_rwlock_t *rwlock)
 {
     int result;
@@ -156,6 +228,28 @@ int pthread_rwlock_rdlock(pthread_rwlock_t *rwlock)
 }
 RTM_EXPORT(pthread_rwlock_rdlock);
 
+/**
+ * @brief Try to acquire a read lock on a read-write lock without blocking.
+ *
+ * This function attempts to acquire a read lock on the specified read-write lock.
+ * If the lock is already held for writing, the function will return immediately
+ * without blocking the calling thread. If the lock is available for reading,
+ * it will be acquired successfully.
+ *
+ * @param rwlock A pointer to the read-write lock to attempt to lock.
+ *
+ * @return - 0 on success, indicating the read lock was acquired.
+ *         - EBUSY if the lock is currently held for writing by another thread.
+ *         - EINVAL if the rwlock is invalid.
+ *
+ * @note This function is non-blocking and returns immediately if the lock
+ *       cannot be acquired. After successfully acquiring the read lock,
+ *       the thread must release it using `pthread_rwlock_unlock`.
+ *
+ * @see pthread_rwlock_unlock
+ * @see pthread_rwlock_rdlock
+ * @see pthread_rwlock_trywrlock
+ */
 int pthread_rwlock_tryrdlock(pthread_rwlock_t *rwlock)
 {
     int result;
@@ -179,6 +273,35 @@ int pthread_rwlock_tryrdlock(pthread_rwlock_t *rwlock)
 }
 RTM_EXPORT(pthread_rwlock_tryrdlock);
 
+/**
+ * @brief Acquire a read lock on a read-write lock with a timeout.
+ *
+ * This function attempts to lock the specified read-write lock for reading,
+ * blocking until the lock becomes available or the specified timeout expires.
+ * If the lock is held for writing by another thread, the calling thread will
+ * block, but only up to the time specified by `abstime`.
+ *
+ * @param rwlock A pointer to the read-write lock to be locked.
+ * @param abstime A pointer to a `timespec` structure specifying the
+ *                    absolute timeout (in seconds and nanoseconds since the
+ *                    Epoch, 1970-01-01 00:00:00 UTC).
+ *
+ * @return - 0 on success, indicating the read lock was acquired.
+ *         - ETIMEDOUT if the timeout expired before the lock could be acquired.
+ *         - EINVAL if the `rwlock` is invalid or `abstime` contains invalid values.
+ *         - EDEADLK if a deadlock condition is detected (optional; implementation-dependent).
+ *
+ * @note The timeout is specified as an absolute time (not relative). After
+ *       acquiring the read lock, the thread must release it using
+ *       `pthread_rwlock_unlock`.
+ *
+ * @warning If the system clock is changed (e.g., via manual adjustment or
+ *          NTP synchronization), the timeout behavior may be affected.
+ *
+ * @see pthread_rwlock_unlock
+ * @see pthread_rwlock_rdlock
+ * @see pthread_rwlock_tryrdlock
+ */
 int pthread_rwlock_timedrdlock(pthread_rwlock_t      *rwlock,
                                const struct timespec *abstime)
 {
@@ -214,6 +337,35 @@ int pthread_rwlock_timedrdlock(pthread_rwlock_t      *rwlock,
 }
 RTM_EXPORT(pthread_rwlock_timedrdlock);
 
+/**
+ * @brief Acquire a write lock on a read-write lock with a timeout.
+ *
+ * This function attempts to acquire a write lock on the specified read-write lock,
+ * blocking until the lock becomes available or the specified timeout expires.
+ * If the lock is already held for reading or writing by another thread, the
+ * calling thread will block, but only up to the time specified by `abstime`.
+ *
+ * @param rwlock A pointer to the read-write lock to be locked.
+ * @param abstime A pointer to a `timespec` structure specifying the
+ *                    absolute timeout (in seconds and nanoseconds since the
+ *                    Epoch, 1970-01-01 00:00:00 UTC).
+ *
+ * @return
+ * - 0 on success, indicating the write lock was acquired.
+ * - EINVAL if the `rwlock` is invalid or `abstime` contains invalid values.
+ * - EDEADLK if a deadlock condition is detected (optional; implementation-dependent).
+ *
+ * @note The timeout is specified as an absolute time (not relative). After
+ *       acquiring the write lock, the thread must release it using
+ *       `pthread_rwlock_unlock`.
+ *
+ * @warning If the system clock is adjusted (e.g., manually or via NTP synchronization),
+ *          the timeout behavior may be affected.
+ *
+ * @see pthread_rwlock_unlock
+ * @see pthread_rwlock_wrlock
+ * @see pthread_rwlock_trywrlock
+ */
 int pthread_rwlock_timedwrlock(pthread_rwlock_t      *rwlock,
                                const struct timespec *abstime)
 {
@@ -248,6 +400,29 @@ int pthread_rwlock_timedwrlock(pthread_rwlock_t      *rwlock,
 }
 RTM_EXPORT(pthread_rwlock_timedwrlock);
 
+/**
+ * @brief Try to acquire a write lock on a read-write lock without blocking.
+ *
+ * This function attempts to acquire a write lock on the specified read-write lock.
+ * If the lock is already held for reading or writing by another thread, the function
+ * will return immediately without blocking the calling thread. If the lock is
+ * available, it will be acquired successfully.
+ *
+ * @param rwlock A pointer to the read-write lock to attempt to lock.
+ *
+ * @return
+ * - 0 on success, indicating the write lock was acquired.
+ * - EBUSY if the lock is currently held by another thread (read or write lock).
+ * - EINVAL if the `rwlock` is invalid.
+ *
+ * @note This function is non-blocking and returns immediately if the lock cannot
+ *       be acquired. After successfully acquiring the write lock, the thread must
+ *       release it using `pthread_rwlock_unlock`.
+ *
+ * @see pthread_rwlock_unlock
+ * @see pthread_rwlock_wrlock
+ * @see pthread_rwlock_timedwrlock
+ */
 int pthread_rwlock_trywrlock(pthread_rwlock_t *rwlock)
 {
     int result;
@@ -271,6 +446,28 @@ int pthread_rwlock_trywrlock(pthread_rwlock_t *rwlock)
 }
 RTM_EXPORT(pthread_rwlock_trywrlock);
 
+/**
+ * @brief Release a read or write lock on a read-write lock.
+ *
+ * This function unlocks the specified read-write lock, releasing either a read
+ * lock or a write lock held by the calling thread. If the calling thread does
+ * not hold the lock, the behavior is undefined.
+ *
+ * @param rwlock A pointer to the read-write lock to be unlocked.
+ *
+ * @return
+ * - 0 on success.
+ * - EINVAL if the `rwlock` is invalid.
+ *
+ * @note
+ * - This function must only be called by the thread that successfully acquired
+ *   the lock.
+ *
+ * @see pthread_rwlock_rdlock
+ * @see pthread_rwlock_wrlock
+ * @see pthread_rwlock_tryrdlock
+ * @see pthread_rwlock_trywrlock
+ */
 int pthread_rwlock_unlock(pthread_rwlock_t *rwlock)
 {
     int result;
@@ -305,6 +502,31 @@ int pthread_rwlock_unlock(pthread_rwlock_t *rwlock)
 }
 RTM_EXPORT(pthread_rwlock_unlock);
 
+/**
+ * @brief Acquire a write lock on a read-write lock.
+ *
+ * This function locks the specified read-write lock for writing. If the lock
+ * is already held by another thread for reading or writing, the calling thread
+ * blocks until the lock becomes available.
+ *
+ * @param rwlock A pointer to the read-write lock to be locked.
+ *
+ * @return
+ * - 0 on success, indicating the write lock was acquired.
+ * - EINVAL if the `rwlock` is invalid.
+ * - EDEADLK if a deadlock condition is detected (optional; implementation-dependent).
+ *
+ * @note
+ * - A write lock is exclusive, meaning no other thread can acquire a read or
+ *   write lock while a write lock is held.
+ * - The thread that successfully acquires the write lock must release it using
+ *   `pthread_rwlock_unlock`.
+ *
+ * @see pthread_rwlock_unlock
+ * @see pthread_rwlock_trywrlock
+ * @see pthread_rwlock_timedwrlock
+ * @see pthread_rwlock_rdlock
+ */
 int pthread_rwlock_wrlock(pthread_rwlock_t *rwlock)
 {
     int result;