Embedded Multicore Building Blocks V1.0.0
|
Initialization, introspection, and finalization functions. More...
Classes | |
struct | mtapi_info_struct |
Info structure. More... | |
struct | mtapi_node_attributes_struct |
Node attributes. More... | |
Functions | |
void | mtapi_initialize (const mtapi_domain_t domain_id, const mtapi_node_t node_id, const mtapi_node_attributes_t *attributes, mtapi_info_t *mtapi_info, mtapi_status_t *status) |
Initializes the MTAPI environment on a given MTAPI node in a given MTAPI domain. More... | |
void | mtapi_node_get_attribute (const mtapi_node_t node, const mtapi_uint_t attribute_num, void *attribute, const mtapi_size_t attribute_size, mtapi_status_t *status) |
Given a node and attribute number, returns a copy of the corresponding attribute value in *attribute . More... | |
void | mtapi_finalize (mtapi_status_t *status) |
Finalizes the MTAPI environment on a given MTAPI node and domain. More... | |
mtapi_domain_t | mtapi_domain_id_get (mtapi_status_t *status) |
Returns the domain id associated with the local node. More... | |
mtapi_node_t | mtapi_node_id_get (mtapi_status_t *status) |
Returns the node id associated with the local node and domain. More... | |
Initialization, introspection, and finalization functions.
All applications wishing to use MTAPI functionality must use the initialization and finalization routines. After initialization, the introspection functions can provide important information to MTAPI-based applications.
void mtapi_initialize | ( | const mtapi_domain_t | domain_id, |
const mtapi_node_t | node_id, | ||
const mtapi_node_attributes_t * | attributes, | ||
mtapi_info_t * | mtapi_info, | ||
mtapi_status_t * | status | ||
) |
Initializes the MTAPI environment on a given MTAPI node in a given MTAPI domain.
It must be called on each node using MTAPI. A node maps to a process, thread, thread pool, instance of an operating system, hardware accelerator, processor core, a cluster of processor cores, or another abstract processing entity with an independent program counter. In other words, an MTAPI node is an independent thread of control.
Application software running on an MTAPI node must call mtapi_initialize() once per node. It is an error to call mtapi_initialize() multiple times from a given node, unless mtapi_finalize() is called in between.
The values for domain_id
and node_id
must be known a priori by the application and MTAPI.
mtapi_info
is used to obtain information from the MTAPI implementation, including MTAPI and the underlying implementation version numbers, implementation vendor identification, the number of cores of a node, and vendor-specific implementation information. See the header files for additional information.
A given MTAPI implementation will specify what is a node, i.e., how the concrete system is partitioned into nodes and what are the underlying units of execution executing tasks, e.g., threads, a thread pool, processes, or hardware units.
attributes
is a pointer to a node attributes object that was previously prepared with mtapi_nodeattr_init() and mtapi_nodeattr_set(). If attributes
is MTAPI_NULL
, then the following default attributes will be used:
On success, *status
is set to MTAPI_SUCCESS
. On error, *status
is set to the appropriate error defined below.
Error code | Description |
---|---|
MTAPI_ERR_NODE_INITFAILED | MTAPI environment could not be initialized. |
MTAPI_ERR_NODE_INITIALIZED | MTAPI environment was already initialized. |
MTAPI_ERR_NODE_INVALID | The node_id parameter is not valid. |
MTAPI_ERR_DOMAIN_INVALID | The domain_id parameter is not valid. |
MTAPI_ERR_PARAMETER | Invalid mtapi_node_attributes or mtapi_info. |
[in] | domain_id | Domain id |
[in] | node_id | Node id |
[in] | attributes | Pointer to attributes |
[out] | mtapi_info | Pointer to info struct |
[out] | status | Pointer to error code, may be MTAPI_NULL |
void mtapi_node_get_attribute | ( | const mtapi_node_t | node, |
const mtapi_uint_t | attribute_num, | ||
void * | attribute, | ||
const mtapi_size_t | attribute_size, | ||
mtapi_status_t * | status | ||
) |
Given a node and attribute number, returns a copy of the corresponding attribute value in *attribute
.
See mtapi_nodeattr_set() for a list of predefined attribute numbers and the sizes of the attribute values. The application is responsible for allocating sufficient space for the returned attribute value and for setting attribute_size
to the exact size in bytes of the attribute value.
On success, *status
is set to MTAPI_SUCCESS
and the attribute value will be written to *attribute
. On error, *status
is set to the appropriate error defined below and *attribute
is undefined.
Error code | Description |
---|---|
MTAPI_ERR_PARAMETER | Invalid attribute parameter. |
MTAPI_ERR_ATTR_NUM | Unknown attribute number. |
MTAPI_ERR_ATTR_SIZE | Incorrect attribute size. |
MTAPI_ERR_NODE_NOTINIT | The calling node is not initialized. |
[in] | node | Node handle |
[in] | attribute_num | Attribute id |
[out] | attribute | Pointer to attribute value |
[in] | attribute_size | Size of attribute value |
[out] | status | Pointer to error code, may be MTAPI_NULL |
void mtapi_finalize | ( | mtapi_status_t * | status | ) |
Finalizes the MTAPI environment on a given MTAPI node and domain.
It has to be called by each node using MTAPI. It is an error to call mtapi_finalize() without first calling mtapi_initialize(). An MTAPI node can call mtapi_finalize() once for each call to mtapi_initialize(), but it is an error to call mtapi_finalize() multiple times from a given node unless mtapi_initialize() has been called prior to each mtapi_finalize() call.
All tasks that have not completed and that have been started on the node where mtapi_finalize() is called will be canceled (see mtapi_task_cancel()). mtapi_finalize() blocks until all tasks that have been started on the same node return (long-running tasks already executing must actively poll the task state and return if canceled). Tasks that execute actions on the node where mtapi_finalize() is called, also block finalization of the MTAPI runtime system on that node. They are canceled as well and return with an MTAPI_ERR_NODE_NOTINIT
status. Other functions that have a dependency to the node and that are called after mtapi_finalize() also return MTAPI_ERR_NODE_NOTINIT
(e.g., mtapi_task_get() starting a task associated with an action implemented on the already-finalized node).
mtapi_finalize() may not be called from an action function.
On success, *status
is set to MTAPI_SUCCESS
. On error, *status
is set to the appropriate error defined below.
Error code | Description |
---|---|
MTAPI_ERR_NODE_FINALFAILED | The MTAPI environment couldn't be finalized. |
MTAPI_ERR_NODE_NOTINIT | The calling node is not initialized. |
[out] | status | Pointer to error code, may be MTAPI_NULL |
mtapi_domain_t mtapi_domain_id_get | ( | mtapi_status_t * | status | ) |
Returns the domain id associated with the local node.
On success, *status
is set to MTAPI_SUCCESS
. On error, *status
is set to the appropriate error defined below.
Error code | Description |
---|---|
MTAPI_ERR_NODE_NOTINIT | The calling node is not initialized. |
[out] | status | Pointer to error code, may be MTAPI_NULL |
mtapi_node_t mtapi_node_id_get | ( | mtapi_status_t * | status | ) |
Returns the node id associated with the local node and domain.
On success, *status
is set to MTAPI_SUCCESS
. On error, *status
is set to the appropriate error defined below.
Error code | Description |
---|---|
MTAPI_ERR_NODE_NOTINIT | The calling node is not initialized. |
[out] | status | Pointer to error code, may be MTAPI_NULL |