/* * Copyright (C) Mellanox Technologies Ltd. 2001-2014. ALL RIGHTS RESERVED. * Copyright (C) UT-Battelle, LLC. 2014-2015. ALL RIGHTS RESERVED. * Copyright (C) IBM 2015. ALL RIGHTS RESERVED. * Copyright (C) Los Alamos National Security, LLC. 2018. ALL RIGHTS RESERVED. * * See file LICENSE for terms. */ #ifndef UCP_DEF_H_ #define UCP_DEF_H_ #include #include #include #include /** * @ingroup UCP_CONTEXT * @brief UCP receive information descriptor * * The UCP receive information descriptor is allocated by application and filled * in with the information about the received message by @ref ucp_tag_probe_nb * or @ref ucp_tag_recv_request_test routines or * @ref ucp_tag_recv_callback_t callback argument. */ typedef struct ucp_tag_recv_info ucp_tag_recv_info_t; /** * @ingroup UCP_CONTEXT * @brief UCP Application Context * * UCP application context (or just a context) is an opaque handle that holds a * UCP communication instance's global information. It represents a single UCP * communication instance. The communication instance could be an OS process * (an application) that uses UCP library. This global information includes * communication resources, endpoints, memory, temporary file storage, and * other communication information directly associated with a specific UCP * instance. The context also acts as an isolation mechanism, allowing * resources associated with the context to manage multiple concurrent * communication instances. For example, users using both MPI and OpenSHMEM * sessions simultaneously can isolate their communication by allocating and * using separate contexts for each of them. Alternatively, users can share the * communication resources (memory, network resource context, etc.) between * them by using the same application context. A message sent or a RMA * operation performed in one application context cannot be received in any * other application context. */ typedef struct ucp_context *ucp_context_h; /** * @ingroup UCP_CONFIG * @brief UCP configuration descriptor * * This descriptor defines the configuration for @ref ucp_context_h * "UCP application context". The configuration is loaded from the run-time * environment (using configuration files of environment variables) * using @ref ucp_config_read "ucp_config_read" routine and can be printed * using @ref ucp_config_print "ucp_config_print" routine. In addition, * application is responsible to release the descriptor using * @ref ucp_config_release "ucp_config_release" routine. * * @todo This structure will be modified through a dedicated function. */ typedef struct ucp_config ucp_config_t; /** * @ingroup UCP_ENDPOINT * @brief UCP Endpoint * * The endpoint handle is an opaque object that is used to address a remote * @ref ucp_worker_h "worker". It typically provides a description of source, * destination, or both. All UCP communication routines address a destination * with the endpoint handle. The endpoint handle is associated with only one * @ref ucp_context_h "UCP context". UCP provides the @ref ucp_ep_create * "endpoint create" routine to create the endpoint handle and the @ref * ucp_ep_destroy "destroy" routine to destroy the endpoint handle. */ typedef struct ucp_ep *ucp_ep_h; /** * @ingroup UCP_ENDPOINT * @brief UCP connection request * * A server-side handle to incoming connection request. Can be used to create an * endpoint which connects back to the client. */ typedef struct ucp_conn_request *ucp_conn_request_h; /** * @ingroup UCP_WORKER * @brief UCP worker address * * The address handle is an opaque object that is used as an identifier for a * @ref ucp_worker_h "worker" instance. */ typedef struct ucp_address ucp_address_t; /** * @ingroup UCP_ENDPOINT * @brief Error handling mode for the UCP endpoint. * * Specifies error handling mode for the UCP endpoint. */ typedef enum { UCP_ERR_HANDLING_MODE_NONE, /**< No guarantees about error * reporting, imposes minimal * overhead from a performance * perspective. @note In this * mode, any error reporting will * not generate calls to @ref * ucp_ep_params_t::err_handler. */ UCP_ERR_HANDLING_MODE_PEER /**< Guarantees that send requests * are always completed * (successfully or error) even in * case of remote failure, disables * protocols and APIs which may * cause a hang or undefined * behavior in case of peer failure, * may affect performance and * memory footprint */ } ucp_err_handling_mode_t; /** * @ingroup UCP_MEM * @brief UCP Remote memory handle * * Remote memory handle is an opaque object representing remote memory access * information. Typically, the handle includes a memory access key and other * network hardware specific information, which are input to remote memory * access operations, such as PUT, GET, and ATOMIC. The object is * communicated to remote peers to enable an access to the memory region. */ typedef struct ucp_rkey *ucp_rkey_h; /** * @ingroup UCP_MEM * @brief UCP Memory handle * * Memory handle is an opaque object representing a memory region allocated * through UCP library, which is optimized for remote memory access * operations (zero-copy operations). The memory handle is a self-contained * object, which includes the information required to access the memory region * locally, while @ref ucp_rkey_h "remote key" is used to access it * remotely. The memory could be registered to one or multiple network resources * that are supported by UCP, such as InfiniBand, Gemini, and others. */ typedef struct ucp_mem *ucp_mem_h; /** * @ingroup UCP_WORKER * @brief UCP listen handle. * * The listener handle is an opaque object that is used for listening on a * specific address and accepting connections from clients. */ typedef struct ucp_listener *ucp_listener_h; /** * @ingroup UCP_MEM * @brief Attributes of the @ref ucp_mem_h "UCP Memory handle", filled by * @ref ucp_mem_query function. */ typedef struct ucp_mem_attr { /** * Mask of valid fields in this structure, using bits from @ref ucp_mem_attr_field. * Fields not specified in this mask will be ignored. * Provides ABI compatibility with respect to adding new fields. */ uint64_t field_mask; /** * Address of the memory segment. */ void *address; /** * Size of the memory segment. */ size_t length; } ucp_mem_attr_t; /** * @ingroup UCP_MEM * @brief UCP Memory handle attributes field mask. * * The enumeration allows specifying which fields in @ref ucp_mem_attr_t are * present. It is used to enable backward compatibility support. */ enum ucp_mem_attr_field { UCP_MEM_ATTR_FIELD_ADDRESS = UCS_BIT(0), /**< Virtual address */ UCP_MEM_ATTR_FIELD_LENGTH = UCS_BIT(1) /**< The size of memory region */ }; /** * @ingroup UCP_WORKER * @brief UCP Worker * * UCP worker is an opaque object representing the communication context. The * worker represents an instance of a local communication resource and the * progress engine associated with it. The progress engine is a construct that * is responsible for asynchronous and independent progress of communication * directives. The progress engine could be implemented in hardware or software. * The worker object abstracts an instance of network resources such as a host * channel adapter port, network interface, or multiple resources such as * multiple network interfaces or communication ports. It could also represent * virtual communication resources that are defined across multiple devices. * Although the worker can represent multiple network resources, it is * associated with a single @ref ucp_context_h "UCX application context". * All communication functions require a context to perform the operation on * the dedicated hardware resource(s) and an @ref ucp_ep_h "endpoint" to address the * destination. * * @note Worker are parallel "threading points" that an upper layer may use to * optimize concurrent communications. */ typedef struct ucp_worker *ucp_worker_h; /** * @ingroup UCP_COMM * @brief UCP Tag Identifier * * UCP tag identifier is a 64bit object used for message identification. * UCP tag send and receive operations use the object for an implementation * tag matching semantics (derivative of MPI tag matching semantics). */ typedef uint64_t ucp_tag_t; /** * @ingroup UCP_COMM * @brief UCP Message descriptor. * * UCP Message descriptor is an opaque handle for a message returned by * @ref ucp_tag_probe_nb. This handle can be passed to @ref ucp_tag_msg_recv_nb * in order to receive the message data to a specific buffer. */ typedef struct ucp_recv_desc *ucp_tag_message_h; /** * @ingroup UCP_COMM * @brief UCP Datatype Identifier * * UCP datatype identifier is a 64bit object used for datatype identification. * Predefined UCP identifiers are defined by @ref ucp_dt_type. */ typedef uint64_t ucp_datatype_t; /** * @ingroup UCP_CONTEXT * @brief Request initialization callback. * * This callback routine is responsible for the request initialization. * * @param [in] request Request handle to initialize. */ typedef void (*ucp_request_init_callback_t)(void *request); /** * @ingroup UCP_CONTEXT * @brief Request cleanup callback. * * This callback routine is responsible for cleanup of the memory * associated with the request. * * @param [in] request Request handle to cleanup. */ typedef void (*ucp_request_cleanup_callback_t)(void *request); /** * @ingroup UCP_COMM * @brief Completion callback for non-blocking sends. * * This callback routine is invoked whenever the @ref ucp_tag_send_nb * "send operation" is completed. It is important to note that the call-back is * only invoked in a case when the operation cannot be completed in place. * * @param [in] request The completed send request. * @param [in] status Completion status. If the send operation was completed * successfully UCS_OK is returned. If send operation was * canceled UCS_ERR_CANCELED is returned. * Otherwise, an @ref ucs_status_t "error status" is * returned. */ typedef void (*ucp_send_callback_t)(void *request, ucs_status_t status); /** * @ingroup UCP_COMM * @brief Callback to process peer failure. * * This callback routine is invoked when transport level error detected. * * @param [in] arg User argument to be passed to the callback. * @param [in] ep Endpoint to handle transport level error. Upon return * from the callback, this @a ep is no longer usable and * all subsequent operations on this @a ep will fail with * the error code passed in @a status. * @param [in] status @ref ucs_status_t "error status". */ typedef void (*ucp_err_handler_cb_t)(void *arg, ucp_ep_h ep, ucs_status_t status); /** * @ingroup UCP_COMM * @brief UCP endpoint error handling context. * * This structure should be initialized in @ref ucp_ep_params_t to handle peer failure */ typedef struct ucp_err_handler { ucp_err_handler_cb_t cb; /**< Error handler callback, if NULL, will not be called. */ void *arg; /**< User defined argument associated with an endpoint, it will be overridden by @ref ucp_ep_params_t::user_data if both are set. */ } ucp_err_handler_t; /** * @ingroup UCP_WORKER * @brief A callback for accepting client/server connections on a listener * @ref ucp_listener_h. * * This callback routine is invoked on the server side upon creating a connection * to a remote client. The user can pass an argument to this callback. * The user is responsible for releasing the @a ep handle using the * @ref ucp_ep_destroy "ucp_ep_destroy()" routine. * * @param [in] ep Handle to a newly created endpoint which is connected * to the remote peer which has initiated the connection. * @param [in] arg User's argument for the callback. */ typedef void (*ucp_listener_accept_callback_t)(ucp_ep_h ep, void *arg); /** * @ingroup UCP_WORKER * @brief A callback for handling of incoming connection request @a conn_request * from a client. * * This callback routine is invoked on the server side to handle incoming * connections from remote clients. The user can pass an argument to this * callback. The @a conn_request handle has to be released, either by @ref * ucp_ep_create or @ref ucp_listener_reject routine. * * @param [in] conn_request Connection request handle. * @param [in] arg User's argument for the callback. */ typedef void (*ucp_listener_conn_callback_t)(ucp_conn_request_h conn_request, void *arg); /** * @ingroup UCP_WORKER * @brief UCP callback to handle the connection request in a client-server * connection establishment flow. * * This structure is used for handling an incoming connection request on * the listener. Setting this type of handler allows creating an endpoint on * any other worker and not limited to the worker on which the listener was * created. * @note * - Other than communication progress routines, it is allowed to call all * other communication routines from the callback in the struct. * - The callback is thread safe with respect to the worker it is invoked on. * - It is the user's responsibility to avoid potential dead lock accessing * different worker. */ typedef struct ucp_listener_conn_handler { ucp_listener_conn_callback_t cb; /**< Connection request callback */ void *arg; /**< User defined argument for the callback */ } ucp_listener_conn_handler_t; /** * @ingroup UCP_COMM * @brief Completion callback for non-blocking stream oriented receives. * * This callback routine is invoked whenever the @ref ucp_stream_recv_nb * "receive operation" is completed and the data is ready in the receive buffer. * * @param [in] request The completed receive request. * @param [in] status Completion status. If the send operation was completed * successfully UCS_OK is returned. Otherwise, * an @ref ucs_status_t "error status" is returned. * @param [in] length The size of the received data in bytes, always * boundary of base datatype size. The value is valid * only if the status is UCS_OK. */ typedef void (*ucp_stream_recv_callback_t)(void *request, ucs_status_t status, size_t length); /** * @ingroup UCP_COMM * @brief Completion callback for non-blocking tag receives. * * This callback routine is invoked whenever the @ref ucp_tag_recv_nb * "receive operation" is completed and the data is ready in the receive buffer. * * @param [in] request The completed receive request. * @param [in] status Completion status. If the send operation was completed * successfully UCS_OK is returned. If send operation was * canceled UCS_ERR_CANCELED is returned. If the data can * not fit into the receive buffer the * @ref UCS_ERR_MESSAGE_TRUNCATED error code is returned. * Otherwise, an @ref ucs_status_t "error status" is * returned. * @param [in] info @ref ucp_tag_recv_info_t "Completion information" * The @a info descriptor is Valid only if the status is * UCS_OK. */ typedef void (*ucp_tag_recv_callback_t)(void *request, ucs_status_t status, ucp_tag_recv_info_t *info); /** * @ingroup UCP_WORKER * @brief UCP worker wakeup events mask. * * The enumeration allows specifying which events are expected on wakeup. Empty * events are possible for any type of event except for @ref UCP_WAKEUP_TX and * @ref UCP_WAKEUP_RX. * * @note Send completions are reported by POLLIN-like events (see poll man * page). Since outgoing operations can be initiated at any time, UCP does not * generate POLLOUT-like events, although it must be noted that outgoing * operations may be queued depending upon resource availability. */ typedef enum ucp_wakeup_event_types { UCP_WAKEUP_RMA = UCS_BIT(0), /**< Remote memory access send completion */ UCP_WAKEUP_AMO = UCS_BIT(1), /**< Atomic operation send completion */ UCP_WAKEUP_TAG_SEND = UCS_BIT(2), /**< Tag send completion */ UCP_WAKEUP_TAG_RECV = UCS_BIT(3), /**< Tag receive completion */ UCP_WAKEUP_TX = UCS_BIT(10),/**< This event type will generate an event on completion of any outgoing operation (complete or partial, according to the underlying protocol) for any type of transfer (send, atomic, or RMA). */ UCP_WAKEUP_RX = UCS_BIT(11),/**< This event type will generate an event on completion of any receive operation (complete or partial, according to the underlying protocol). */ UCP_WAKEUP_EDGE = UCS_BIT(16) /**< Use edge-triggered wakeup. The event file descriptor will be signaled only for new events, rather than existing ones. */ } ucp_wakeup_event_t; /** * @ingroup UCP_ENDPOINT * @brief Callback to process incoming Active Message. * * When the callback is called, @a flags indicates how @a data should be handled. * * @param [in] arg User-defined argument. * @param [in] data Points to the received data. This data may * persist after the callback returns and needs * to be freed with @ref ucp_am_data_release. * @param [in] length Length of data. * @param [in] reply_ep If the Active Message is sent with the * UCP_AM_SEND_REPLY flag, the sending ep * will be passed in. If not, NULL will be passed. * @param [in] flags If this flag is set to UCP_CB_PARAM_FLAG_DATA, * the callback can return UCS_INPROGRESS and * data will persist after the callback returns. * * @return UCS_OK @a data will not persist after the callback returns. * * @return UCS_INPROGRESS Can only be returned if flags is set to * UCP_CB_PARAM_FLAG_DATA. If UCP_INPROGRESS * is returned, data will persist after the * callback has returned. To free the memory, * a pointer to the data must be passed into * @ref ucp_am_data_release. * * @note This callback should be set and released * by @ref ucp_worker_set_am_handler function. * */ typedef ucs_status_t (*ucp_am_callback_t)(void *arg, void *data, size_t length, ucp_ep_h reply_ep, unsigned flags); /** * @ingroup UCP_ENDPOINT * @brief Tuning parameters for the UCP endpoint. * * The structure defines the parameters that are used for the * UCP endpoint tuning during the UCP ep @ref ucp_ep_create "creation". */ typedef struct ucp_ep_params { /** * Mask of valid fields in this structure, using bits from * @ref ucp_ep_params_field. * Fields not specified in this mask will be ignored. * Provides ABI compatibility with respect to adding new fields. */ uint64_t field_mask; /** * Destination address; this field should be set along with its * corresponding bit in the field_mask - @ref * UCP_EP_PARAM_FIELD_REMOTE_ADDRESS and must be obtained using @ref * ucp_worker_get_address. */ const ucp_address_t *address; /** * Desired error handling mode, optional parameter. Default value is * @ref UCP_ERR_HANDLING_MODE_NONE. */ ucp_err_handling_mode_t err_mode; /** * Handler to process transport level failure. */ ucp_err_handler_t err_handler; /** * User data associated with an endpoint. See @ref ucp_stream_poll_ep_t and * @ref ucp_err_handler_t */ void *user_data; /** * Endpoint flags from @ref ucp_ep_params_flags_field. * This value is optional. * If it's not set (along with its corresponding bit in the field_mask - * @ref UCP_EP_PARAM_FIELD_FLAGS), the @ref ucp_ep_create() routine will * consider the flags as set to zero. */ unsigned flags; /** * Destination address in the form of a sockaddr; this field should be set * along with its corresponding bit in the field_mask - @ref * UCP_EP_PARAM_FIELD_SOCK_ADDR and must be obtained from the user, it means * that this type of the endpoint creation is possible only on client side * in client-server connection establishment flow. */ ucs_sock_addr_t sockaddr; /** * Connection request from client; this field should be set along with its * corresponding bit in the field_mask - @ref * UCP_EP_PARAM_FIELD_CONN_REQUEST and must be obtained from @ref * ucp_listener_conn_callback_t, it means that this type of the endpoint * creation is possible only on server side in client-server connection * establishment flow. */ ucp_conn_request_h conn_request; } ucp_ep_params_t; #endif