ESPShell : Process Control : kill, suspend and resume

[ На русском ] ↔ [ English ]

Process Control
Suspend, Resume and Kill

PROCESS CONTROL

Process control is implemented through three commands: suspend, resume, and kill. By "processes," we mean FreeRTOS tasks. For example, the main Arduino loop() runs as a dedicated FreeRTOS task named "loop" - so "loop()" is a process.

Tasks are accessed and controlled using their TASK_ID (a hexadecimal number, e.g., "0x3fca370c"), except for the main Arduino loop() task: the main sketch execution can be controlled by omitting the TASK_ID parameter in the command. That is, to suspend the sketch, instead of writing "suspend 0x12345678", one can simply use "suspend" without arguments.

Okay, but where can we get these task IDs?

It's simple: every ESPShell command that is run as a background process displays its TASK_ID. Let's say we execute the command "pin 2 delay 1000" in the background:

esp32#>pin 2 delay 1000 &
% Background task started
% Copy/paste "kill 0x3ffb91dc" to abort
esp32#>

This command doesn't do much -just waits for 1000ms. Once started, it prints its task ID along with a convenient "kill" command that can be copied and executed: "kill 0x3ffb91dc".

Another source of TASK_IDs is the "show counters" command.

SUSPEND, RESUME AND KILL

Command	Description and examples
suspend	Pauses sketch execution by suspending Arduino's loop(). Tasks that were started by loop() and setup() are not suspended by this command. Suspending a task along with all of its child tasks is a planned but not yet implemented feature. Ctrl+C is a hotkey for the "suspend" command.
suspend TASK_ID	suspend TASK_ID Suspends an arbitrary task if its TASK_ID is known. The command requires one argument -a hexadecimal task ID.
resume	Resumes sketch execution.
resume TASK_ID	resume TASK_ID Resumes an arbitrary task if its TASK_ID is known. The command requires one argument -a hexadecimal task ID.

To stop an ESPShell task (ESPShell uses tasks to run background commands) or any arbitrary FreeRTOS task, use the kill command:

Command Description and examples

Command	Description and examples
kill TASK_ID	kill [-TERM \| -15 \| -KILL \| -9] TASK_ID Stops execution of the task with the given TASK_ID. This ID is either printed when a background command is started or is the identifier of a generic FreeRTOS task. If the "&" symbol is used at the end of a command, ESPShell executes it in the background by spawning a new task: esp32#>pin 2 delay 999 & % Background task started % Copy/paste "kill 0x3fca370c" command to stop execution ← note the TASK_ID esp32#> In the simplest case -when only the TASK_ID is provided -the command sends a notification to the task in an attempt to initiate a graceful shutdown. This command mimics the classic Linux `kill` command and accepts an optional signal parameter. -9 or -KILL means forcibly terminate the task: no notification is sent; the task is suspended and then deleted via the FreeRTOS API `vTaskDelete()`. However, resources used by the task are not freed. Force-killing a task holding a mutex may result in system lockups. All ESPShell-created tasks should normally be terminated this way -without using any additional parameters. However, there are examples of ESPShell commands that can only be terminated using `kill -9`. These special cases are described in the documentation for the "pin" command. Using -15, -TERM, or no signal at all indicates a graceful shutdown: the task is not deleted but is given a chance to terminate itself and release any allocated resources. Using -9 or -KILL results in immediate task suspension and deletion via FreeRTOS `vTaskDelete()`. This is equivalent to the Linux `kill -9` command, but unlike its Linux counterpart, ESPShell does not release any memory or resources allocated by the task.

kill TASK_ID

kill [-TERM | -15 | -KILL | -9] TASK_ID

Stops execution of the task with the given TASK_ID. This ID is either printed when a background command is started or is the identifier of a generic FreeRTOS task. If the "&" symbol is used at the end of a command, ESPShell executes it in the background by spawning a new task:

      esp32#>pin 2 delay 999 &
      % Background task started
      % Copy/paste "kill 0x3fca370c" command to stop execution  ← note the TASK_ID
      esp32#>

In the simplest case -when only the TASK_ID is provided -the command sends a notification to the task in an attempt to initiate a graceful shutdown.

This command mimics the classic Linux kill command and accepts an optional signal parameter. -9 or -KILL means forcibly terminate the task: no notification is sent; the task is suspended and then deleted via the FreeRTOS API vTaskDelete(). However, resources used by the task are not freed. Force-killing a task holding a mutex may result in system lockups.

All ESPShell-created tasks should normally be terminated this way -without using any additional parameters. However, there are examples of ESPShell commands that can only be terminated using kill -9. These special cases are described in the documentation for the "pin" command.

Using -15, -TERM, or no signal at all indicates a graceful shutdown: the task is not deleted but is given a chance to terminate itself and release any allocated resources.

Using -9 or -KILL results in immediate task suspension and deletion via FreeRTOS vTaskDelete(). This is equivalent to the Linux kill -9 command, but unlike its Linux counterpart, ESPShell does not release any memory or resources allocated by the task.