[components/libc/posix][pthreads]add comments for thread APIs of pthread.

components/libc/posix/pthreads/pthread.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
  *
@@ -213,6 +213,42 @@ static void pthread_entry_stub(void *parameter)
     }
 }
 
+/**
+ * @brief Creates a new thread in a POSIX-compliant system.
+ *
+ * The `pthread_create` function initializes a new thread in the calling process. The new thread starts execution
+ * by invoking the function specified by the `start` parameter. The thread runs concurrently with the calling thread.
+ *
+ * @param[out] pid
+ *   A pointer to a `pthread_t` object where the ID of the newly created thread will be stored.
+ *   This ID can be used to refer to the thread in subsequent function calls.
+ *
+ * @param[in] attr
+ *   A pointer to a `pthread_attr_t` object that specifies attributes for the new thread, or `NULL` for default attributes.
+ *   Default attributes include:
+ *   - Detached state: joinable.
+ *   - Stack size: implementation-defined default.
+ *
+ * @param[in] start
+ *   A pointer to the function that the new thread will execute. This function must have the following signature:
+ *   `void *start(void *parameter)`.
+ *
+ * @param[in] parameter
+ *   A pointer to data passed as an argument to the `start` function. The meaning and handling of this data is determined
+ *   by the `start` function.
+ *
+ * @return
+ *   Returns 0 on success. On failure, a non-zero error code is returned, indicating the error condition:
+ *   - `EAGAIN`: Insufficient resources to create another thread.
+ *   - `EINVAL`: Invalid attributes specified in `attr`.
+ *   - `EPERM`: Insufficient permissions to set the requested attributes.
+ *
+ * @note
+ *   It is the caller's responsibility to manage the lifetime of any resources associated with the new thread.
+ *   If the thread is not detached, it must be joined using `pthread_join` to avoid resource leaks.
+ *
+ * @see pthread_join, pthread_exit, pthread_attr_init
+ */
 int pthread_create(pthread_t            *pid,
                    const pthread_attr_t *attr,
                    void *(*start)(void *), void *parameter)
@@ -334,6 +370,28 @@ __exit:
 }
 RTM_EXPORT(pthread_create);
 
+/**
+ * @brief Marks a thread as detached, allowing its resources to be automatically released upon termination.
+ *
+ * The `pthread_detach` function separates the specified thread from the calling thread. Once a thread is detached,
+ * its resources will be automatically reclaimed by the system upon the thread's termination. A detached thread cannot
+ * be joined using `pthread_join`.
+ *
+ * @param[in] thread
+ *   The thread ID of the thread to be detached. This must be a valid thread ID returned by `pthread_create`.
+ *
+ * @return
+ *   Returns 0 on success. On failure, an error code is returned:
+ *   - `EINVAL`: The specified thread is not joinable or is already detached.
+ *   - `ESRCH`: No thread with the specified ID could be found.
+ *
+ * @note
+ *   - Detaching a thread allows it to run independently. Once detached, the thread's termination status cannot
+ *     be retrieved, and it cannot be joined.
+ *   - Threads can be created in a detached state using attributes set with `pthread_attr_setdetachstate`.
+ *
+ * @see pthread_create, pthread_join, pthread_attr_setdetachstate
+ */
 int pthread_detach(pthread_t thread)
 {
     int ret = 0;
@@ -378,6 +436,33 @@ __exit:
 }
 RTM_EXPORT(pthread_detach);
 
+/**
+ * @brief Waits for the specified thread to terminate and retrieves its exit status.
+ *
+ * The `pthread_join` function blocks the calling thread until the specified thread terminates.
+ * If the specified thread has already terminated, it returns immediately. The exit status of
+ * the terminated thread can optionally be retrieved via the `value_ptr` parameter.
+ *
+ * @param[in] thread
+ *   The thread ID of the thread to wait for. This must be a joinable thread created with `pthread_create`.
+ *
+ * @param[out] value_ptr
+ *   A pointer to a location where the exit status of the terminated thread will be stored.
+ *   If the thread terminated by calling `pthread_exit`, the value passed to `pthread_exit`
+ *   will be stored at this location. If this parameter is `NULL`, the exit status is ignored.
+ *
+ * @return
+ *   Returns 0 on success. On failure, an error code is returned:
+ *   - `ESRCH`: The specified thread does not exist.
+ *   - `EINVAL`: The specified thread is not joinable.
+ *   - `EDEADLK`: A deadlock was detected (e.g., a thread tries to join itself).
+ *
+ * @note
+ *   - Threads must not be detached to use `pthread_join`.
+ *   - If `pthread_join` is not called for joinable threads, their resources are not released, leading to resource leaks.
+ *
+ * @see pthread_create, pthread_exit, pthread_detach
+ */
 int pthread_join(pthread_t thread, void **value_ptr)
 {
     _pthread_data_t *ptd;
@@ -390,7 +475,7 @@ int pthread_join(pthread_t thread, void **value_ptr)
         return EINVAL; /* invalid pthread id */
     }
 
-    if (ptd && ptd->tid == rt_thread_self())
+    if (ptd->tid == rt_thread_self())
     {
         /* join self */
         return EDEADLK;
@@ -420,6 +505,25 @@ int pthread_join(pthread_t thread, void **value_ptr)
 }
 RTM_EXPORT(pthread_join);
 
+/**
+ * @brief Returns the thread ID of the calling thread.
+ *
+ * The `pthread_self` function returns the thread ID of the calling thread. The thread ID is unique to the
+ * thread within a process and can be used to identify the calling thread in the context of multithreading.
+ *
+ * The value returned by `pthread_self` can be compared with the thread IDs of other threads to determine
+ * if two threads are the same.
+ *
+ * @return
+ *   The thread ID of the calling thread.
+ *
+ * @note
+ *   - The thread ID returned by `pthread_self` is not the same as the operating system's thread ID.
+ *   - This function does not affect the calling thread's state or execution.
+ *   - The thread ID returned by `pthread_self` is only meaningful in the context of the current process.
+ *
+ * @see pthread_create, pthread_equal, pthread_join
+ */
 pthread_t pthread_self (void)
 {
     rt_thread_t tid;
@@ -436,6 +540,32 @@ pthread_t pthread_self (void)
 }
 RTM_EXPORT(pthread_self);
 
+/**
+ * @brief Retrieves the clock ID for the specified thread.
+ *
+ * The `pthread_getcpuclockid` function retrieves the clock ID associated with the CPU time used
+ * by the specified thread.
+ *
+ * @param[in] thread
+ *   The thread whose CPU clock ID is to be retrieved. If the thread is the calling thread,
+ *   the current thread's ID is used.
+ *
+ * @param[out] clock_id
+ *   A pointer to a `clockid_t` variable that will be filled with the clock ID associated
+ *   with the specified thread.
+ *
+ * @return
+ *   - `0` on success.
+ *   - `EINVAL` if the `thread` is not a valid thread identifier.
+ *   - `ESRCH` if the specified thread does not exist.
+ *
+ * @note
+ *   The clock returned by this function is specific to the thread and is different from the
+ *   system-wide clock. It measures the CPU time consumed by the specified thread, not wall-clock
+ *   time. The thread's CPU time can be obtained using `clock_gettime` with the returned `clock_id`.
+ *
+ * @see clock_gettime, pthread_create, pthread_self
+ */
 int pthread_getcpuclockid(pthread_t thread, clockid_t *clock_id)
 {
     if(_pthread_get_data(thread) == NULL)
@@ -449,12 +579,62 @@ int pthread_getcpuclockid(pthread_t thread, clockid_t *clock_id)
 }
 RTM_EXPORT(pthread_getcpuclockid);
 
+/**
+ * @brief Retrieves the current concurrency level of the program.
+ *
+ * The `pthread_getconcurrency` function returns the current concurrency level of the program.
+ * This value represents the number of threads that can run concurrently in the program,
+ * based on the current settings of the pthreads library. It is used to help tune the behavior
+ * of thread scheduling in some systems.
+ *
+ * @return
+ *   The current concurrency level of the program.
+ *   - The value is an integer representing the number of threads that are permitted to run
+ *     concurrently in the system, based on the library's current configuration.
+ *   - A return value of `0` typically means that the system is using the default concurrency
+ *     level, which may be determined automatically by the system or by thread creation behavior.
+ *
+ * @note
+ *   - The behavior and meaning of concurrency levels can be implementation-dependent,
+ *     and it may vary across different systems or environments.
+ *   - The function is typically used for diagnostic purposes, and its behavior may not
+ *     affect thread execution directly.
+ *
+ * @see pthread_setconcurrency
+ */
 int pthread_getconcurrency(void)
 {
     return concurrency_level;
 }
 RTM_EXPORT(pthread_getconcurrency);
 
+/**
+ * @brief Sets the concurrency level of the program.
+ *
+ * The `pthread_setconcurrency` function sets the number of threads that are allowed to run concurrently.
+ * The concurrency level defines the maximum number of threads that can be executed in parallel by the system.
+ * This is useful for tuning thread behavior and controlling system resource usage, especially in environments
+ * with limited resources (e.g., CPU cores).
+ *
+ * @param[in] new_level
+ *   The new concurrency level to be set. This value represents the number of threads that can execute concurrently.
+ *   - A value of `0` typically means that the system will automatically determine the concurrency level based on
+ *     the system's configuration and available resources.
+ *   - A non-zero value explicitly sets the maximum number of threads that can run concurrently.
+ *
+ * @return
+ *   - `0` on success.
+ *   - `EINVAL` if the `new_level` is invalid or if the system does not support this functionality.
+ *
+ * @note
+ *   - The behavior of this function is system-dependent. Some systems may ignore the concurrency setting
+ *     and automatically manage the concurrency based on available resources (e.g., CPU cores).
+ *   - This function may not have any effect on systems that do not support concurrency settings at the library level.
+ *   - The concurrency level controls thread scheduling policies and is intended to influence how the thread library
+ *     manages threads, not how the operating system schedules them at the kernel level.
+ *
+ * @see pthread_getconcurrency
+ */
 int pthread_setconcurrency(int new_level)
 {
     concurrency_level = new_level;
@@ -463,6 +643,44 @@ int pthread_setconcurrency(int new_level)
 }
 RTM_EXPORT(pthread_setconcurrency);
 
+/**
+ * @brief Retrieves the scheduling policy and parameters of a thread.
+ *
+ * The `pthread_getschedparam` function retrieves the scheduling policy and the scheduling parameters
+ * (such as priority) for the specified thread. This allows you to check the scheduling settings of a thread
+ * and can be useful for thread management and performance tuning in a multithreaded application.
+ *
+ * @param[in] thread
+ *   The thread whose scheduling policy and parameters are to be retrieved. This is typically a valid
+ *   `pthread_t` identifier of a thread that has already been created.
+ *
+ * @param[out] policy
+ *   A pointer to an integer where the scheduling policy of the specified thread will be stored. The
+ *   value will be one of the following constants defined in `<sched.h>`:
+ *   - `SCHED_FIFO`: First-in, first-out scheduling policy.
+ *   - `SCHED_RR`: Round-robin scheduling policy.
+ *   - `SCHED_OTHER`: Default policy, which is typically used by non-realtime threads.
+ *   - `SCHED_IDLE`: For idle threads (system-level threads that do minimal work).
+ *   - `SCHED_BATCH`: For threads that should be scheduled with lower priority than interactive threads.
+ *   - `SCHED_DEADLINE`: A policy that allows specifying real-time deadlines (on systems that support it).
+ *
+ * @param[out] param
+ *   A pointer to a `struct sched_param` where the scheduling parameters (e.g., priority) for the thread
+ *   will be stored. The `sched_param` structure typically contains:
+ *   - `sched_priority`: The priority value associated with the thread's scheduling policy.
+ *
+ * @return
+ *   - `0` on success.
+ *   - `ESRCH` if the specified thread does not exist.
+ *   - `EINVAL` if an invalid argument is provided, such as an invalid thread ID or null pointers for the policy or parameters.
+ *
+ * @note
+ *   - This function retrieves the current scheduling settings for a thread. These settings can be used
+ *     to monitor or adjust thread behavior.
+ *   - The scheduling policies and priorities may be platform-dependent and subject to system configuration.
+ *
+ * @see pthread_setschedparam, sched_getparam
+ */
 int pthread_getschedparam(pthread_t thread, int *policy, struct sched_param *param)
 {
     _pthread_data_t *ptd;
@@ -475,6 +693,47 @@ int pthread_getschedparam(pthread_t thread, int *policy, struct sched_param *par
 }
 RTM_EXPORT(pthread_getschedparam);
 
+/**
+ * @brief Sets the scheduling policy and parameters for a thread.
+ *
+ * The `pthread_setschedparam` function sets the scheduling policy and scheduling parameters (such as priority)
+ * for the specified thread. This allows you to control how the thread is scheduled by the operating system.
+ * It is useful for adjusting thread behavior, especially for real-time or performance-sensitive applications.
+ *
+ * @param[in] thread
+ *   The thread whose scheduling policy and parameters are to be set. This is a valid `pthread_t` identifier.
+ *
+ * @param[in] policy
+ *   The scheduling policy to be set for the thread. This can be one of the following values:
+ *   - `SCHED_FIFO`: First-in, first-out scheduling policy, where threads are scheduled based on their arrival time.
+ *   - `SCHED_RR`: Round-robin scheduling policy, where each thread is allocated a fixed time slice and scheduled cyclically.
+ *   - `SCHED_OTHER`: Default policy for non-realtime threads.
+ *   - `SCHED_IDLE`: For threads intended to run only when no other threads are runnable.
+ *   - `SCHED_BATCH`: For threads that should run with lower priority than interactive threads.
+ *   - `SCHED_DEADLINE`: For real-time threads that have a specified deadline (if supported).
+ *
+ * @param[in] param
+ *   A pointer to a `struct sched_param`, which contains the scheduling parameters, typically the thread's priority.
+ *   The `sched_priority` field is the most commonly used parameter, and it controls the thread's priority within
+ *   the specified scheduling policy.
+ *
+ * @return
+ *   - `0` on success.
+ *   - `EINVAL` if an invalid policy or parameter is provided.
+ *   - `ESRCH` if the specified thread does not exist.
+ *   - `EPERM` if the caller does not have permission to modify the thread's scheduling attributes.
+ *
+ * @note
+ *   - The `sched_param` structure's `sched_priority` field specifies the priority of the thread. The priority
+ *     range depends on the policy used. For example, for `SCHED_FIFO` and `SCHED_RR`, higher priority values
+ *     correspond to higher priority threads, while for `SCHED_OTHER`, priorities are not as strictly enforced.
+ *   - Changing a thread's scheduling parameters may affect its execution behavior, including how it competes with
+ *     other threads for CPU time.
+ *   - The system may not allow you to modify scheduling parameters for all threads, depending on system configuration
+ *     and privileges.
+ *
+ * @see pthread_getschedparam
+ */
 int pthread_setschedparam(pthread_t thread, int policy, const struct sched_param *param)
 {
     _pthread_data_t *ptd;
@@ -487,6 +746,35 @@ int pthread_setschedparam(pthread_t thread, int policy, const struct sched_param
 }
 RTM_EXPORT(pthread_setschedparam);
 
+/**
+ * @brief Sets the scheduling priority for a thread.
+ *
+ * The `pthread_setschedprio` function adjusts the priority of the specified thread while leaving its
+ * scheduling policy unchanged. This is useful for fine-tuning thread behavior in multithreaded applications.
+ *
+ * @param[in] thread
+ *   The thread whose scheduling priority is to be changed. This must be a valid `pthread_t` identifier.
+ *
+ * @param[in] prio
+ *   The new scheduling priority for the thread. The priority must fall within the valid range for the
+ *   thread's current scheduling policy, as defined by `sched_get_priority_min` and `sched_get_priority_max`.
+ *
+ * @return
+ *   - `0` on success.
+ *   - `EINVAL` if the specified priority is invalid for the thread's current scheduling policy.
+ *   - `ESRCH` if the specified thread does not exist.
+ *   - `EPERM` if the calling process lacks the necessary privileges to set the thread's priority.
+ *
+ * @note
+ *   - Changing a thread's priority may require elevated privileges (e.g., root) on certain systems, especially
+ *     for real-time priorities.
+ *   - The priority range and behavior depend on the thread's current scheduling policy. For example:
+ *     - `SCHED_FIFO` and `SCHED_RR`: Priorities are used for strict scheduling.
+ *     - `SCHED_OTHER`: Priorities may have minimal or no effect.
+ *   - The behavior of this function is platform-dependent and may vary between different operating systems.
+ *
+ * @see pthread_setschedparam, pthread_getschedparam
+ */
 int pthread_setschedprio(pthread_t thread, int prio)
 {
     _pthread_data_t *ptd;
@@ -500,6 +788,24 @@ int pthread_setschedprio(pthread_t thread, int prio)
 }
 RTM_EXPORT(pthread_setschedprio);
 
+/**
+ * @brief Terminates the calling thread and optionally returns a value.
+ *
+ * The `pthread_exit` function terminates the calling thread. It can optionally provide an exit status that can be
+ * retrieved by other threads that join the calling thread using `pthread_join`. If the thread is detached, the
+ * exit status is ignored and the system automatically reclaims resources once the thread terminates.
+ *
+ * @param[in] value
+ *   A pointer to a value that will be returned to any thread that calls `pthread_join` on this thread.
+ *   If `NULL`, no value is returned.
+ *
+ * @note
+ *   - This function does not terminate the process. It only terminates the calling thread.
+ *   - If the calling thread is the main thread, `pthread_exit` allows other threads to continue execution.
+ *   - If a thread terminates without calling `pthread_exit`, it returns control to the system when the thread's function ends.
+ *
+ * @see pthread_join, pthread_create
+ */
 void pthread_exit(void *value)
 {
     _pthread_data_t *ptd;
@@ -564,6 +870,33 @@ void pthread_exit(void *value)
 }
 RTM_EXPORT(pthread_exit);
 
+/**
+ * @brief Executes a routine once in a multithreaded environment.
+ *
+ * The `pthread_once` function ensures that the specified initialization routine is executed exactly once,
+ * even if multiple threads attempt to execute it simultaneously. It is typically used for one-time
+ * initialization tasks in a multithreaded program.
+ *
+ * @param[in] once_control
+ *   A pointer to a `pthread_once_t` control variable. The init_routine can only be excuted
+ *   when (*once_control) is zero.
+ *
+ * @param[in] init_routine
+ *   A pointer to the initialization routine to be executed. This routine takes no arguments and
+ *   returns no value. It is guaranteed to be executed exactly once.
+ *
+ * @return
+ *   - `0` on success.
+ *
+ * @note
+ *   - The `pthread_once` function is thread-safe and guarantees that the `init_routine` is called only once.
+ *   - The `once_control` variable must remain valid and should not be modified by the application after
+ *     initialization.
+ *   - If the initialization routine fails or encounters an error, it is the responsibility of the routine
+ *     to handle it appropriately.
+ *
+ * @see pthread_mutex_lock, pthread_mutex_unlock
+ */
 int pthread_once(pthread_once_t *once_control, void (*init_routine)(void))
 {
     RT_ASSERT(once_control != RT_NULL);
@@ -590,6 +923,35 @@ int pthread_atfork(void (*prepare)(void), void (*parent)(void), void (*child)(vo
 }
 RTM_EXPORT(pthread_atfork);
 
+/**
+ * @brief Sends a signal to a specific thread.
+ *
+ * The `pthread_kill` function sends the specified signal to the target thread. This allows fine-grained
+ * control over signal handling in multithreaded applications.
+ *
+ * @param[in] thread
+ *   The target thread to which the signal is sent. This is a valid `pthread_t` identifier.
+ *
+ * @param[in] sig
+ *   The signal to be sent. This can be any valid signal, such as those defined in `<signal.h>`. For example:
+ *   - `SIGTERM`: Request thread termination.
+ *   - `SIGUSR1` or `SIGUSR2`: User-defined signals.
+ *   - `0`: Used to check if the thread is still valid without sending a signal.
+ *
+ * @return
+ *   - `0` on success.
+ *   - `ESRCH` if the specified thread does not exist or is invalid.
+ *   - `EINVAL` if the signal number `sig` is invalid.
+ *
+ * @note
+ *   - The signal is delivered to the specified thread only if the thread has the appropriate signal handlers
+ *     set up. Unhandled signals might result in the default action for that signal.
+ *   - If `sig` is `0`, no signal is sent, but the function checks if the thread is valid and exists.
+ *   - Signal handling behavior is shared across threads in a process. For example, blocking or ignoring a signal
+ *     in one thread affects the entire process.
+ *
+ * @see pthread_sigmask, sigaction
+ */
 int pthread_kill(pthread_t thread, int sig)
 {
 #ifdef RT_USING_SIGNALS
@@ -616,12 +978,62 @@ int pthread_kill(pthread_t thread, int sig)
 RTM_EXPORT(pthread_kill);
 
 #ifdef RT_USING_SIGNALS
+/**
+ * @brief Modifies or retrieves the signal mask of the calling thread.
+ *
+ * The `pthread_sigmask` function allows a thread to block, unblock, or examine the signals in its signal mask.
+ * Signals that are blocked are not delivered to the thread until they are unblocked.
+ *
+ * @param[in] how
+ *   Specifies how the signal mask is modified. Possible values:
+ *   - `SIG_BLOCK`: Add the signals in `set` to the current signal mask.
+ *   - `SIG_UNBLOCK`: Remove the signals in `set` from the current signal mask.
+ *   - `SIG_SETMASK`: Replace the current signal mask with the signals in `set`.
+ *
+ * @param[in] set
+ *   A pointer to a `sigset_t` containing the signals to be modified in the mask. Can be `NULL` if no change is needed.
+ *
+ * @param[out] oset
+ *   A pointer to a `sigset_t` where the previous signal mask will be stored. Can be `NULL` if the previous mask is not required.
+ *
+ * @return
+ *   - `0` on success.
+ *
+ * @note
+ *   - Signal masks are thread-specific in a multithreaded program.
+ *   - The `pthread_sigmask` function is designed for multithreaded programs, whereas `sigprocmask` should not be used.
+ *   - Blocking a signal prevents it from being delivered to the thread until unblocked.
+ *
+ * @see sigprocmask, sigaction, pthread_kill
+ */
 int pthread_sigmask(int how, const sigset_t *set, sigset_t *oset)
 {
     return sigprocmask(how, set, oset);
 }
 #endif
 
+/**
+ * @brief Unregisters a cleanup handler and optionally executes it.
+ *
+ * The `pthread_cleanup_pop` function unregisters a cleanup handler that was previously registered
+ * using `pthread_cleanup_push`. If the `execute` parameter is non-zero, the cleanup handler is executed
+ * at the point where the thread terminates or is canceled.
+ *
+ * If `execute` is zero, the handler is unregistered without being executed. This allows the handler
+ * to be removed from the cleanup stack without performing any actions.
+ *
+ * @param[in] execute
+ *   If non-zero, the cleanup handler is executed when the thread terminates or is canceled.
+ *   If zero, the handler is simply removed from the stack without executing it.
+ *
+ * @note
+ *   - Cleanup handlers are executed in the reverse order of their registration (i.e., last-in, first-out).
+ *   - It is important to use `pthread_cleanup_push` to register cleanup handlers and `pthread_cleanup_pop`
+ *     to ensure they are properly unregistered and executed if needed.
+ *   - This function should be paired with `pthread_cleanup_push` to manage cleanup handlers effectively.
+ *
+ * @see pthread_cleanup_push, pthread_exit, pthread_cancel
+ */
 void pthread_cleanup_pop(int execute)
 {
     _pthread_data_t *ptd;
@@ -651,6 +1063,33 @@ void pthread_cleanup_pop(int execute)
 }
 RTM_EXPORT(pthread_cleanup_pop);
 
+/**
+ * @brief Registers a cleanup handler to be executed when the calling thread terminates.
+ *
+ * The `pthread_cleanup_push` function registers a cleanup handler that is executed when the calling thread
+ * is canceled or exits (either normally or via `pthread_exit`). The cleanup handler will be executed
+ * in the reverse order of their registration.
+ *
+ * The cleanup handler can be used to release resources such as memory or file descriptors when the thread
+ * is terminated, whether it terminates normally or is canceled.
+ *
+ * @param[in] routine
+ *   A pointer to the cleanup handler function. The function must have the following signature:
+ *   `void routine(void* arg);`. It is invoked when the thread terminates or is canceled.
+ *
+ * @param[in] arg
+ *   A pointer to the argument that will be passed to the cleanup handler (`routine`).
+ *   This allows the handler to perform actions with the passed argument.
+ *
+ * @note
+ *   - The cleanup handler is automatically invoked when a thread terminates or is canceled.
+ *   - The cleanup handlers are executed in the reverse order of their registration, similar to how
+ *     destructors are executed in a stack-based fashion.
+ *   - `pthread_cleanup_pop` must be called to unregister the cleanup handler. It ensures that the handler
+ *     is only invoked during the thread's termination process.
+ *
+ * @see pthread_cleanup_pop, pthread_cancel, pthread_exit
+ */
 void pthread_cleanup_push(void (*routine)(void *), void *arg)
 {
     _pthread_data_t *ptd;
@@ -704,6 +1143,33 @@ RTM_EXPORT(pthread_cleanup_push);
  * functions are defined to be async-cancel safe.
  */
 
+/**
+ * @brief Sets the cancelability state of the calling thread.
+ *
+ * The `pthread_setcancelstate` function allows a thread to enable or disable its ability to be canceled
+ * by another thread. Cancelability determines if and when a thread responds to a cancellation request.
+ *
+ * @param[in] state
+ *   The new cancelability state for the calling thread. Possible values:
+ *   - `PTHREAD_CANCEL_ENABLE`: The thread can be canceled.
+ *   - `PTHREAD_CANCEL_DISABLE`: The thread cannot be canceled.
+ *
+ * @param[out] oldstate
+ *   A pointer to an integer where the previous cancelability state will be stored. Can be `NULL` if
+ *   the previous state is not needed.
+ *
+ * @return
+ *   - `0` on success.
+ *   - `EINVAL` if the `state` is not a valid cancelability state.
+ *
+ * @note
+ *   - The cancelability state affects how the thread responds to cancellation requests:
+ *     - In the `PTHREAD_CANCEL_DISABLE` state, cancellation requests are held pending until the state is changed to `PTHREAD_CANCEL_ENABLE`.
+ *   - Cancelability is distinct from the cancelability type, which controls the timing of cancellation (deferred or asynchronous).
+ *   - By default, threads are created with `PTHREAD_CANCEL_ENABLE`.
+ *
+ * @see pthread_cancel, pthread_setcanceltype
+ */
 int pthread_setcancelstate(int state, int *oldstate)
 {
     _pthread_data_t *ptd;
@@ -727,6 +1193,34 @@ int pthread_setcancelstate(int state, int *oldstate)
 }
 RTM_EXPORT(pthread_setcancelstate);
 
+/**
+ * @brief Sets the cancellation type of the calling thread.
+ *
+ * The `pthread_setcanceltype` function allows a thread to specify when it should respond to
+ * a cancellation request. The cancellation type can be set to deferred or asynchronous.
+ *
+ * @param[in] type
+ *   The new cancellation type for the calling thread. Possible values:
+ *   - `PTHREAD_CANCEL_DEFERRED`: Cancellation occurs at cancellation points (default behavior).
+ *   - `PTHREAD_CANCEL_ASYNCHRONOUS`: Cancellation occurs immediately when a request is received.
+ *
+ * @param[out] oldtype
+ *   A pointer to an integer where the previous cancellation type will be stored. Can be `NULL`
+ *   if the previous type is not required.
+ *
+ * @return
+ *   - `0` on success.
+ *   - `EINVAL` if the `type` is not a valid cancellation type.
+ *
+ * @note
+ *   - The cancellation type determines when a thread processes a cancellation request:
+ *     - **Deferred**: The thread responds to cancellation only at well-defined cancellation points.
+ *     - **Asynchronous**: The thread can be canceled immediately, which may lead to resource inconsistencies.
+ *   - By default, threads use `PTHREAD_CANCEL_DEFERRED`.
+ *   - Asynchronous cancellation should be used cautiously as it can interrupt a thread at any point.
+ *
+ * @see pthread_cancel, pthread_setcancelstate, pthread_testcancel
+ */
 int pthread_setcanceltype(int type, int *oldtype)
 {
     _pthread_data_t *ptd;
@@ -748,6 +1242,23 @@ int pthread_setcanceltype(int type, int *oldtype)
 }
 RTM_EXPORT(pthread_setcanceltype);
 
+/**
+ * @brief Explicitly checks for pending cancellation requests in the calling thread.
+ *
+ * The `pthread_testcancel` function allows a thread to determine if it has a pending
+ * cancellation request. If a cancellation request is pending and the thread's cancelability
+ * state is set to `PTHREAD_CANCEL_ENABLE`, the thread will terminate immediately.
+ *
+ * @note
+ *   - This function is a cancellation point, meaning it checks for cancellation and responds if applicable.
+ *   - If the thread's cancelability state is `PTHREAD_CANCEL_DISABLE`, the function has no effect.
+ *   - The thread will invoke any cleanup handlers registered with `pthread_cleanup_push` before termination.
+ *
+ * @return
+ *   This function does not return if a cancellation is performed. Otherwise, it returns normally.
+ *
+ * @see pthread_setcancelstate, pthread_setcanceltype, pthread_cancel
+ */
 void pthread_testcancel(void)
 {
     int cancel = 0;
@@ -766,6 +1277,30 @@ void pthread_testcancel(void)
 }
 RTM_EXPORT(pthread_testcancel);
 
+/**
+ * @brief Sends a cancellation request to a specified thread.
+ *
+ * The `pthread_cancel` function requests the cancellation of the thread identified by `thread`.
+ * The actual response to the request depends on the target thread's cancelability state and type.
+ *
+ * @param[in] thread
+ *   The identifier of the thread to be canceled.
+ *
+ * @return
+ *   - `0` on success.
+ *   - `EINVAL` if the specified thread does not exist.
+ *
+ * @note
+ *   - Cancellation is an asynchronous mechanism. The thread may not terminate immediately or at all
+ *     if its cancelability state is set to `PTHREAD_CANCEL_DISABLE`.
+ *   - If the thread is cancelable and terminates, it invokes cleanup handlers registered with
+ *     `pthread_cleanup_push` before termination.
+ *   - The thread's cancellation type determines when it processes the cancellation request:
+ *     - `PTHREAD_CANCEL_DEFERRED` (default): At specific cancellation points.
+ *     - `PTHREAD_CANCEL_ASYNCHRONOUS`: Immediately upon receipt of the request.
+ *
+ * @see pthread_setcancelstate, pthread_setcanceltype, pthread_testcancel
+ */
 int pthread_cancel(pthread_t thread)
 {
     _pthread_data_t *ptd;