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:

main()
{
    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");
}

void * my_thread1(void * p)
{
      printf("In my_thread1\n");
      pthread_t t2;
      pthread_create(&t2, NULL, my_thread2);
}

main()
{

     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

Functions

esp_pthread_cfg_t esp_pthread_get_default_config()

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.

Macros

PTHREAD_STACK_MIN