16.2 OS20 function descriptions 16 Alphabetical list of functions
task_kill
Kill a task
Synopsis
#include <task.h> int task_kill( task_t* task, int status, task_kill_flags_t flags );
Arguments task_t* task int status
The task to be killed
The task’s exit status task_kill_flags_t flags Additional flags
Results
Returns 0 if the task is successfully killed, -1 if it cannot be killed.
Errors
If the task has been deleted, is a high priority process, then this call fails.
Description task_kill kills the task specified by task , causing it to stop running, and call its exit handler. If task is NULL then the current task is killed. If the task was waiting on any objects when it is killed, it is removed from the list of tasks waiting for that object before the exit handler is called.
status is the exit status for the task. Thus task_kill can be viewed as a way of forcing the task to call: task_exit(status)
Normally flags should have the value 0 . However, by specifying the value task_kill_flags_no_exit_handler , it is possible to prevent the task calling its exit handler, and so it terminates immediately, never running again.
Note: When task_kill is used to kill a task with the task_kill_flags_no_exit_handler flag set, any waiting tasks (caused by task_wait ) are not informed that the task has been killed. This is because the exit handler is used to inform waiting tasks, so if the exit handler is not called the waiting tasks are not informed about the event.
A task can temporarily make itself immune to being killed by calling task_immortal ; see
Section 5.11: Killing a task on page 36
for more details. When a task which has made itself immortal is killed, task_kill returns immediately, but the killed task does not die until it makes itself mortal again.
Note: task_kill may return before the task has died. A task_kill should normally be followed by a task_wait to be sure that the task has made itself mortal again, and completed its exit handler.
On ST20-C2 cores task_kill cannot be used on a high priority process.
263
ADCS 7473749D
OS20 User Manual
Callable from
Tasks only
Example void tidy_up(task_t* task, int status)
{ task_kill(task, status, 0); task_wait(&task, 1, TIMEOUT_INFINITY); task_delete(task);
}
See also
task_delete ,
task_immortal ,
task_mortal
16.2 OS20 function descriptions
264
ADCS 7473749D
