The CAA Async Manager provides a managing mechanism for jobs to be executed asynchronously. The execution of the jobs itself has to be done by a worker. The following phase diagram describes the workflow.
DORMANT: With help of the function ⇘ ASM.JobOpen or ⇘ ASM.JobOpenEx a new job will be created. After its creation the job will be in state DORMANT. During this state the function ⇘ ASM.JobGetParams will return a pointer to an allocated memory area. This memory area has to be filled with the parameter values of the job.By use of function ⇘ ASM.JobClose all resources allocated by the job and the job itself will be released. By calling the function ⇘ ASM.JobExecute the job will switch to the state BUSY.
BUSY: The state BUSY indicates that the job is being executed. The user may abort the execution by use of the function ASM.JobAbort; else the worker will terminate the execution. After this the job will be assigned to one of the three states: ABORTED, DONE or STATE_ERROR.
ABORTED: The job will be in state ABORTED, if the user has aborted the execution by ⇘ ASM.JobAbort. By calling the function ⇘ ASM.JobReset the job can be reset to DORMANT.
DONE: A job is in state DONE, if it has been executed successfully. To be able to evaluate the return value of the job the user has to call the function ⇘ ASM.JobGetParams. In addition to the parameter values the allocated memory area contains the return value. By function ⇘ ASM.JobReset the job can be reset to DORMANT.
STATE_ERROR: A job is in state STATE_ERROR, if its execution failed. The function ⇘ ASM.JobGetState will return the data structure STATE, whose component eError contains the error code. By use of the function ⇘ ASM.JobReset the job can be reset to DORMANT.
As already mentioned a worker has to undertake the execution of the job. For each type of a job (e.g.FileOpen or FileClose) a worker has to be registered. Only these jobs a worker has been registered for can be executed. The user is not in charge of calling the worker, which may only be called by the Async Manager. A worker implements the following functions:
| 1. | pfExecute: Starts execution of a job. |
| 2. | pfAbort: Aborts execution of a job. |
| 3. | pfGetState: Returns the state of execution. |
| 4. | pfDispose: Deallocates the resources for the job execution. |
| 5. | pfGetParamSize: Returns the size of the memory area necessary for the parameters of the job. |
The execution queue comprises all jobs to be executed. As long as a job has not been executed yet, a call of ASM.JobGetState will return the state BUSY: The function ASM.JobExecQueue will dequeue the next job and call the function pfExec of the associated worker.
On implementing the CAA Asnyc Managers you have to pay attention to ASM.JobExecQueue being called in an asynchronous context. Per default the following facilities are provided:
| 1. | Asynchronous within an own task: While initializing the runtime system a task pool is created. As soon as a job is enqueued in the Execution Queue, a task of the pool will be started. This task will call the function ⇘ ASM.JobExecQueue. The job being executed the task will be suspended and restored in the task pool. |
| 2. | Asynchronous within the Idle Loop: The function ⇘ ASM.JobExecQueue will be called cyclically by the Idle Loop of the runtime system. A job being placed into the Execution Queue will be executed within the Idle Loop. |
| 3. | OEM specific: The runtime system does not care for the work-off of the queue. The OEM has to ensure that the function ⇘ ASM.JobExecQueue will be called at the right moment. |
BUSY: The state BUSY indicates that the job is being executed. The user may abort the execution by use of the function ASM.JobAbort; else the worker will terminate the execution. After this the job will be assigned to one of the three states: ABORTED, DONE or STATE_ERROR.