Embedded Multicore Building Blocks V1.0.0
Classes | Functions

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...
 

Detailed Description

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.

Function Documentation

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:

  • all available cores will be used
  • the main thread will be reused as a worker
  • maximum number of tasks is 1024
  • maximum number of groups is 128
  • maximum number of queues is 16
  • maximum queue capacity is 1024
  • maximum number of priorities is 4.

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.
See also
mtapi_nodeattr_init(), mtapi_nodeattr_set()
Concurrency
Not thread-safe
Dynamic memory allocation
Allocates some memory depending on the node attributes. The amount allocated is returned in the mtapi_info structure.
Parameters
[in]domain_idDomain id
[in]node_idNode id
[in]attributesPointer to attributes
[out]mtapi_infoPointer to info struct
[out]statusPointer 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.
See also
mtapi_nodeattr_set()
Concurrency
Thread-safe and wait-free
Parameters
[in]nodeNode handle
[in]attribute_numAttribute id
[out]attributePointer to attribute value
[in]attribute_sizeSize of attribute value
[out]statusPointer 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.
See also
mtapi_initialize(), mtapi_task_cancel(), mtapi_task_get()
Concurrency
Not thread-safe
Parameters
[out]statusPointer 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.
Returns
Domain id of local node
Concurrency
Thread-safe and wait-free
Parameters
[out]statusPointer 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.
Returns
Node id of local node
Concurrency
Thread-safe and wait-free
Parameters
[out]statusPointer to error code, may be MTAPI_NULL