![]() |
bsp-microej-async-worker
0.2.1
bsp-microej-async-worker
|
Asynchronous Worker API. This library helps writing SNI functions that must be executed asynchronously. More...
#include <stdint.h>
#include "sni.h"
#include "osal.h"
Go to the source code of this file.
Data Structures | |
struct | MICROEJ_ASYNC_WORKER_job |
A job to execute in a worker. More... | |
struct | MICROEJ_ASYNC_WORKER_handle_t |
An async worker. More... | |
Macros | |
#define | MICROEJ_ASYNC_WORKER_worker_declare(_name, _job_count, _param_type, _waiting_list_size) |
Declares a worker named _name . More... | |
Typedefs | |
typedef struct MICROEJ_ASYNC_WORKER_job | MICROEJ_ASYNC_WORKER_job_t |
See struct MICROEJ_ASYNC_WORKER_job . | |
typedef void(* | MICROEJ_ASYNC_WORKER_action_t) (MICROEJ_ASYNC_WORKER_job_t *job) |
Pointer to a function to call asynchronously. | |
Enumerations | |
enum | MICROEJ_ASYNC_WORKER_status_t { MICROEJ_ASYNC_WORKER_OK, MICROEJ_ASYNC_WORKER_ERROR, MICROEJ_ASYNC_WORKER_INVALID_ARGS } |
Return codes list. | |
Asynchronous Worker API. This library helps writing SNI functions that must be executed asynchronously.
The execution of an SNI function prevents the other Java thread to be scheduled. That's why blocking native functions or long native functions should be executed asynchronously.
An async worker is declared statically using the MICROEJ_ASYNC_WORKER_worker_declare()
macro and started with the MICROEJ_ASYNC_WORKER_initialize()
function. Jobs are allocated using MICROEJ_ASYNC_WORKER_allocate_job()
and scheduled with MICROEJ_ASYNC_WORKER_async_exec()
.
Typical usage consists in declaring:
MICROEJ_ASYNC_WORKER_worker_declare()
macro. For example, if we have to implement asynchronously the following two SNI functions :
Then we will declare the async worker as following:
Definition in file microej_async_worker.h.
#define MICROEJ_ASYNC_WORKER_worker_declare | ( | _name, | |
_job_count, | |||
_param_type, | |||
_waiting_list_size | |||
) |
Declares a worker named _name
.
This macro must be used outside of any function so the worker is declared as a global variable.
_name | name of the worker variable. |
_job_count | maximum number of jobs that can be allocated for this worker. Must be greater than 0. |
_param_type | type of the union of all the parameters structures |
_waiting_list_size | Maximum Java thread that can be suspended on MICROEJ_ASYNC_WORKER_allocate_job() when no job is available. Must be greater than 0. |
Definition at line 194 of file microej_async_worker.h.
MICROEJ_ASYNC_WORKER_job_t* MICROEJ_ASYNC_WORKER_allocate_job | ( | MICROEJ_ASYNC_WORKER_handle_t * | async_worker, |
SNI_callback | sni_retry_callback | ||
) |
Allocates a new job for the given worker.
If a job is available, returns a reference to the job.
If there is no job available, the current Java thread is suspended, added to the waiting list and NULL
is returned. Then, when a job is available, the Java thread is resumed and the function sni_retry_callback
is called. Usually the sni_retry_callback
function argument is the current SNI function itself (i.e. the function that is currently calling MICROEJ_ASYNC_WORKER_allocate_job()
).
If the waiting list is full, an SNI exception is thrown using SNI_throwNativeIOException()
and NULL
is returned. Size of the waiting list is defined when declaring the worker.
params
field of the returned job is a pointer to a type T
where T
is the value of the argument _param_type
given to the MICROEJ_ASYNC_WORKER_worker_declare()
macro.
This function must be called within the virtual machine task.
[in] | async_worker | the worker in which to allocate a job. |
[in] | sni_retry_callback | if the current Java thread has been suspended, this function is called when it is resumed. |
Definition at line 76 of file microej_async_worker.c.
MICROEJ_ASYNC_WORKER_status_t MICROEJ_ASYNC_WORKER_async_exec | ( | MICROEJ_ASYNC_WORKER_handle_t * | async_worker, |
MICROEJ_ASYNC_WORKER_job_t * | job, | ||
MICROEJ_ASYNC_WORKER_action_t | action, | ||
SNI_callback | on_done_callback | ||
) |
Executes the given job asynchronously.
This function does not block and returns immediately but it suspends the execution of the current Java thread until the job is finished.
When the job is finished, the SNI callback on_done_callback
is called before going back to Java. If the job is not used anymore, the callback must released it explicitly by calling MICROEJ_ASYNC_WORKER_free_job()
.
If an error happens, an SNI exception is thrown using SNI_throwNativeIOException()
and the error status MICROEJ_ASYNC_WORKER_ERROR
is returned. In this case, the SNI callback on_done_callback
is not called and the job must be released explicitly by calling MICROEJ_ASYNC_WORKER_free_job()
.
This function must be called within the virtual machine task.
[in] | async_worker | the worker used to execute the given job. Must be the same than the one used to allocate the job. |
[in] | job | the job to execute. Must have been allocated with MICROEJ_ASYNC_WORKER_allocate_job() . |
[in] | action | the function to execute asynchronously. |
[in] | on_done_callback | the SNI_callback called when the job is done. |
MICROEJ_ASYNC_WORKER_OK
on success, otherwise returns the error status MICROEJ_ASYNC_WORKER_ERROR
. Definition at line 140 of file microej_async_worker.c.
MICROEJ_ASYNC_WORKER_status_t MICROEJ_ASYNC_WORKER_async_exec_no_wait | ( | MICROEJ_ASYNC_WORKER_handle_t * | async_worker, |
MICROEJ_ASYNC_WORKER_job_t * | job, | ||
MICROEJ_ASYNC_WORKER_action_t | action | ||
) |
Executes the given job asynchronously.
This function does not block and returns immediately.
When the job is finished, the job is automatically released by the async worker thread.
If an error happens, an SNI exception is thrown using SNI_throwNativeIOException()
and the error status MICROEJ_ASYNC_WORKER_ERROR
is returned. In this case, the job must be released explicitly by calling MICROEJ_ASYNC_WORKER_free_job()
.
This function must be called within the virtual machine task.
[in] | async_worker | the worker used to execute the given job. Must be the same than the one used to allocate the job. |
[in] | job | the job to execute. Must have been allocated with MICROEJ_ASYNC_WORKER_allocate_job() . |
[in] | action | the function to execute asynchronously. |
MICROEJ_ASYNC_WORKER_OK
on success, otherwise returns the error status MICROEJ_ASYNC_WORKER_ERROR
. Definition at line 144 of file microej_async_worker.c.
MICROEJ_ASYNC_WORKER_status_t MICROEJ_ASYNC_WORKER_free_job | ( | MICROEJ_ASYNC_WORKER_handle_t * | async_worker, |
MICROEJ_ASYNC_WORKER_job_t * | job | ||
) |
Frees a job previously allocated with MICROEJ_ASYNC_WORKER_allocate_job().
This function must be called when and only when the given job has been executed and the result retrieved. This is usually done in the on_done_callback given to MICROEJ_ASYNC_WORKER_async_exec(). After calling this function the given job and its parameters must not be used anymore.
This function must be called within the virtual machine task.
[in] | async_worker | the worker used to allocate the given job. |
[in] | job | the job to free. Must have been allocated with MICROEJ_ASYNC_WORKER_allocate_job(). |
MICROEJ_ASYNC_WORKER_OK
on success, otherwise returns the error status MICROEJ_ASYNC_WORKER_ERROR
. Definition at line 117 of file microej_async_worker.c.
MICROEJ_ASYNC_WORKER_job_t* MICROEJ_ASYNC_WORKER_get_job_done | ( | void | ) |
Returns the job that has been executed.
This function must be called after the execution of a job in the function passed as on_done_callback
argument to MICROEJ_ASYNC_WORKER_async_exec()
.
NULL
if not called from an on_done_callback
. Definition at line 172 of file microej_async_worker.c.
MICROEJ_ASYNC_WORKER_status_t MICROEJ_ASYNC_WORKER_initialize | ( | MICROEJ_ASYNC_WORKER_handle_t * | async_worker, |
uint8_t * | name, | ||
OSAL_task_stack_t | stack, | ||
int32_t | priority | ||
) |
Initializes and starts a worker previously declared with MICROEJ_ASYNC_WORKER_worker_declare()
macro.
[in] | async_worker | the worker to initialize. Declared with MICROEJ_ASYNC_WORKER_worker_declare() macro. |
[in] | name | worker name. |
[in] | stack | worker task stack declared using OSAL_task_stack_declare() macro. |
[in] | priority | worker task priority. |
Definition at line 33 of file microej_async_worker.c.