Other

Miscellaneous helper macros. More...

Macros
#define	EIF_TASK_LAUNCH(m_ret, m_handle, m_alias, m_worker)
	Spawns a system task using standardized, auto-resolved configuration macros. More...

Detailed Description

This group serves as a collection point for utility macros that currently do not belong to any specific category. It includes tools that are either unique in their purpose or haven't yet reached a sufficient "critical mass" to justify the creation of a dedicated group.

Macro Definition Documentation

EIF_TASK_LAUNCH

#define EIF_TASK_LAUNCH	(		m_ret,
			m_handle,
			m_alias,
			m_worker
	)

Value:

do { \
    /* @deviation [Rule 20.10] The '##' token pasting operator is utilized to
     * enforce compile-time synchronization between task aliases and their
     * respective system parameters (NAME, SIZE, PRIORITY). This compile-time
     * binding enforces architecture-level mutual exclusion and prevents runtime
     * mismatch risks. The macro expansion is strictly deterministic and
     * guaranteed to resolve only into valid, well-defined C identifiers.
     */ \
    (m_ret) = eif_task_common_spawn( \
        &(m_handle), \
        (m_worker), \
        TASK_##m_alias##_NAME, \
        TASK_##m_alias##_SIZE, \
        TASK_##m_alias##_PRIORITY \
    ); \
} while (false)

This macro simplifies task creation by enforcing a unified naming convention for task parameters. By providing a base alias (m_alias), the macro automatically constructs the necessary configuration definitions (Name, Stack Size, Priority) using the ## token pasting operator.

For this macro to compile, you must define the corresponding parameters before calling it. For an alias X, the following definitions must exist:

• TASK_X_NAME (String literal, task name in the scheduler)
• TASK_X_SIZE (Integer, stack size in words (4 byte))
• TASK_X_PRIORITY (Integer, FreeRTOS priority)

Warning

The m_handle argument must point to a persistent variable (typically a module-scoped static) to maintain double-spawn protection. Once the task finishes execution or triggers a delete, the underlying task handle variable must be set back to NULL to allow future respawns.

Parameters

[out]	m_ret	Status variable (esp_err_t) to store the creation result.
[in,out]	m_handle	Variable of type TaskHandle_t to store the spawned task handle.
[in]	m_alias	The base identifier alias (e.g., WIFI, SENSOR, MQTT).
[in]	m_worker	The function pointer to the task entry point (worker function).

Example of use:

#include <esp_log.h>
#include <freertos/FreeRTOS.h>
#include <freertos/task.h>
#include <esp_iot_framework_core_ext.h>
#include <esp_iot_framework_core_macros.h>
 
// Definitions needed for the 'MQTT' alias
#define TASK_MQTT_NAME     "mqtt_service"
#define TASK_MQTT_SIZE     4096
#define TASK_MQTT_PRIORITY 5
 
// Double-call protection
static TaskHandle_t mqtt_hdl = NULL;
 
void mqtt_task_worker(void *arg) {
    while(1) {
        vTaskDelay(pdMS_TO_TICKS(1000));
    }
    mqtt_hdl = NULL;
    vTaskDelete(NULL);
}
 
void start_app_tasks(void) {
    EIF_TAG_WITH_UNUSED "APP_START";
    esp_err_t ret = ESP_OK;
 
    // Macro expands to use TASK_MQTT_NAME, TASK_MQTT_SIZE, etc.
    EIF_TASK_LAUNCH(ret, mqtt_hdl, MQTT, mqtt_task_worker);
   
    if (ret != ESP_OK) {
        EIF_LOG_E("Failed to launch MQTT task");
    }
}

Note

If double-spawn restrictions are not required (e.g., creating multiple instances of the same task), pass a pointer to a temporary standalone task handle variable instead of the main module handle.

Example of use (without double-call protection):

#include <esp_log.h>
#include <freertos/FreeRTOS.h>
#include <freertos/task.h>
#include <esp_iot_framework_core_ext.h>
#include <esp_iot_framework_core_macros.h>
 
// Definitions needed for the 'NAME' alias
#define TASK_NAME_NAME     "mqtt_service"
#define TASK_NAME_SIZE     4096
#define TASK_NAME_PRIORITY 5
 
void task_worker(void *arg) {
    while(1) {
        vTaskDelay(pdMS_TO_TICKS(1000));
    }
    vTaskDelete(NULL);
}
 
void start_app_tasks(void) {
    EIF_TAG_WITH_UNUSED "APP_START";
    esp_err_t ret = ESP_OK;
   
    for (int i = 0; i < 5; i++) {
        TaskHandle_t hdl = NULL;
       
        // Macro expands to use TASK_NAME_NAME, TASK_NAME_SIZE, etc.
        EIF_TASK_LAUNCH(ret, hdl, NAME, task_worker);
        if (ret != ESP_OK) {
            EIF_LOG_E("Failed to launch task iteration %d", i);
        }
    }
}