diff --git a/mtapi_network_c/include/embb/mtapi/c/mtapi_network.h b/mtapi_network_c/include/embb/mtapi/c/mtapi_network.h index f0a6fd4..8f45178 100644 --- a/mtapi_network_c/include/embb/mtapi/c/mtapi_network.h +++ b/mtapi_network_c/include/embb/mtapi/c/mtapi_network.h @@ -36,25 +36,167 @@ extern "C" { #endif +/** + * \defgroup C_MTAPI_NETWORK MTAPI Network Plugin + * + * \ingroup C_MTAPI_EXT + * + * + */ + + +/** + * 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, \c *status is set to \c MTAPI_SUCCESS. On error, \c *status is + * set to the appropriate error defined below. + * Error code | Description + * --------------------------- | ---------------------------------------------- + * \c MTAPI_ERR_UNKNOWN | MTAPI network couldn't be initialized. + * + * \see mtapi_network_plugin_finalize() + * + * \notthreadsafe + * \ingroup C_MTAPI_NETWORK + */ void mtapi_network_plugin_initialize( - MTAPI_IN char * host, - MTAPI_IN mtapi_uint16_t port, + MTAPI_IN char * host, /**< [in] The interface to listen on, if + MTAPI_NULL is given the plugin will + listen on all available + interfaces. */ + MTAPI_IN mtapi_uint16_t port, /**< [in] The port to listen on. */ MTAPI_IN mtapi_uint16_t max_connections, - MTAPI_IN mtapi_size_t buffer_size, - MTAPI_OUT mtapi_status_t* status + /**< [in] Maximum concurrent connections + accepted by the plugin. */ + MTAPI_IN mtapi_size_t buffer_size, /**< [in] Capacity of the transfer + buffers, this should be chosen big + enough to hold argument and result + buffers.*/ + MTAPI_OUT mtapi_status_t* status /**< [out] Pointer to error code, + may be \c MTAPI_NULL */ ); +/** + * 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, \c *status is set to \c MTAPI_SUCCESS. On error, \c *status is + * set to the appropriate error defined below. + * Error code | Description + * ----------------------------- | -------------------------------------------- + * \c MTAPI_ERR_UNKNOWN | MTAPI network couldn't be finalized. + * + * \see mtapi_network_plugin_initialize(), mtapi_task_cancel() + * + * \notthreadsafe + * \ingroup C_MTAPI_NETWORK + */ void mtapi_network_plugin_finalize( - MTAPI_OUT mtapi_status_t* status + MTAPI_OUT mtapi_status_t* status /**< [out] Pointer to error code, + may be \c MTAPI_NULL */ ); +/** + * 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 \c mtapi_action_hndl_t, or indirectly through a + * node-local job handle of type \c 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 \c 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 \c *status is set to + * \c MTAPI_SUCCESS. On error, \c *status is set to the appropriate error + * defined below. In the case where the action already exists, \c status will + * be set to \c MTAPI_ERR_ACTION_EXISTS and the handle returned will not be a + * valid handle. + * + * + * + * + * + * + * + * + * + * + * + * + * + * + * + * + * + * + * + * + * + * + * + * + * + *
Error codeDescription
\c MTAPI_ERR_JOB_INVALIDThe \c job_id is not a valid job ID, i.e., no action was created for + * that ID or the action has been deleted.
\c MTAPI_ERR_ACTION_EXISTSThis action is already created.
\c MTAPI_ERR_ACTION_LIMITExceeded maximum number of actions allowed.
\c MTAPI_ERR_NODE_NOTINITThe calling node is not initialized.
\c MTAPI_ERR_UNKNOWNThe remote node could not be reached or there was no local + * interface available.
+ * + * \see mtapi_action_delete(), mtapi_finalize() + * + * \returns Handle to newly created network action, invalid handle on error + * \threadsafe + * \ingroup C_MTAPI_NETWORK + */ mtapi_action_hndl_t mtapi_network_action_create( - MTAPI_IN mtapi_domain_t domain_id, + MTAPI_IN mtapi_domain_t domain_id, /**< [in] The domain the action is + associated with */ MTAPI_IN mtapi_job_id_t local_job_id, + /**< [in] The ID of the local job */ 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 + /**< [in] The ID of the remote job */ + MTAPI_IN char * host, /**< [in] The host to connect to */ + MTAPI_IN mtapi_uint16_t port, /**< [in] The port the host is listening + on */ + MTAPI_OUT mtapi_status_t* status /**< [out] Pointer to error code, + may be \c MTAPI_NULL */ );