ESP-pthread¶
Overview¶
This module offers Espressif specific extensions to the pthread library that can be used to influence the behaviour of pthreads. Currently the following configuration can be tuned:
Stack size of the pthreads
Priority of the created pthreads
Inheriting this configuration across threads
Thread name
Core affinity / core pinning.
Example to tune the stack size of the pthread:
void * thread_func(void * p)
{
printf("In thread_func\n");
return NULL;
}
void app_main(void)
{
pthread_t t1;
esp_pthread_cfg_t cfg = esp_create_default_pthread_config();
cfg.stack_size = (4 * 1024);
esp_pthread_set_cfg(&cfg);
pthread_create(&t1, NULL, thread_func);
}
The API can also be used for inheriting the settings across threads. For example:
void * my_thread2(void * p)
{
/* This thread will inherit the stack size of 4K */
printf("In my_thread2\n");
return NULL;
}
void * my_thread1(void * p)
{
printf("In my_thread1\n");
pthread_t t2;
pthread_create(&t2, NULL, my_thread2);
return NULL;
}
void app_main(void)
{
pthread_t t1;
esp_pthread_cfg_t cfg = esp_create_default_pthread_config();
cfg.stack_size = (4 * 1024);
cfg.inherit_cfg = true;
esp_pthread_set_cfg(&cfg);
pthread_create(&t1, NULL, my_thread1);
}
API Reference¶
Header File¶
Functions¶
-
esp_pthread_cfg_t
esp_pthread_get_default_config
(void)¶ Creates a default pthread configuration based on the values set via menuconfig.
- Return
A default configuration structure.
-
esp_err_t
esp_pthread_set_cfg
(const esp_pthread_cfg_t *cfg)¶ Configure parameters for creating pthread.
This API allows you to configure how the subsequent pthread_create() call will behave. This call can be used to setup configuration parameters like stack size, priority, configuration inheritance etc.
If the ‘inherit’ flag in the configuration structure is enabled, then the same configuration is also inherited in the thread subtree.
- Note
Passing non-NULL attributes to pthread_create() will override the stack_size parameter set using this API
- Return
ESP_OK if configuration was successfully set
ESP_ERR_NO_MEM if out of memory
ESP_ERR_INVALID_ARG if stack_size is less than PTHREAD_STACK_MIN
- Parameters
cfg
: The pthread config parameters
-
esp_err_t
esp_pthread_get_cfg
(esp_pthread_cfg_t *p)¶ Get current pthread creation configuration.
This will retrieve the current configuration that will be used for creating threads.
- Return
ESP_OK if the configuration was available
ESP_ERR_NOT_FOUND if a configuration wasn’t previously set
- Parameters
p
: Pointer to the pthread config structure that will be updated with the currently configured parameters
Structures¶
-
struct
esp_pthread_cfg_t
¶ pthread configuration structure that influences pthread creation
Public Members
-
size_t
stack_size
¶ The stack size of the pthread.
-
size_t
prio
¶ The thread’s priority.
-
bool
inherit_cfg
¶ Inherit this configuration further.
-
const char *
thread_name
¶ The thread name.
-
int
pin_to_core
¶ The core id to pin the thread to. Has the same value range as xCoreId argument of xTaskCreatePinnedToCore.
-
size_t