james/SumProject
1
0
Fork 0
Code Issues Pull Requests Packages Projects Releases Wiki Activity

rtt更新

Browse Source
This commit is contained in:
dgjames
2025-01-18 13:25:25 +08:00
parent c6a7554b51
commit d6009a0773
726 changed files with 103376 additions and 6270 deletions
Download Patch File Download Diff File Expand all files Collapse all files

10
rt-thread/components/libc/compilers/common/cstring.c
View File

@@ -13,13 +13,13 @@
#include <rtthread.h>
#include <stdlib.h>
#ifndef RT_USING_PICOLIBC
/**
* @brief erases the data in the n bytes of the memory starting at the
* location pointed to by s, by writing zeros (bytes containing '\0') to that area.
*
* @note The bzero() function is deprecated (marked as LEGACY in POSIX. 1-2001).
*/
#ifndef RT_USING_PICOLIBC
void bzero(void* s, size_t n)
{
rt_memset(s, 0, n);
@@ -46,12 +46,12 @@ void explicit_bzero(void* s, size_t n)
}
}
char* index(const char* s, int c)
char *index(const char* s, int c)
{
return strchr(s, c);
}
char* rindex(const char* s, int c)
char *rindex(const char* s, int c)
{
return strrchr(s, c);
}
@@ -99,7 +99,7 @@ int ffsll(long long i)
*
* @note This function is GNU extension, available since glibc 2.1.91.
*/
void* memrchr(const void* ptr, int ch, size_t pos)
void *memrchr(const void* ptr, int ch, size_t pos)
{
char* end = (char*)ptr + pos - 1;
while (end != ptr)
@@ -118,7 +118,7 @@ size_t strnlen(const char *s, size_t maxlen)
return sc - s;
}
char* strchrnul(const char* s, int c)
char *strchrnul(const char* s, int c)
{
while (*s != '\0' && *s != c)
s++;

46
rt-thread/components/libc/compilers/common/ctime.c
View File

@@ -30,8 +30,10 @@
#include "sys/time.h"
#include <rthw.h>
#include <rtthread.h>
#ifdef RT_USING_RTC
#include <rtdevice.h>
#include <drivers/rtc.h>
#endif /* RT_USING_RTC */
#include <sys/errno.h>
#include <unistd.h>
#ifdef RT_USING_SMART
@@ -68,8 +70,8 @@ static const short __spm[13] =
(31 + 28 + 31 + 30 + 31 + 30 + 31 + 31 + 30 + 31 + 30 + 31),
};
rt_align(RT_ALIGN_SIZE) static const char *days = "Sun Mon Tue Wed Thu Fri Sat ";
rt_align(RT_ALIGN_SIZE) static const char *months = "Jan Feb Mar Apr May Jun Jul Aug Sep Oct Nov Dec ";
rt_align(RT_ALIGN_SIZE) static const char days[] = "Sun Mon Tue Wed Thu Fri Sat ";
rt_align(RT_ALIGN_SIZE) static const char months[] = "Jan Feb Mar Apr May Jun Jul Aug Sep Oct Nov Dec ";
#ifndef __isleap
static int __isleap(int year)
@@ -87,9 +89,9 @@ static void num2str(char *c, int i)
c[1] = i % 10 + '0';
}
#ifdef RT_USING_RTC
static rt_err_t _control_rtc(int cmd, void *arg)
{
#ifdef RT_USING_RTC
static rt_device_t device = RT_NULL;
rt_err_t rst = -RT_ERROR;
@@ -113,11 +115,8 @@ static rt_err_t _control_rtc(int cmd, void *arg)
return -RT_ENOSYS;
}
return rst;
#else
LOG_W(_WARNING_NO_RTC);
return -RT_ENOSYS;
#endif /* RT_USING_RTC */
}
#endif /* RT_USING_RTC */
/* lightweight timezone and daylight saving time */
#ifdef RT_LIBC_USING_LIGHT_TZ_DST
@@ -340,6 +339,7 @@ RTM_EXPORT(strftime); /* inherent in the toolchain */
*/
rt_weak time_t time(time_t *t)
{
#ifdef RT_USING_RTC
time_t _t;
if (_control_rtc(RT_DEVICE_CTRL_RTC_GET_TIME, &_t) != RT_EOK)
@@ -352,6 +352,10 @@ rt_weak time_t time(time_t *t)
*t = _t;
return _t;
#else
rt_set_errno(EFAULT);
return (time_t)-1;
#endif
}
RTM_EXPORT(time);
@@ -363,10 +367,12 @@ RTM_EXPORT(clock);
int stime(const time_t *t)
{
#ifdef RT_USING_RTC
if ((t != RT_NULL) && (_control_rtc(RT_DEVICE_CTRL_RTC_SET_TIME, (void *)t) == RT_EOK))
{
return 0;
}
#endif /* RT_USING_RTC */
rt_set_errno(EFAULT);
return -1;
@@ -475,6 +481,7 @@ int gettimeofday(struct timeval *tv, struct timezone *tz)
#endif /* RT_LIBC_USING_LIGHT_TZ_DST */
}
#ifdef RT_USING_RTC
if (tv != RT_NULL)
{
tv->tv_sec = 0;
@@ -492,6 +499,7 @@ int gettimeofday(struct timeval *tv, struct timezone *tz)
}
}
}
#endif /* RT_USING_RTC */
rt_set_errno(EINVAL);
return -1;
@@ -505,6 +513,7 @@ int settimeofday(const struct timeval *tv, const struct timezone *tz)
* The tz_dsttime field has never been used under Linux.
* Thus, the following is purely of historic interest.
*/
#ifdef RT_USING_RTC
if (tv != RT_NULL && (long)tv->tv_usec >= 0 && (long)tv->tv_sec >= 0)
{
if (_control_rtc(RT_DEVICE_CTRL_RTC_SET_TIMEVAL, (void *)tv) == RT_EOK)
@@ -519,6 +528,7 @@ int settimeofday(const struct timeval *tv, const struct timezone *tz)
}
}
}
#endif /* RT_USING_RTC */
rt_set_errno(EINVAL);
return -1;
@@ -594,7 +604,9 @@ int clock_getres(clockid_t clockid, struct timespec *res)
{
case CLOCK_REALTIME: // use RTC
case CLOCK_REALTIME_COARSE:
#ifdef RT_USING_RTC
return _control_rtc(RT_DEVICE_CTRL_RTC_GET_TIMERES, res);
#endif /* RT_USING_RTC */
case CLOCK_MONOTONIC: // use cputimer
case CLOCK_MONOTONIC_COARSE:
@@ -625,7 +637,9 @@ int clock_gettime(clockid_t clockid, struct timespec *tp)
{
case CLOCK_REALTIME: // use RTC
case CLOCK_REALTIME_COARSE:
#ifdef RT_USING_RTC
return _control_rtc(RT_DEVICE_CTRL_RTC_GET_TIMESPEC, tp);
#endif /* RT_USING_RTC */
case CLOCK_MONOTONIC: // use boottime
case CLOCK_MONOTONIC_COARSE:
@@ -666,9 +680,11 @@ int clock_nanosleep(clockid_t clockid, int flags, const struct timespec *rqtp, s
switch (clockid)
{
case CLOCK_REALTIME: // use RTC
#ifdef RT_USING_RTC
if (flags & TIMER_ABSTIME)
err = _control_rtc(RT_DEVICE_CTRL_RTC_GET_TIMESPEC, &ts);
break;
#endif /* RT_USING_RTC */
case CLOCK_MONOTONIC: // use boottime
case CLOCK_PROCESS_CPUTIME_ID:
@@ -717,8 +733,10 @@ int clock_settime(clockid_t clockid, const struct timespec *tp)
switch (clockid)
{
#ifdef RT_USING_RTC
case CLOCK_REALTIME:
return _control_rtc(RT_DEVICE_CTRL_RTC_SET_TIMESPEC, (void *)tp);
#endif /* RT_USING_RTC */
case CLOCK_REALTIME_COARSE:
case CLOCK_MONOTONIC:
@@ -783,7 +801,7 @@ RTM_EXPORT(rt_timespec_to_tick);
struct timer_obj
{
struct rt_ktime_hrtimer hrtimer;
void (*sigev_notify_function)(union sigval val);
void (*sigev_notify_func)(union sigval val);
union sigval val;
struct timespec interval; /* Reload value */
struct timespec value; /* Reload value */
@@ -885,7 +903,7 @@ static void rtthread_timer_wrapper(void *timerobj)
}
#ifdef RT_USING_SMART
/* this field is named as tid in musl */
void *ptid = &timer->sigev_notify_function;
void *ptid = &timer->sigev_notify_func;
int tid = *(int *)ptid;
struct lwp_timer_event_param *data = rt_container_of(timer->work, struct lwp_timer_event_param, work);
data->signo = timer->sigev_signo;
@@ -904,9 +922,9 @@ static void rtthread_timer_wrapper(void *timerobj)
if (rt_work_submit(timer->work, 0))
RT_ASSERT(0);
#else
if(timer->sigev_notify_function != RT_NULL)
if(timer->sigev_notify_func != RT_NULL)
{
(timer->sigev_notify_function)(timer->val);
(timer->sigev_notify_func)(timer->val);
}
#endif /* RT_USING_SMART */
}
@@ -994,7 +1012,7 @@ int timer_create(clockid_t clockid, struct sigevent *evp, timer_t *timerid)
timer->work = work;
#endif /* RT_USING_SMART */
timer->sigev_notify_function = evp->sigev_notify_function;
timer->sigev_notify_func = evp->sigev_notify_function;
timer->val = evp->sigev_value;
timer->interval.tv_sec = 0;
timer->interval.tv_nsec = 0;
@@ -1181,11 +1199,13 @@ int timer_settime(timer_t timerid, int flags, const struct itimerspec *value,
switch (timer->clockid)
{
#ifdef RT_USING_RTC
case CLOCK_REALTIME:
case CLOCK_REALTIME_ALARM:
if (flags & TIMER_ABSTIME)
err = _control_rtc(RT_DEVICE_CTRL_RTC_GET_TIMESPEC, &ts);
break;
#endif /* RT_USING_RTC */
case CLOCK_MONOTONIC:
case CLOCK_BOOTTIME:
case CLOCK_BOOTTIME_ALARM:

12
rt-thread/components/libc/compilers/common/cwchar.c
View File

@@ -112,12 +112,12 @@ int wcwidth(wchar_t ucs)
(ucs >= 0xf900 && ucs <= 0xfaff) || /* CJK Compatibility Ideographs */
(ucs >= 0xfe30 && ucs <= 0xfe6f) || /* CJK Compatibility Forms */
(ucs >= 0xff00 && ucs <= 0xff5f) || /* Fullwidth Forms */
(ucs >= 0xffe0 && ucs <= 0xffe6) // ||
//#ifndef _WIN32
// (ucs >= 0x20000 && ucs <= 0x2ffff)
//#else
// 0
//#endif
(ucs >= 0xffe0 && ucs <= 0xffe6) ||
#ifndef _WIN32
(ucs >= 0x20000 && ucs <= 0x2ffff)
#else
0
#endif
));
}

13
rt-thread/components/libc/compilers/common/include/dirent.h
View File

@@ -65,6 +65,19 @@ struct dirent
};
#endif
#ifdef RT_USING_MUSLLIBC
typedef uint64_t ino_t;
#endif
struct libc_dirent {
#ifdef RT_USING_MUSLLIBC
ino_t d_ino;
#endif
off_t d_off;
unsigned short d_reclen;
unsigned char d_type;
char d_name[DIRENT_NAME_MAX];
};
int closedir(DIR *);
DIR *opendir(const char *);
struct dirent *readdir(DIR *);

25
rt-thread/components/libc/compilers/musl/fcntl.h
View File

@@ -22,18 +22,33 @@
#define O_DSYNC 010000
#define O_SYNC 04010000
#define O_RSYNC 04010000
#define O_DIRECTORY 040000
#define O_NOFOLLOW 0100000
#define O_CLOEXEC 02000000
#define O_ASYNC 020000
#define O_DIRECT 0200000
#define O_LARGEFILE 0400000
#define O_NOATIME 01000000
#define O_PATH 010000000
#define O_TMPFILE 020040000
#define O_NDELAY O_NONBLOCK
#ifndef O_LARGEFILE
#define O_LARGEFILE 0400000
#endif
#ifndef O_DIRECT
#define O_DIRECT 0200000
#endif
#ifndef O_TMPFILE
#define O_TMPFILE 020040000
#endif
#ifndef O_NOFOLLOW
#define O_NOFOLLOW 0100000
#endif
#ifndef O_DIRECTORY
#define O_DIRECTORY 040000
#endif
#ifndef O_BINARY
#define O_BINARY 00
#endif

86
rt-thread/components/libc/posix/io/timerfd/timerfd.c
View File

@@ -1,5 +1,5 @@
/*
* Copyright (c) 2006-2023, RT-Thread Development Team
* Copyright (c) 2006-2024 RT-Thread Development Team
*
* SPDX-License-Identifier: Apache-2.0
*
@@ -546,16 +546,100 @@ static int timerfd_do_gettime(int fd, struct itimerspec *cur)
return 0;
}
/**
* @brief Creates a file descriptor for a timer.
*
* The `timerfd_create` function creates a new timer object that generates
* timer expiration notifications via a file descriptor.
*
* @param clockid The clock ID that specifies the clock to be used as the
* timing base for the timer. Common values include:
* - `CLOCK_REALTIME`: A system-wide clock representing
* wall-clock time.
* - `CLOCK_MONOTONIC`: A clock that cannot be set and
* represents monotonic time since some unspecified
* starting point.
* @param flags A bitmask that can include the following flags:
* - `TFD_CLOEXEC`: Close the file descriptor on `execve`.
* - `TFD_NONBLOCK`: Set the file descriptor to non-blocking mode.
*
* @return On success, returns a file descriptor for the timer. On error,
* returns -1 and sets `errno` appropriately.
*
* @note The file descriptor can be used with select, poll, or epoll to wait
* for timer expirations.
*
* @warning The timerfd interface is Linux-specific and may not be available
* on other operating systems.
*
* @see timerfd_settime, timerfd_gettime
*/
int timerfd_create(int clockid, int flags)
{
return timerfd_do_create(clockid, flags);
}
/**
* @brief Sets the time for a timer file descriptor.
*
* The `timerfd_settime` function starts or modifies the timer associated
* with the specified timer file descriptor.
*
* @param fd The file descriptor of the timer, obtained from
* `timerfd_create`.
* @param flags Flags that control the behavior of the timer. Possible
* values include:
* - `0`: Relative time is specified in `new`.
* - `TFD_TIMER_ABSTIME`: Use absolute time instead of
* relative time.
* @param new A pointer to a `itimerspec` structure that specifies the
* new timer settings:
* - `it_value`: The initial expiration time. A zero value
* means the timer is disabled.
* - `it_interval`: The interval for periodic timers. A zero
* value means the timer is not periodic.
* @param old A pointer to a `itimerspec` structure to store the
* previous timer settings. Can be `NULL` if this information
* is not needed.
*
* @return On success, returns 0. On error, returns -1 and sets `errno`
* appropriately.
*
* @note The timer starts counting down immediately after this call if
* `it_value` is non-zero.
*
* @warning If the timer is set to a very short interval, high-frequency
* events may impact system performance.
*
* @see timerfd_create, timerfd_gettime
*/
int timerfd_settime(int fd, int flags, const struct itimerspec *new, struct itimerspec *old)
{
return timerfd_do_settime(fd, flags, new, old);
}
/**
* @brief Retrieves the current value and interval of a timer.
*
* The `timerfd_gettime` function queries the settings of the timer associated
* with the specified timer file descriptor.
*
* @param fd The file descriptor of the timer, obtained from `timerfd_create`.
* @param cur A pointer to a `itimerspec` structure where the current timer
* settings will be stored:
* - `it_value`: The time remaining until the next expiration.
* If zero, the timer is disabled.
* - `it_interval`: The interval for periodic timers. Zero if the
* timer is not periodic.
*
* @return On success, returns 0. On error, returns -1 and sets `errno`
* appropriately.
*
* @note This function does not reset or modify the timer; it only retrieves
* the current settings.
*
* @see timerfd_create, timerfd_settime
*/
int timerfd_gettime(int fd, struct itimerspec *cur)
{
return timerfd_do_gettime(fd, cur);

2
rt-thread/components/libc/posix/libdl/arch/arm.c
View File

@@ -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
*

2
rt-thread/components/libc/posix/libdl/arch/riscv.c
View File

@@ -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
*

2
rt-thread/components/libc/posix/libdl/arch/x86.c
View File

@@ -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
*

11
rt-thread/components/libc/posix/libdl/dlclose.c
View File

@@ -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
*
@@ -13,6 +13,15 @@
#include "dlmodule.h"
/**
* @brief close a dynamically loaded shared library.
*
* @param handle the handle which identifies the shared library to be closed.
* @return int it returns RT_TRUE on success.
*
* @note This function is an API of POSIX standard, which is designed to decrease the reference count (nref) for a dynamically loaded module
* and destroy it if no references remain.
*/
int dlclose(void *handle)
{
struct rt_dlmodule *module;

45
rt-thread/components/libc/posix/libdl/dlelf.c
View File

@@ -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
*
@@ -14,8 +14,32 @@
#define DBG_TAG "DLMD"
#define DBG_LVL DBG_INFO
#include <rtdbg.h> // must after of DEBUG_ENABLE or some other options
#include <rtdbg.h> /* must after of DEBUG_ENABLE or some other options*/
/**
* @brief Load a shared object file into memory.
*
* @param module A pointer to a rt_dlmodule object for holding the module's information.
* @param module_ptr A pointer to the raw memory of the ELF file (shared object) that is being loaded.
* @return rt_err_t On success, it returns RT_EOK. Otherwise, it returns the error code.
*
* @note This function loads a shared object (ELF file) into memory, broken down into steps:
* 1. Initialization and Validation: it begins by validating the module pointer
* and checking if the ELF file has been linked by comparing its magic number (RTMMAG).
* If matched, the module is considered linked.
* 2. Calculating the ELF Image Size: it iterates over the ELF program headers to compute the total size of the ELF image
* by adding the sizes of loadable segments. It also ensures there are no overlaps or invalid addresses in the segments.
* 3. Allocating Memory for the Module: After determining the module size, the function allocates memory (module->mem_space) for the ELF image
* and initializes it to zero. Then, it copies the relevant program segments from the ELF file into this allocated memory.
* 4. Setting the Module Entry Point: it sets the entry point address (module->entry_addr) based on the ELF entry point adjusted by the calculated base address.
* 5. Handling Relocation Sections: It processes each relocation section in the ELF file.
* For each relocation entry, it either resolves the symbol from the module's own symbol table
* or looks up the symbol in the kernel symbol table if it was not found locally.
* 6. Building the Module's Symbol Table: it looks for the .dynsym section to extract global function symbols.
* It creates a symbol table (module->symtab) and populates it with the function names and addresses for all global symbols of type STT_FUNC.
* 7. Extracting Additional Parameters: It extracts additional parameters, such as thread priority (dlmodule_thread_priority) and stack size (dlmodule_thread_stacksize),
* from the symbol table and assigns them to the module if valid.
*/
rt_err_t dlmodule_load_shared_object(struct rt_dlmodule* module, void *module_ptr)
{
rt_bool_t linked = RT_FALSE;
@@ -273,6 +297,23 @@ rt_err_t dlmodule_load_shared_object(struct rt_dlmodule* module, void *module_pt
return RT_EOK;
}
/**
* @brief Load a relocatable file into memory.
*
* @param module A pointer to a rt_dlmodule object for holding the module's information.
* @param module_ptr A pointer to the raw memory of the ELF file (relocatable file) that is being loaded.
* @return rt_err_t On success, it returns RT_EOK. Otherwise, it returns the error code.
*
* @note This function loads a relocatable file (ELF file) into memory, broken down step by step:
* 1. Calculate Module Size: iterates over the ELF sections (text, data, rodata, and bss) to calculate the total size of the module
* and identifies the start address for each section.
* 2. Allocate Memory: It allocates memory for the module based on the calculated size. If allocation fails, an error is returned.
* 3. Load Sections into Memory: The function loads the text, rodata, data, and BSS sections into the allocated memory.
* The BSS section is zeroed out, while the others are copied from the ELF image.
* 4. Set Entry Point: The entry point of the module is set by calculating the address relative to the start of the allocated memory.
* 5. Handle Relocation: It processes the relocation entries, resolving symbol addresses and relocating them as needed.
* This includes functions, sections (rodata, bss, data), and external symbols from the kernel symbol table.
*/
rt_err_t dlmodule_load_relocated_object(struct rt_dlmodule* module, void *module_ptr)
{
rt_ubase_t index, rodata_addr = 0, bss_addr = 0, data_addr = 0;

2
rt-thread/components/libc/posix/libdl/dlelf.h
View File

@@ -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
*

9
rt-thread/components/libc/posix/libdl/dlerror.c
View File

@@ -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
*
@@ -11,6 +11,13 @@
#include <rtthread.h>
#include <rtm.h>
/**
* @brief retrieve a string describing the last error that occurred from a dynamic linking operation.
*
* @return const char* a string containing an error message describing the last error.
*
* @note This function is an API of POSIX standard, which is still remaining TBD.
*/
const char *dlerror(void)
{
return "TODO";

2
rt-thread/components/libc/posix/libdl/dlfcn.h
View File

@@ -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
*

62
rt-thread/components/libc/posix/libdl/dlmodule.c
View File

@@ -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
*
@@ -24,7 +24,7 @@
#define DBG_TAG "DLMD"
#define DBG_LVL DBG_INFO
#include <rtdbg.h> // must after of DEBUG_ENABLE or some other options
#include <rtdbg.h> /* must after of DEBUG_ENABLE or some other options*/
static struct rt_module_symtab *_rt_module_symtab_begin = RT_NULL;
static struct rt_module_symtab *_rt_module_symtab_end = RT_NULL;
@@ -176,6 +176,11 @@ __exit:
return ;
}
/**
* @brief create a dynamic module object and initialize it.
*
* @return struct rt_dlmodule* If module create successfully, return the pointer to its rt_dlmodule structure.
*/
struct rt_dlmodule *dlmodule_create(void)
{
struct rt_dlmodule *module = RT_NULL;
@@ -233,6 +238,12 @@ void dlmodule_destroy_subthread(struct rt_dlmodule *module, rt_thread_t thread)
#endif
}
/**
* @brief destroy dynamic module and cleanup all kernel objects inside it.
*
* @param module Pointer to the module to be destroyed.
* @return rt_err_t On success, it returns RT_EOK. Otherwise, it returns the error code.
*/
rt_err_t dlmodule_destroy(struct rt_dlmodule* module)
{
int i;
@@ -255,7 +266,7 @@ rt_err_t dlmodule_destroy(struct rt_dlmodule* module)
rt_exit_critical();
}
// list_object(&(module->object_list));
/* list_object(&(module->object_list));*/
/* cleanup for all kernel objects inside module*/
{
@@ -393,6 +404,11 @@ rt_err_t dlmodule_destroy(struct rt_dlmodule* module)
return RT_EOK;
}
/**
* @brief retrieve the dynamically loaded module that the current thread belongs to.
*
* @return struct rt_dlmodule* On success, it returns a pointer to the module. otherwise, it returns RT_NULL.
*/
struct rt_dlmodule *dlmodule_self(void)
{
rt_thread_t tid;
@@ -415,6 +431,20 @@ struct rt_dlmodule *rt_module_self(void)
return dlmodule_self();
}
/**
* @brief load an ELF module to memory.
*
* @param filename the path to the module to load.
* @return struct rt_dlmodule* On success, it returns a pointer to the module object. otherwise, RT_NULL is returned.
*
* @note the function is used to load an ELF (Executable and Linkable Format) module from a file, validate it,
* and initialize it as a dynamically loaded module. what it implements are as follows:
* 1. Load and Validate ELF: It loads an ELF file, checks its validity, and identifies it as either a relocatable or shared object.
* 2. Memory Allocation and Cleanup: Uses rt_malloc and rt_free to allocate and free memory for module data.
* Error handling ensures all resources are released if an error occurs.
* 3. Symbol Resolution and Initialization: Sets up init function and cleanup function, and calls the module_init function if it is present.
* 4. Cache Management: Optionally (when RT_USING_CACHE defined) flushes data and invalidates instruction caches to ensure the module is correctly loaded into memory.
*/
struct rt_dlmodule* dlmodule_load(const char* filename)
{
#ifdef RT_USING_POSIX_FS
@@ -525,6 +555,14 @@ __exit:
return RT_NULL;
}
/**
* @brief load a dynamic module, and create a thread to excute the module main function.
*
* @param pgname path of the module to be loaded.
* @param cmd the command string (with commandline options) for startup module.
* @param cmd_size the command's length.
* @return struct rt_dlmodule* On success, it returns a pointer to the module object. otherwise, RT_NULL is returned.
*/
struct rt_dlmodule* dlmodule_exec(const char* pgname, const char* cmd, int cmd_size)
{
struct rt_dlmodule *module = RT_NULL;
@@ -742,6 +780,17 @@ struct rt_dlmodule* dlmodule_exec_custom(const char* pgname, const char* cmd, in
}
#endif
/**
* @brief exit a dynamically loaded module.
*
* @param ret_code the return code for module exit.
*
* @note this function is responsible for gracefully exiting a dynamically loaded module, releasing resources associated with the module,
* and handling cleanup operations. what it implements are as follows:
* 1. Thread and Resource Cleanup: The function safely exits a module by deleting its main thread and freeing resources associated with it.
* 2. Status Management: Checks and updates the module's state, setting a return code and calling _dlmodule_exit() to transition to a closing state.
* 3. Critical Sections: Critical sections ensure that the exit process is atomic and free from race conditions.
*/
void dlmodule_exit(int ret_code)
{
rt_thread_t thread;
@@ -784,6 +833,13 @@ void dlmodule_exit(int ret_code)
rt_exit_critical();
}
/**
* @brief search for a symbol by its name in the kernel symbol table.
*
* @param sym_str the symbol name string.
* @return rt_uint32_t On success, it returns the address of the symbol.
* Otherwise, it returns 0 (indicating the symbol was not found).
*/
rt_uint32_t dlmodule_symbol_find(const char *sym_str)
{
/* find in kernel symbol table */

2
rt-thread/components/libc/posix/libdl/dlmodule.h
View File

@@ -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
*

15
rt-thread/components/libc/posix/libdl/dlopen.c
View File

@@ -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
*
@@ -16,6 +16,19 @@
#define MODULE_ROOT_DIR "/modules"
/**
* @brief dynamically load a shared library at runtime.
*
* @param filename the path to the shared library to load, which shouldn't be set to NULL.
* @param flags options for loading the shared library.
* @return void* on success, it returns a handle (a pointer) to the opened shared library, otherwise it returns NULL.
*
* @note This function is an API of POSIX standard, which is used for dynamically loading shared libraries at runtime.
* the function first tries to check if the module is already loaded, by finding module in module list.
* If module is found in memory (RT_NULL check fails), the reference count (nref) is incremented.
* Otherwise, dlmodule_load() will be called to load the module into memory.
* A handle (a pointer to the module) is returned at last, which can be used with other functions like dlsym().
*/
void* dlopen(const char *filename, int flags)
{
struct rt_dlmodule *module;

13
rt-thread/components/libc/posix/libdl/dlsym.c
View File

@@ -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
*
@@ -13,6 +13,17 @@
#include "dlmodule.h"
/**
* @brief look up the address of a symbol in a dynamically loaded shared library.
*
* @param handle the handle returned by dlopen() when the library was previously loaded.
* @param symbol A string containing the name of the symbol to locate.
* @return void* On success, it returns a pointer to the symbol. Otherwise, it returns RT_NULL.
*
* @note This function is an API of POSIX standard, which is commonly used in conjunction with dlopen() to retrieve function pointers from shared libraries.
* the input symbol name, which can be the name of a function or variable, is compared with each symbol
* in the module symbol table. if the same symbol is found, return its address.
*/
void* dlsym(void *handle, const char* symbol)
{
int i;

2
rt-thread/components/libc/posix/libdl/dlsyms.c
View File

@@ -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
*

539
rt-thread/components/libc/posix/pthreads/pthread.c
View File

@@ -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;

115
rt-thread/components/libc/posix/pthreads/pthread_barrier.c
View File

@@ -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
*
@@ -45,12 +45,40 @@ int pthread_barrierattr_setpshared(pthread_barrierattr_t *attr, int pshared)
if (!attr)
return EINVAL;
if (pshared == PTHREAD_PROCESS_PRIVATE)
attr = PTHREAD_PROCESS_PRIVATE;
{
*attr = PTHREAD_PROCESS_PRIVATE;
return 0;
}
return EINVAL;
}
RTM_EXPORT(pthread_barrierattr_setpshared);
/**
* @brief Destroys a barrier object.
*
* The `pthread_barrier_destroy` function releases any resources associated
* with the specified barrier object. After a barrier has been destroyed,
* it cannot be used again unless it is reinitialized using `pthread_barrier_init`.
*
* @param[in] barrier
* A pointer to an initialized `pthread_barrier_t` object to be destroyed.
*
* @return
* - `0` on success.
* - `EINVAL` if the `barrier` is invalid or uninitialized.
* - `EBUSY` if there are threads currently blocked on the barrier.
*
* @note
* - Ensure that no threads are blocked on the barrier before calling this function.
* - Attempting to destroy a barrier that is still in use results in undefined behavior.
*
* @warning
* Destroying a barrier without ensuring it is no longer in use can lead to
* resource leaks or undefined program behavior.
*
* @see pthread_barrier_init, pthread_barrier_wait
*/
int pthread_barrier_destroy(pthread_barrier_t *barrier)
{
rt_err_t result;
@@ -58,12 +86,68 @@ int pthread_barrier_destroy(pthread_barrier_t *barrier)
if (!barrier)
return EINVAL;
/* Lock the internal mutex to safely check the barrier's state*/
result = pthread_mutex_lock(&(barrier->mutex));
if (result != 0)
return result;
/* Check if any threads are currently waiting on the barrier*/
if (barrier->count != 0)
{
pthread_mutex_unlock(&(barrier->mutex));
return EBUSY; /* Threads are still waiting*/
}
/* Free resources associated with the barrier*/
result = pthread_mutex_unlock(&(barrier->mutex));
if (result != 0)
{
return result; /* Return mutex unlock error*/
}
result = pthread_mutex_destroy(&(barrier->mutex));
if (result != 0)
{
return result; /* Return mutex destroy error*/
}
result = pthread_cond_destroy(&(barrier->cond));
return result;
}
RTM_EXPORT(pthread_barrier_destroy);
/**
* @brief Initializes a barrier for synchronizing threads.
*
* The `pthread_barrier_init` function initializes a barrier object
* that allows a specified number of threads to synchronize at a barrier point.
* Each thread waits at the barrier until the required number of threads have called
* `pthread_barrier_wait`.
*
* @param[out] barrier
* A pointer to the `pthread_barrier_t` object to be initialized.
* This object must not already be initialized.
*
* @param[in] attr
* A pointer to a `pthread_barrierattr_t` object that specifies
* attributes for the barrier (e.g., process-shared or process-private).
* If NULL, the default attributes are used.
*
* @param[in] count
* The number of threads that must call `pthread_barrier_wait`
* before any of them successfully return from the barrier.
*
* @return
* - `0` on success.
* - `EINVAL` if the `count` is zero or `barrier` is invalid.
*
* @note The barrier must be destroyed using `pthread_barrier_destroy`
* when it is no longer needed.
*
* @warning If `count` is set to zero, the behavior is undefined.
*
* @see pthread_barrier_wait, pthread_barrier_destroy
*/
int pthread_barrier_init(pthread_barrier_t *barrier,
const pthread_barrierattr_t *attr,
unsigned count)
@@ -83,6 +167,33 @@ int pthread_barrier_init(pthread_barrier_t *barrier,
}
RTM_EXPORT(pthread_barrier_init);
/**
* @brief Synchronizes threads at a barrier.
*
* The `pthread_barrier_wait` function blocks the calling thread at the specified
* barrier until the required number of threads have reached the barrier. Once
* the required number of threads have called this function, all threads are
* unblocked and can proceed.
*
* @param[in] barrier
* A pointer to an initialized `pthread_barrier_t` object representing the barrier
* at which threads will synchronize.
*
* @return
* - `0` for all threads except one.
* - `EINVAL` - The `barrier` is invalid or uninitialized.
*
* @note
* - All threads participating in the barrier must call `pthread_barrier_wait`
* before any of them are released.
*
* @warning
* Ensure that the number of threads specified during the barrier's initialization
* matches the number of threads calling this function, otherwise the program
* may hang indefinitely.
*
* @see pthread_barrier_init, pthread_barrier_destroy
*/
int pthread_barrier_wait(pthread_barrier_t *barrier)
{
rt_err_t result;

185
rt-thread/components/libc/posix/pthreads/pthread_cond.c
View File

@@ -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)

296
rt-thread/components/libc/posix/pthreads/pthread_mutex.c
View File

@@ -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
*
@@ -16,6 +16,28 @@
const pthread_mutexattr_t pthread_default_mutexattr = PTHREAD_PROCESS_PRIVATE;
/**
* @brief Initializes a mutex attributes object.
*
* This function initializes a mutex attributes object pointed to by `attr` with
* default attribute values. Once initialized, the attributes object can be used
* to customize the behavior of mutexes created using it.
*
* @param[out] attr Pointer to the mutex attributes object to be initialized.
*
* @return
* - 0 on success.
* - Non-zero error code on failure.
*
* @note
* After initialization, the mutex attributes object must be destroyed with
* `pthread_mutexattr_destroy()` when it is no longer needed.
*
* @warning
* Using an uninitialized mutex attributes object may result in undefined behavior.
*
* @see pthread_mutexattr_destroy, pthread_mutex_init
*/
int pthread_mutexattr_init(pthread_mutexattr_t *attr)
{
if (attr)
@@ -29,6 +51,29 @@ int pthread_mutexattr_init(pthread_mutexattr_t *attr)
}
RTM_EXPORT(pthread_mutexattr_init);
/**
* @brief Destroys a mutex attributes object.
*
* This function releases any resources associated with the mutex attributes object
* pointed to by `attr`. After the attributes object is destroyed, it should not
* be used unless it is re-initialized with `pthread_mutexattr_init()`.
*
* @param[in,out] attr Pointer to the mutex attributes object to be destroyed.
*
* @return
* - 0 on success.
* - Non-zero error code on failure, including:
* - `EINVAL`: The attributes object is invalid or uninitialized.
*
* @note
* Destroying an uninitialized or already destroyed attributes object results in undefined behavior.
*
* @warning
* Ensure that no mutexes are being initialized or created using this attributes object
* at the time of its destruction.
*
* @see pthread_mutexattr_init, pthread_mutex_init
*/
int pthread_mutexattr_destroy(pthread_mutexattr_t *attr)
{
if (attr)
@@ -42,6 +87,30 @@ int pthread_mutexattr_destroy(pthread_mutexattr_t *attr)
}
RTM_EXPORT(pthread_mutexattr_destroy);
/**
* @brief Retrieves the type attribute of a mutex attributes object.
*
* This function retrieves the mutex type attribute from the attributes object
* pointed to by `attr` and stores it in the integer pointed to by `type`.
*
* @param[in] attr Pointer to the mutex attributes object.
* @param[out] type Pointer to an integer where the mutex type will be stored.
* Possible values include:
* - `PTHREAD_MUTEX_NORMAL`: Default mutex type.
* - `PTHREAD_MUTEX_ERRORCHECK`: Mutex with error-checking.
* - `PTHREAD_MUTEX_RECURSIVE`: Recursive mutex.
*
* @return
* - 0 on success.
* - Non-zero error code on failure, including:
* - `EINVAL`: The attributes object or the `type` pointer is invalid.
*
* @note
* Use this function to check the type of a mutex attributes object that has
* already been initialized or configured.
*
* @see pthread_mutexattr_settype, pthread_mutexattr_init
*/
int pthread_mutexattr_gettype(const pthread_mutexattr_t *attr, int *type)
{
if (attr && type)
@@ -60,6 +129,41 @@ int pthread_mutexattr_gettype(const pthread_mutexattr_t *attr, int *type)
}
RTM_EXPORT(pthread_mutexattr_gettype);
/**
* @brief Sets the type attribute of a mutex attributes object.
*
* This function sets the type of the mutex to be initialized using the
* attributes object pointed to by `attr`. The `type` can be one of the
* following values:
* - `PTHREAD_MUTEX_NORMAL`: Default mutex type. The mutex does not allow
* a thread to unlock it if it was not locked by that thread (this results
* in undefined behavior).
* - `PTHREAD_MUTEX_ERRORCHECK`: Error-checking mutex type. A thread trying to
* lock a mutex it already holds will return an error.
* - `PTHREAD_MUTEX_RECURSIVE`: Recursive mutex type. The same thread can lock
* the mutex multiple times without causing a deadlock, but it must unlock it
* the same number of times.
*
* @param[in,out] attr Pointer to the mutex attributes object.
* @param[in] type The type to set for the mutex. One of the following:
* - `PTHREAD_MUTEX_NORMAL`
* - `PTHREAD_MUTEX_ERRORCHECK`
* - `PTHREAD_MUTEX_RECURSIVE`
*
* @return
* - 0 on success.
* - Non-zero error code on failure, including:
* - `EINVAL`: The specified type is invalid.
*
* @note
* The type must be set before the mutex attributes object is used to
* initialize a mutex with `pthread_mutex_init()`.
*
* @warning
* Attempting to set an invalid mutex type will result in an error.
*
* @see pthread_mutexattr_gettype, pthread_mutexattr_init, pthread_mutex_init
*/
int pthread_mutexattr_settype(pthread_mutexattr_t *attr, int type)
{
if (attr && type >= PTHREAD_MUTEX_NORMAL && type <= PTHREAD_MUTEX_ERRORCHECK)
@@ -73,6 +177,37 @@ int pthread_mutexattr_settype(pthread_mutexattr_t *attr, int type)
}
RTM_EXPORT(pthread_mutexattr_settype);
/**
* @brief Sets the shared attribute of a mutex attributes object.
*
* This function sets the `pshared` attribute of the mutex attributes object
* pointed to by `attr`. The `pshared` attribute determines whether the mutex
* is shared between threads of the same process or can be shared between
* threads of different processes.
*
* @param[in,out] attr Pointer to the mutex attributes object.
* @param[in] pshared The sharing behavior of the mutex. This can be one of the following:
* - `PTHREAD_PROCESS_PRIVATE`: The mutex is only shared between threads
* of the same process (this is the default behavior).
* - `PTHREAD_PROCESS_SHARED`: The mutex can be shared between threads
* of different processes (requires the mutex to be allocated in
* shared memory).
*
* @return
* - 0 on success.
* - Non-zero error code on failure, including:
* - `EINVAL`: Invalid `pshared` value or invalid attributes object.
*
* @note
* The `pshared` attribute must be set before the mutex attributes object is
* used to initialize a mutex with `pthread_mutex_init()`. For shared mutexes
* (`PTHREAD_PROCESS_SHARED`), the mutex object must be allocated in shared memory.
*
* @warning
* Attempting to set an invalid `pshared` value will result in an error.
*
* @see pthread_mutexattr_getpshared, pthread_mutexattr_init, pthread_mutex_init
*/
int pthread_mutexattr_setpshared(pthread_mutexattr_t *attr, int pshared)
{
if (!attr)
@@ -93,6 +228,35 @@ int pthread_mutexattr_setpshared(pthread_mutexattr_t *attr, int pshared)
}
RTM_EXPORT(pthread_mutexattr_setpshared);
/**
* @brief Retrieves the shared attribute of a mutex attributes object.
*
* This function retrieves the `pshared` attribute from the mutex attributes
* object pointed to by `attr` and stores it in the integer pointed to by `pshared`.
* The `pshared` attribute indicates whether the mutex can be shared between threads
* of different processes or only within the same process.
*
* @param[in] attr Pointer to the mutex attributes object.
* @param[out] pshared Pointer to an integer where the shared attribute will be stored.
* Possible values are:
* - `PTHREAD_PROCESS_PRIVATE`: Mutex is shared only within the same process.
* - `PTHREAD_PROCESS_SHARED`: Mutex can be shared between threads of different processes.
*
* @return
* - 0 on success.
* - Non-zero error code on failure, including:
* - `EINVAL`: Invalid attributes object or the `pshared` pointer is NULL.
*
* @note
* Use this function to check the shared attribute of an already initialized
* mutex attributes object.
*
* @warning
* Attempting to get the `pshared` attribute of an uninitialized or invalid
* attributes object will result in an error.
*
* @see pthread_mutexattr_setpshared, pthread_mutexattr_init, pthread_mutex_init
*/
int pthread_mutexattr_getpshared(pthread_mutexattr_t *attr, int *pshared)
{
if (!attr || !pshared)
@@ -104,6 +268,31 @@ int pthread_mutexattr_getpshared(pthread_mutexattr_t *attr, int *pshared)
}
RTM_EXPORT(pthread_mutexattr_getpshared);
/**
* @brief Initializes a mutex with optional attributes.
*
* This function initializes a mutex object pointed to by `mutex`. The mutex
* can optionally be initialized with attributes specified by `attr`. If
* `attr` is `NULL`, default attributes are used.
*
* @param[in,out] mutex Pointer to the mutex to be initialized.
* @param[in] attr Pointer to the mutex attributes object. Pass `NULL` to use
* default attributes.
*
* @return
* - 0 on success.
* - Non-zero error code on failure, including:
* - `EINVAL`: Invalid parameters or result.
*
* @note
* The mutex object must be destroyed using `pthread_mutex_destroy()` after it
* is no longer needed to free associated resources.
*
* @warning
* A mutex should not be re-initialized while it is already in use.
*
* @see pthread_mutex_destroy, pthread_mutex_lock, pthread_mutex_unlock
*/
int pthread_mutex_init(pthread_mutex_t *mutex, const pthread_mutexattr_t *attr)
{
rt_err_t result;
@@ -133,6 +322,31 @@ int pthread_mutex_init(pthread_mutex_t *mutex, const pthread_mutexattr_t *attr)
}
RTM_EXPORT(pthread_mutex_init);
/**
* @brief Destroys a mutex object.
*
* This function releases any resources associated with the mutex object
* pointed to by `mutex`. After the mutex has been destroyed, it cannot
* be used unless it is re-initialized with `pthread_mutex_init()`.
*
* @param[in,out] mutex Pointer to the mutex to be destroyed.
*
* @return
* - 0 on success.
* - Non-zero error code on failure, including:
* - `EBUSY`: The mutex is currently locked or being used by another thread.
* - `EINVAL`: The mutex is invalid or has not been initialized.
*
* @note
* Before calling this function, ensure that the mutex is not locked or in use
* by any thread. Destroying a locked mutex results in undefined behavior.
*
* @warning
* Attempting to destroy a mutex that is still in use can cause resource leaks
* or undefined behavior.
*
* @see pthread_mutex_init, pthread_mutex_lock, pthread_mutex_unlock
*/
int pthread_mutex_destroy(pthread_mutex_t *mutex)
{
if (!mutex || mutex->attr == -1)
@@ -149,6 +363,34 @@ int pthread_mutex_destroy(pthread_mutex_t *mutex)
}
RTM_EXPORT(pthread_mutex_destroy);
/**
* @brief Locks a mutex.
*
* This function locks the mutex object pointed to by `mutex`. If the mutex is
* already locked by another thread, the calling thread will block until the
* mutex becomes available.
*
* @param[in,out] mutex Pointer to the mutex to be locked.
*
* @return
* - 0 on success.
* - Non-zero error code on failure, including:
* - `EDEADLK`: A deadlock condition was detected (e.g., the current thread
* already holds the mutex in a recursive locking scenario).
* - `EINVAL`: The mutex is invalid or uninitialized.
*
* @note
* If the mutex is initialized with the `PTHREAD_MUTEX_RECURSIVE` attribute,
* the same thread can lock the mutex multiple times without causing a deadlock.
* However, the mutex must be unlocked an equal number of times before it
* becomes available to other threads.
*
* @warning
* Attempting to lock an uninitialized or already destroyed mutex results in
* undefined behavior.
*
* @see pthread_mutex_unlock, pthread_mutex_trylock, pthread_mutex_init
*/
int pthread_mutex_lock(pthread_mutex_t *mutex)
{
int mtype;
@@ -182,6 +424,33 @@ int pthread_mutex_lock(pthread_mutex_t *mutex)
}
RTM_EXPORT(pthread_mutex_lock);
/**
* @brief Unlocks a mutex.
*
* This function unlocks the mutex object pointed to by `mutex`. If other threads
* are blocked waiting for the mutex, one of them will acquire the lock once it is
* released. The calling thread must hold the lock on the mutex before calling
* this function.
*
* @param[in,out] mutex Pointer to the mutex to be unlocked.
*
* @return
* - 0 on success.
* - Non-zero error code on failure, including:
* - `EPERM`: The current thread does not hold the lock on the mutex.
* - `EINVAL`: The mutex is invalid or uninitialized.
*
* @note
* If the mutex was initialized with the `PTHREAD_MUTEX_RECURSIVE` attribute,
* the mutex will only be unlocked after the calling thread unlocks it as many
* times as it was locked.
*
* @warning
* Attempting to unlock an uninitialized, destroyed, or unlocked mutex results
* in undefined behavior.
*
* @see pthread_mutex_lock, pthread_mutex_trylock, pthread_mutex_init
*/
int pthread_mutex_unlock(pthread_mutex_t *mutex)
{
rt_err_t result;
@@ -216,6 +485,31 @@ int pthread_mutex_unlock(pthread_mutex_t *mutex)
}
RTM_EXPORT(pthread_mutex_unlock);
/**
* @brief Attempts to lock a mutex without blocking.
*
* This function attempts to lock the mutex object pointed to by `mutex`. If the mutex
* is already locked by another thread, the function returns immediately with an error
* code instead of blocking.
*
* @param[in,out] mutex Pointer to the mutex to be locked.
*
* @return
* - 0 on success (the mutex was successfully locked).
* - Non-zero error code on failure, including:
* - `EBUSY`: The mutex is already locked by another thread.
* - `EINVAL`: The mutex is invalid or uninitialized.
*
* @note
* This function is useful for implementing non-blocking mutex acquisition. If the mutex
* was initialized with the `PTHREAD_MUTEX_RECURSIVE` attribute, the calling thread can
* lock it multiple times, but must unlock it the same number of times.
*
* @warning
* Attempting to trylock an uninitialized or destroyed mutex results in undefined behavior.
*
* @see pthread_mutex_lock, pthread_mutex_unlock, pthread_mutex_init
*/
int pthread_mutex_trylock(pthread_mutex_t *mutex)
{
rt_err_t result;

224
rt-thread/components/libc/posix/pthreads/pthread_rwlock.c
View File

@@ -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;

112
rt-thread/components/libc/posix/pthreads/pthread_tls.c
View File

@@ -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;
@@ -54,7 +110,7 @@ int pthread_setspecific(pthread_key_t key, const void *value)
/* check tls area */
if (ptd->tls == NULL)
{
ptd->tls = (void**)rt_malloc(sizeof(void*) * PTHREAD_KEY_MAX);
ptd->tls = (void**)rt_calloc(PTHREAD_KEY_MAX, sizeof(void*));
}
if ((key < PTHREAD_KEY_MAX) && _thread_keys[key].is_used)
@@ -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)