Task handle usage in FreeRTOS - Step-by-Step Execution

Concept Flow - Task handle usage

Create Task

↓

Store Task Handle

↓

Use Handle to Control Task

↓

Delete or Suspend Task Using Handle

↓

End

Create a task and save its handle to control it later, like suspending or deleting.

Execution Sample

FreeRTOS

TaskHandle_t xHandle = NULL;

void vTaskCode(void * pvParameters) {
    for(;;) {
        // Task work here
    }
}

xTaskCreate(vTaskCode, "Task1", 1000, NULL, 1, &xHandle);

Creates a task and saves its handle in xHandle for later control.

Execution Table

Step	Action	Variable/Handle State	Result/Output
1	Declare xHandle as NULL	xHandle = NULL	No task created yet
2	Define task function vTaskCode	No change	Task code ready
3	Call xTaskCreate with &xHandle	xHandle assigned task handle	Task created and handle stored
4	Task runs in background	xHandle valid	Task executes loop
5	Use xHandle to suspend task	xHandle unchanged	Task suspended
6	Use xHandle to delete task	xHandle unchanged	Task deleted
7	End of usage	xHandle still holds handle value	Handle can be reused or set NULL

💡 Task handle allows control of the created task after creation

Variable Tracker

Variable	Start	After xTaskCreate	After Suspend	After Delete
xHandle	NULL	Valid Task Handle	Valid Task Handle	Valid Task Handle (handle value remains)

Key Moments - 3 Insights

Why do we pass &xHandle to xTaskCreate instead of xHandle?

Because xTaskCreate needs to write the new task's handle back to xHandle, so we pass its address. See execution_table step 3.

Does the task handle change after suspending or deleting the task?

No, the handle variable keeps the same value until you change it manually. See execution_table steps 5 and 6.

Can we use the task handle before the task is created?

No, the handle is NULL before creation and only valid after xTaskCreate returns successfully. See execution_table steps 1 and 3.

Visual Quiz - 3 Questions

Look at the execution_table, what is the value of xHandle right after xTaskCreate is called?

A NULL

B Undefined

C Valid Task Handle

D 0

💡 Hint

Check execution_table row 3 under Variable/Handle State

At which step does the task start running its code?

A Step 4

B Step 2

C Step 3

D Step 5

💡 Hint

Look for when the task executes the loop in execution_table

If we never store the task handle, what can we NOT do later?

A Create the task

B Suspend or delete the task

C Run the task code

D Define the task function

💡 Hint

Refer to concept_flow and key_moments about handle usage for control

Concept Snapshot

Task Handle Usage in FreeRTOS:
- Declare TaskHandle_t variable (e.g., xHandle)
- Pass &xHandle to xTaskCreate to get handle
- Use handle to suspend, resume, or delete task
- Handle remains valid until task is deleted
- Handle is NULL before task creation

Full Transcript

In FreeRTOS, when you create a task, you can save its handle in a variable. This handle lets you control the task later, like pausing or deleting it. First, declare a TaskHandle_t variable and set it to NULL. Then, when calling xTaskCreate, pass the address of this variable so FreeRTOS can store the new task's handle there. After creation, the handle is valid and you can use it to suspend or delete the task. The handle value stays the same even after suspending or deleting the task until you change it manually. Without storing the handle, you cannot control the task after creation.

Practice

1.

What is the main purpose of a task handle in FreeRTOS?

easy

A. To allocate memory for tasks

B. To store task priority values

C. To identify and control a specific task

D. To define the task's stack size

Solution

1. Step 1: Understand what a task handle represents

   A task handle is a reference used to identify a task uniquely in FreeRTOS.

2. Step 2: Identify the purpose of the handle

   The handle allows you to control the task, such as suspending or deleting it.

3. Final Answer:

   To identify and control a specific task -> Option C

4. Quick Check:

   Task handle = task control reference [OK]

Hint: Task handles let you control tasks by their ID [OK]

Common Mistakes:

• Confusing handle with task priority
• Thinking handle allocates memory
• Mixing handle with stack size

2.

Which of the following is the correct way to declare a task handle variable in FreeRTOS?

?

easy

A. TaskHandle_t xTaskHandle;

B. TaskHandle xTaskHandle;

C. HandleTask_t xTaskHandle;

D. Task_Handle xTaskHandle;

Solution

1. Step 1: Recall the FreeRTOS type for task handles

   The correct type defined by FreeRTOS for task handles is TaskHandle_t.

2. Step 2: Check the syntax of declaration

   Declaring a variable as TaskHandle_t xTaskHandle; is the correct syntax.

3. Final Answer:

   TaskHandle_t xTaskHandle; -> Option A

4. Quick Check:

   Task handle type = TaskHandle_t [OK]

Hint: Use TaskHandle_t to declare task handles [OK]

Common Mistakes:

• Using incorrect type names
• Adding underscores wrongly
• Confusing with other handle types

3.

What will be the output of the following code snippet?

TaskHandle_t xHandle = NULL;

void vTaskFunction(void *pvParameters) {
    for (;;) {
        vTaskDelay(pdMS_TO_TICKS(1000));
    }
}

int main() {
    xTaskCreate(vTaskFunction, "Task1", 1000, NULL, 1, &xHandle);
    if (xHandle != NULL) {
        printf("Task created successfully\n");
    } else {
        printf("Task creation failed\n");
    }
    return 0;
}

medium

A. Task creation failed

B. Task created successfully

C. Compilation error due to missing includes

D. No output, program hangs

Solution

1. Step 1: Analyze task creation and handle assignment

   The function xTaskCreate assigns the created task's handle to xHandle. If successful, xHandle is not NULL.

2. Step 2: Check the condition and output

   The code checks if xHandle != NULL and prints "Task created successfully" if true.

3. Final Answer:

   Task created successfully -> Option B

4. Quick Check:

   xHandle != NULL means success [OK]

Hint: Check if handle is NULL to confirm task creation [OK]

Common Mistakes:

• Assuming handle is NULL on success
• Ignoring handle assignment
• Confusing task creation return value

4.

Identify the error in the following code snippet related to task handle usage:

TaskHandle_t xTaskHandle;

void vTaskFunction(void *pvParameters) {
    for (;;) {
        vTaskDelay(pdMS_TO_TICKS(500));
    }
}

int main() {
    xTaskCreate(vTaskFunction, "Task", 1000, NULL, 1, xTaskHandle);
    vTaskSuspend(xTaskHandle);
    return 0;
}

medium

A. xTaskCreate should pass &xTaskHandle, not xTaskHandle

B. vTaskSuspend cannot suspend a task

C. Task handle must be initialized to NULL before use

D. Task priority is missing in xTaskCreate

Solution

1. Step 1: Check how task handle is passed to xTaskCreate

   The last parameter of xTaskCreate expects a pointer to the task handle variable, so it should be &xTaskHandle.

2. Step 2: Identify the error in the code

   The code passes xTaskHandle instead of its address, causing incorrect handle assignment.

3. Final Answer:

   xTaskCreate should pass &xTaskHandle, not xTaskHandle -> Option A

4. Quick Check:

   Pass handle address to xTaskCreate [OK]

Hint: Always pass &handle to xTaskCreate [OK]

Common Mistakes:

• Passing handle instead of its address
• Assuming vTaskSuspend needs no handle
• Ignoring task priority parameter

5.

You want to create two tasks and suspend the first one after creation using task handles. Which code snippet correctly achieves this?

void vTask1(void *pvParameters) { for(;;) {} }
void vTask2(void *pvParameters) { for(;;) {} }

int main() {
    TaskHandle_t xHandle1 = NULL, xHandle2 = NULL;
    // Create tasks here
    // Suspend first task here
    return 0;
}

hard

A. xTaskCreate(vTask1, "Task1", 1000, NULL, 1, &xHandle1);
xTaskCreate(vTask2, "Task2", 1000, NULL, 1, &xHandle2);
vTaskSuspend(NULL);

B. xTaskCreate(vTask1, "Task1", 1000, NULL, 1, xHandle1);
xTaskCreate(vTask2, "Task2", 1000, NULL, 1, xHandle2);
vTaskSuspend(xHandle1);

C. xTaskCreate(vTask1, "Task1", 1000, NULL, 1, &xHandle1);
xTaskCreate(vTask2, "Task2", 1000, NULL, 1, &xHandle2);
vTaskSuspend(&xHandle1);

D. xTaskCreate(vTask1, "Task1", 1000, NULL, 1, &xHandle1);
xTaskCreate(vTask2, "Task2", 1000, NULL, 1, &xHandle2);
vTaskSuspend(xHandle1);

Solution

1. Step 1: Correctly create tasks with handles

   Use &xHandle1 and &xHandle2 to store task handles during creation.

2. Step 2: Suspend the first task using its handle

   Call vTaskSuspend(xHandle1); to suspend the first task by passing the handle itself, not its address or NULL.

3. Final Answer:

   Correct creation with &xHandle and suspend with xHandle1 -> Option D

4. Quick Check:

   Create with &handle, suspend with handle [OK]

Hint: Create tasks with &handle, suspend using handle [OK]

Common Mistakes:

• Passing handle instead of &handle to xTaskCreate
• Passing &handle to vTaskSuspend instead of handle
• Suspending with NULL handle