/* * Copyright (c) 2014-2016, Siemens AG. All rights reserved. * * Redistribution and use in source and binary forms, with or without * modification, are permitted provided that the following conditions are met: * * 1. Redistributions of source code must retain the above copyright notice, * this list of conditions and the following disclaimer. * * 2. Redistributions in binary form must reproduce the above copyright notice, * this list of conditions and the following disclaimer in the documentation * and/or other materials provided with the distribution. * * THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS" * AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE * IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE * ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT HOLDER OR CONTRIBUTORS BE * LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR * CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF * SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS * INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN * CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) * ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE * POSSIBILITY OF SUCH DAMAGE. */ #ifndef EMBB_MTAPI_C_MTAPI_NETWORK_H_ #define EMBB_MTAPI_C_MTAPI_NETWORK_H_ #include #ifdef __cplusplus extern "C" { #endif /** * \defgroup C_MTAPI_NETWORK MTAPI Network Plugin * * \ingroup C_MTAPI_EXT * * Provides functionality to distribute tasks across nodes in a TCP/IP network. */ /** * 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, /**< [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, /**< [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 /**< [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, /**< [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, /**< [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 */ ); #ifdef __cplusplus } #endif #endif // EMBB_MTAPI_C_MTAPI_NETWORK_H_