alf_task_event_handler

NAME

alf_task_event_handler_register - Allows you to register and unregister an event handler for a specific task.

SYNOPSIS

int alf_task_event_handler_register (alf_task_handle_t task_handle, int (*task_event_handler)( alf_task_handle_t task_handle, ALF_TASK_EVENT_TYPE_T event, void* p_data), void* p_data, unsigned int data_size, unsigned int event_mask);

Parameters
`task_handle [IN]`	The handle to a task.
`task_event_handler [IN]`	Pointer of the event handler function for the specified task. A NULL value indicates the current event handler is to be unregistered.
`p_context [IN]`	A pointer to a context buffer that is copied to another buffer managed by the ALF runtime. The pointer to this buffer is passed to the event handler. The content of the context buffer is copied by value only. A NULL value indicates no context buffer.
`context_size [IN]`	The size of the context buffer in bytes. Zero indicates no context buffer.
`event_mask [IN]`	A bitwise OR of `ALF_TASK_EVENT_TYPE_T` values. `ALF_TASK_EVENT_TYPE_T` is defined as follows: `ALF_TASK_EVENT_FINALIZED`: This task has been finalized. No additional work block can be added to this task. The registered event handler is invoked right before `alf_task_finalize` returns. `ALF_TASK_EVENT_READY`: This task has been scheduled for execution. The registered event handler is invoked as soon as the ALF runtime determines that all dependencies have been satisfied for this specific task and can schedule this task for execution as soon as this event handler returns. `ALF_TASK_EVENT_FINISHED`: All work blocks in this task have been processed. The registered event handler is invoked as soon as the last work block has been processed and the task context is written back to host memory. `ALF_TASK_EVENT_INSTANCE_START`: One new instance of the task is started on an accelerator after the event handler returns. `ALF_TASK_EVENT_INSTANCE_END`: One existing instance of the task ends and the task context has been copied out to the original location or has been merged to another current instance of the same task. The event handler is called as soon as the task instance is ended and unloaded from the accelerator. `ALF_TASK_EVENT_DESTROY`: The task is destroyed explicitly.

DESCRIPTION

This function allows you to register an event handler for a specified task. This function can only be called before alf_task_finalize is invoked. An error is returned if a you try to register an event handler for a task that has been finalized.

If the task_event_handler function is NULL, this function unregisters the current event handler. If there is no current event handler, nothing happens.

Note: If the event handler is registered after the task begin to run, some of the events may not be seen.

RETURN VALUE

0	Success
less than 0	Errors occurred: `ALF_ERR_INVAL`: Invalid input handle. `ALF_ERR_BADF`: Invalid ALF task handle. `ALF_ERR_PERM`: The API call is not permitted at the current context. `ALF_ERR_NOMEM`: Out of memory. `ALF_ERR_FAULT`: Invalid buffer or error handler address (only when it is possible to detect the fault). `ALF_ERR_GENERIC`: Generic internal errors.