[components/libc/posix]add comments for thread local storage APIs.

Author: GorrayLi

components/libc/posix/pthreads/pthread_tls.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
  *
@@ -21,6 +21,31 @@ static int pthread_key_system_init(void)
 }
 INIT_COMPONENT_EXPORT(pthread_key_system_init);
 
+/**
+ * @brief Retrieves the value associated with a thread-specific data key for the calling thread.
+ *
+ * This function returns the value that was previously set for the specified key
+ * in the calling thread using `pthread_setspecific`. Each thread has its own independent
+ * value for the same key.
+ *
+ * @param[in] key
+ *     The thread-specific data key, created using `pthread_key_create`.
+ *
+ * @return
+ * - The value associated with the key for the calling thread, or `NULL` if no value
+ *   has been set for the key in this thread.
+ *
+ * @note
+ * - If no value has been set for the key in the calling thread, `pthread_getspecific`
+ *   returns `NULL`. This does not indicate an error unless `NULL` was explicitly set as the value.
+ * - The value retrieved is specific to the calling thread and may differ for other threads.
+ *
+ * @attention
+ * - If the key has been deleted using `pthread_key_delete`, the behavior of this
+ *   function is undefined.
+ *
+ * @see pthread_key_create(), pthread_setspecific(), pthread_key_delete()
+ */
 void *pthread_getspecific(pthread_key_t key)
 {
     struct _pthread_data* ptd;
@@ -41,6 +66,37 @@ void *pthread_getspecific(pthread_key_t key)
 }
 RTM_EXPORT(pthread_getspecific);
 
+/**
+ * @brief Associates a value with a thread-specific data key for the calling thread.
+ *
+ * This function sets a thread-specific value for the given key. Each thread has its
+ * own independent value associated with the same key, and this value is not shared with
+ * other threads.
+ *
+ * @param[in] key
+ *     The thread-specific data key, created using `pthread_key_create`.
+ * @param[in] value
+ *     The value to associate with the key for the calling thread. The value can be
+ *     a pointer to any data or `NULL`.
+ *
+ * @return
+ * - `0`: The value was successfully set.
+ * - `EINVAL`: The specified key is invalid or not initialized.
+ *
+ * @note
+ * - Setting a new value for a key in a thread overwrites any previously set value
+ *   for that key in the same thread.
+ * - The value set using `pthread_setspecific` is accessible via `pthread_getspecific`
+ *   for the same thread.
+ * - The association between the key and value is valid until the thread terminates,
+ *   the key is deleted using `pthread_key_delete`, or a new value is set with this function.
+ *
+ * @attention
+ * - The value is specific to the calling thread; other threads will not be affected
+ *   and will continue to maintain their own independent values for the same key.
+ *
+ * @see pthread_key_create(), pthread_getspecific(), pthread_key_delete()
+ */
 int pthread_setspecific(pthread_key_t key, const void *value)
 {
     struct _pthread_data* ptd;
@@ -68,6 +124,35 @@ int pthread_setspecific(pthread_key_t key, const void *value)
 }
 RTM_EXPORT(pthread_setspecific);
 
+/**
+ * @brief Creates a thread-specific data key.
+ *
+ * This function allocates a unique key for thread-specific data (TSD).
+ * Each thread can use this key to access its own specific data associated with it.
+ *
+ * @param[out] key
+ *     A pointer to a variable where the newly created key will be stored.
+ *     On success, `*key` will hold the newly allocated key.
+ * @param[in] destructor
+ *     An optional destructor function pointer. This function will be called to
+ *     clean up thread-specific data associated with the key when a thread terminates.
+ *     Pass `NULL` if no cleanup is required.
+ *
+ * @return
+ * - `0`: The key was successfully created.
+ * - `EAGAIN`: The system has reached the maximum number of available keys, and no new key can be allocated.
+ *
+ * @note
+ * - Each thread can use `pthread_setspecific` and `pthread_getspecific` to set and retrieve the thread-specific data associated with the key.
+ * - The destructor function will be invoked automatically by the system when the thread terminates, if not explicitly called.
+ *
+ * @attention
+ * - If the `destructor` function is invoked and it sets thread-specific data for the same key,
+ *   the destructor may be called multiple times, up to a limit defined by the system
+ *   (typically `PTHREAD_DESTRUCTOR_ITERATIONS`).
+ *
+ * @see pthread_setspecific(), pthread_getspecific(), pthread_key_delete()
+ */
 int pthread_key_create(pthread_key_t *key, void (*destructor)(void*))
 {
     rt_uint32_t index;
@@ -94,6 +179,29 @@ int pthread_key_create(pthread_key_t *key, void (*destructor)(void*))
 }
 RTM_EXPORT(pthread_key_create);
 
+/**
+ * @brief Deletes a thread-specific data key.
+ *
+ * This function deletes a previously created thread-specific data key.
+ * The key will no longer be valid for use in `pthread_setspecific` or `pthread_getspecific`.
+ *
+ * @param[in] key
+ *     The thread-specific data key to delete. The key must have been created with
+ *     `pthread_key_create`.
+ *
+ * @return
+ * - `0`: The key was successfully deleted.
+ * - `EINVAL`: The specified key is invalid or has not been initialized.
+ *
+ * @note
+ * - Deleting a key does not automatically free or clean up the thread-specific data
+ *   associated with the key. It is the programmer's responsibility to ensure that
+ *   associated resources are properly released, if necessary.
+ * - After deletion, using the key in `pthread_setspecific` or `pthread_getspecific`
+ *   will result in undefined behavior.
+ *
+ * @see pthread_key_create(), pthread_setspecific(), pthread_getspecific()
+ */
 int pthread_key_delete(pthread_key_t key)
 {
     if (key >= PTHREAD_KEY_MAX)