alf_task_create

NAME

alf_task_create - Creates a task and allows you to add work blocks to the work queue of the task.

SYNOPSIS

int alf_task_create(alf_task_desc_handle_t task_desc_handle, void* p_task_context_data, unsigned int num_instances, unsigned int tsk_attr, unsigned int wb_dist_size, alf_task_handle_t *p_task_handle);

Parameters
`task_desc_handle [IN]`	Handle to a `task_desc` structure.
`p_task_context_data [IN]`	Pointer to the task context data for this task. The structure and size for the task context have been defined through `alf_task_desc_add_task_ctx_entry`. If there is no `task_context`, a NULL pointer can be provided.
`num_instances [IN]`	Number of instances of the task, only used when `ALF_TASK_ATTR_SCHED_FIXED` is provided.
`tsk_attr [IN]`	Attribute for a task. This value can be set to a bit-wise OR to one of the following: `ALF_TASK_ATTR_SCHED_FIXED`: The task must be scheduled on the specified number of accelerators. By default, a task can be scheduled on any number of accelerators and the number of accelerators can be adjusted at anytime during the execution of the task. `ALF_TASK_ATTR_WB_CYCLIC`: the work blocks for this task are distributed to the accelerators in a cyclic order as specified by `num_accelerators`. By default, the work blocks distribution order is determined by the ALF runtime. This option must be used combined with `ALF_TASK_ATTR_SCHED_FIXED`.
`wb_dist_size [IN]`	The specified block distribution bundle size in number of work blocks per distribution unit. A 0 (zero) value is treated as 1 (one). Refer to Work block scheduling for more details about work block distribution.
`p_task_handle [OUT]`	Returns a handle to the created task. The content of the pointer is not modified if the call returns failure.

DESCRIPTION

This function creates a task and allows you to enqueue work blocks to the task. The task remains in a pending status until the following condition is met: All dependencies are satisfied and either at least one work block is added or the task is finalized by calling alf_task_finalize.

When the condition is met, the task becomes ready to run. However, when the task actually starts to run depends on the available accelerator resources and the scheduling of ALF runtime. Multiple independent tasks can also run concurrently if there are enough accelerator resources. When the task starts to run, it keeps running until at least one of the following two conditions is met:

The task has been finalized by calling alf_task_finalize and all the enqueued work blocks are processed and the task context has been merged and written back;
alf_task_destroy is called to explicitly destroy the task.

Note: A finalized task without any work block enqueued is never actually loaded and run. The runtime considers this task as completed immediately after the dependencies are satisfied.

RETURN VALUE

Successful

less than 0

Errors occurred:

ALF_ERR_INVAL: Invalid input argument
ALF_ERR_BADF: Invalid ALF handle
ALF_ERR_NOMEM: Out of memory or system resource
ALF_ERR_PERM: The API call is not permitted at the current context
ALF_ERR_NOEXEC: Invalid task image format or description information
ALF_ERR_2BIG: Memory requirement for the task exceeds maximum range
ALF_ERR_NOSYS: The required task attribute is not supported
ALF_ERR_BADR: The requested number of accelerator resources is not available
ALF_ERR_GENERIC: Generic internal errors