Chapter 2. API Reference
Note: If calling a standard libc or C++ sleep function, such as usleep defined in unistd.h, then the task will
only block and yield the CPU if the sleep time is longer than one FreeRTOS tick period. If the time is shorter, the
thread will busy-wait instead of yielding to another RTOS task.
By default all POSIX Threads have the same RTOS priority, but it is possible to change this by calling a custom API.
Standard features
The following standard APIs are implemented in ESP-IDF.
Refer to standard POSIX Threads documentation, or pthread.h, for details about the standard arguments and be-
haviour of each function. Differences or limitations compared to the standard APIs are noted below.
Thread APIs
• pthread_create() - The attr argument is supported for setting stack size and detach state only. Other
attribute fields are ignored. - Unlike FreeRTOS task functions, the start_routine function is allowed to
return. A “detached”type thread is automatically deleted if the function returns. The default “joinable”
type thread will be suspended until pthread_join() is called on it.
• pthread_join()
• pthread_detach()
• pthread_exit()
• sched_yield()
• pthread_self() - An assert will fail if this function is called from a FreeRTOS task which is not a pthread.
• pthread_equal()
Thread Attributes
• pthread_attr_init()
• pthread_attr_destroy() - This function doesn’t need to free any resources and instead resets the
attr structure to defaults (implementation is same as pthread_attr_init()).
• pthread_attr_getstacksize() / pthread_attr_setstacksize()
• pthread_attr_getdetachstate() / pthread_attr_setdetachstate()
Once
• pthread_once()
Static initializer constant PTHREAD_ONCE_INIT is supported.
Note: This function can be called from tasks created using either pthread or FreeRTOS APIs
Mutexes POSIX Mutexes are implemented as FreeRTOS Mutex Semaphores (normal type for “fast”or “error
check”mutexes, and Recursive type for“recursive”mutexes). This means that they have the same priority inheritance
behaviour as mutexes created with xSemaphoreCreateMutex().
• pthread_mutex_init()
• pthread_mutex_destroy()
• pthread_mutex_lock()
• pthread_mutex_timedlock()
• pthread_mutex_trylock()
• pthread_mutex_unlock()
• pthread_mutexattr_init()
• pthread_mutexattr_destroy()
Espressif Systems 831
Submit Document Feedback
Release v4.4