Embedded Multicore Building Blocks V1.0.0
Functions
MTAPI Network Plugin

Provides functionality to distribute tasks across nodes in a TCP/IP network. More...

Functions

void mtapi_network_plugin_initialize (MTAPI_IN char *host, MTAPI_IN mtapi_uint16_t port, MTAPI_IN mtapi_uint16_t max_connections, MTAPI_IN mtapi_size_t buffer_size, MTAPI_OUT mtapi_status_t *status)
 Initializes the MTAPI network environment on a previously initialized MTAPI node. More...
 
void mtapi_network_plugin_finalize (MTAPI_OUT mtapi_status_t *status)
 Finalizes the MTAPI network environment on the local MTAPI node. More...
 
mtapi_action_hndl_t mtapi_network_action_create (MTAPI_IN mtapi_domain_t domain_id, MTAPI_IN mtapi_job_id_t local_job_id, MTAPI_IN mtapi_job_id_t remote_job_id, MTAPI_IN char *host, MTAPI_IN mtapi_uint16_t port, MTAPI_OUT mtapi_status_t *status)
 This function creates a network action. More...
 

Detailed Description

Provides functionality to distribute tasks across nodes in a TCP/IP network.

Function Documentation

void mtapi_network_plugin_initialize ( MTAPI_IN char *  host,
MTAPI_IN mtapi_uint16_t  port,
MTAPI_IN mtapi_uint16_t  max_connections,
MTAPI_IN mtapi_size_t  buffer_size,
MTAPI_OUT mtapi_status_t *  status 
)

Initializes the MTAPI network environment on a previously initialized MTAPI node.

It must be called on all nodes using the MTAPI network plugin.

Application software using MTAPI network must call mtapi_network_plugin_initialize() once per node. It is an error to call mtapi_network_plugin_initialize() multiple times from a given node, unless mtapi_network_plugin_finalize() is called in between.

On success, *status is set to MTAPI_SUCCESS. On error, *status is set to the appropriate error defined below.

Error code Description
MTAPI_ERR_UNKNOWN MTAPI network couldn't be initialized.
See also
mtapi_network_plugin_finalize()
Concurrency
Not thread-safe
Parameters
[in]hostThe interface to listen on, if MTAPI_NULL is given the plugin will listen on all available interfaces.
[in]portThe port to listen on.
[in]max_connectionsMaximum concurrent connections accepted by the plugin.
[in]buffer_sizeCapacity of the transfer buffers, this should be chosen big enough to hold argument and result buffers.
[out]statusPointer to error code, may be MTAPI_NULL
void mtapi_network_plugin_finalize ( MTAPI_OUT mtapi_status_t *  status)

Finalizes the MTAPI network environment on the local MTAPI node.

It has to be called by each node using MTAPI network. It is an error to call mtapi_network_plugin_finalize() without first calling mtapi_network_plugin_initialize(). An MTAPI node can call mtapi_network_plugin_finalize() once for each call to mtapi_network_plugin_initialize(), but it is an error to call mtapi_network_plugin_finalize() multiple times from a given node unless mtapi_network_plugin_initialize() has been called prior to each mtapi_network_plugin_finalize() call.

All network tasks that have not completed and that have been started on the node where mtapi_network_plugin_finalize() is called will be canceled (see mtapi_task_cancel()). mtapi_network_plugin_finalize() blocks until all tasks that have been started on the same node return. Tasks that execute actions on the node where mtapi_network_plugin_finalize() is called, also block finalization of the MTAPI network system on that 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_UNKNOWN MTAPI network couldn't be finalized.
See also
mtapi_network_plugin_initialize(), mtapi_task_cancel()
Concurrency
Not thread-safe
Parameters
[out]statusPointer to error code, may be MTAPI_NULL
mtapi_action_hndl_t mtapi_network_action_create ( MTAPI_IN mtapi_domain_t  domain_id,
MTAPI_IN mtapi_job_id_t  local_job_id,
MTAPI_IN mtapi_job_id_t  remote_job_id,
MTAPI_IN char *  host,
MTAPI_IN mtapi_uint16_t  port,
MTAPI_OUT mtapi_status_t *  status 
)

This function creates a network action.

It is called on the node where the user wants to execute an action on a remote node where the actual action is implemented. A network action contains a reference to a local job, a remote job and a remote domain as well as a host and port to connect to. After a network action is created, it is referenced by the application using a node-local handle of type mtapi_action_hndl_t, or indirectly through a node-local job handle of type mtapi_job_hndl_t. A network action's life-cycle begins with mtapi_network_action_create(), and ends when mtapi_action_delete() or mtapi_finalize() is called.

To create an action, the application must supply the domain-wide job ID of the job associated with the action. Job IDs must be predefined in the application and runtime, of type mtapi_job_id_t, which is an implementation-defined type. The job ID is unique in the sense that it is unique for the job implemented by the action. However several actions may implement the same job for load balancing purposes.

A network action defines no node local data, instead the node local data of the remote action is used. The user has to make sure that the remote node local data matches what he expects the remote action to use if invoked through the network.

On success, an action handle is returned and *status is set to MTAPI_SUCCESS. On error, *status is set to the appropriate error defined below. In the case where the action already exists, status will be set to MTAPI_ERR_ACTION_EXISTS and the handle returned will not be a valid handle.

Error code Description
MTAPI_ERR_JOB_INVALID The job_id is not a valid job ID, i.e., no action was created for that ID or the action has been deleted.
MTAPI_ERR_ACTION_EXISTS This action is already created.
MTAPI_ERR_ACTION_LIMIT Exceeded maximum number of actions allowed.
MTAPI_ERR_NODE_NOTINIT The calling node is not initialized.
MTAPI_ERR_UNKNOWN The remote node could not be reached or there was no local interface available.
See also
mtapi_action_delete(), mtapi_finalize()
Returns
Handle to newly created network action, invalid handle on error
Concurrency
Thread-safe
Parameters
[in]domain_idThe domain the action is associated with
[in]local_job_idThe ID of the local job
[in]remote_job_idThe ID of the remote job
[in]hostThe host to connect to
[in]portThe port the host is listening on
[out]statusPointer to error code, may be MTAPI_NULL