Returns a handle to the newly created task on success, or NULL_HANDLE on failure. To obtain extended error information, call the osGetLastError function.

This function creates a new task.

The newly created task begins execution at the address defined by the TaskProc parameter. The specified function is invoked with the argument provided in the Arg parameter. When the task function returns, the task terminates and its exit code is set to the returned value. Returning from the task function is equivalent to calling the osExitTask function. Additionally, a task may be terminated by another task using osTerminateTask, provided that OS_TERMINATE_TASK_FUNC is set to 1. If a task is terminated by another task, its exit code is always set to ERR_TASK_TERMINATED_BY_OTHER. If OS_TASK_EXIT_CODE_FUNC is enabled, the osGetTaskExitCode function can be used to retrieve the exit code of a finished task.

Upon task creation, a memory buffer for the task stack is allocated with the size specified in the StackSize parameter. If StackSize is zero, the task is created using the default stack size defined in OS_DEFAULT_TASK_STACK_SIZE.

Tasks can be created at any time: prior to system startup, from within an interrupt service routine, or by another running task. If a task is created by another task and its priority is higher than that of the creator, the new task begins execution immediately. If the priority is equal or lower, the new task is placed at the end of the ready-to-run queue if OS_RESUME_IMMEDIATELY is set to 0, or at the beginning of the queue if it is set to 1.

If the Suspended argument is set to TRUE, the task is created in a suspended state and will not execute until osResumeTask is called. This parameter is ignored if OS_SUSP_RES_TASK_FUNC is configured as 0.

Tasks are system objects and can exist in either a signaled or non-signaled state. A task remains non-signaled until it terminates. Any tasks waiting on the task object are resumed once the task enters the signaled (terminated) state.

The task object remains in the system until it has terminated and all handles opened to it (including the handle returned to the creator) have been closed using osCloseHandle. Once these conditions are met, the task object is removed. The object is not automatically removed if it was created before system startup, from an interrupt, or if all handles were closed prior to its termination.

The allocation of the stack and initialization of the task context are handled by architecture-specific code. For further details, refer to the arCreateTaskContext description.