From dd709c1cea4289d841dda413c60e90dbc5ec6193 Mon Sep 17 00:00:00 2001 From: ligr Date: Fri, 22 Nov 2024 10:15:59 +0800 Subject: [PATCH] [components/libc/posix]add comments for thread local storage APIs. --- components/libc/posix/pthreads/pthread_tls.c | 110 ++++++++++++++++++- 1 file changed, 109 insertions(+), 1 deletion(-) diff --git a/components/libc/posix/pthreads/pthread_tls.c b/components/libc/posix/pthreads/pthread_tls.c index c14f3630ed..996c117a5b 100644 --- a/components/libc/posix/pthreads/pthread_tls.c +++ b/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)