309 lines
13 KiB
C
309 lines
13 KiB
C
/*
|
||
* Copyright (c) 2013-2020 Intel, Inc. All rights reserved.
|
||
* Copyright (c) 2015 Artem Y. Polyakov <artpol84@gmail.com>.
|
||
* All rights reserved.
|
||
* Copyright (c) 2015 Research Organization for Information Science
|
||
* and Technology (RIST). All rights reserved.
|
||
* Copyright (c) 2023 Nanook Consulting. All rights reserved.
|
||
* $COPYRIGHT$
|
||
*
|
||
* Redistribution and use in source and binary forms, with or without
|
||
* modification, are permitted provided that the following conditions are
|
||
* met:
|
||
*
|
||
* - Redistributions of source code must retain the above copyright
|
||
* notice, this list of conditions and the following disclaimer.
|
||
*
|
||
* - Redistributions in binary form must reproduce the above copyright
|
||
* notice, this list of conditions and the following disclaimer listed
|
||
* in this license in the documentation and/or other materials
|
||
* provided with the distribution.
|
||
*
|
||
* - Neither the name of the copyright holders nor the names of its
|
||
* contributors may be used to endorse or promote products derived from
|
||
* this software without specific prior written permission.
|
||
*
|
||
* The copyright holders provide no reassurances that the source code
|
||
* provided does not infringe any patent, copyright, or any other
|
||
* intellectual property rights of third parties. The copyright holders
|
||
* disclaim any liability to any recipient for claims brought against
|
||
* recipient by any third party for infringement of that parties
|
||
* intellectual property rights.
|
||
*
|
||
* 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
|
||
* OWNER 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.
|
||
*
|
||
* $HEADER$
|
||
*
|
||
* PMIx provides a "function-shipping" approach to support for
|
||
* implementing the server-side of the protocol. This method allows
|
||
* resource managers to implement the server without being burdened
|
||
* with PMIx internal details. Accordingly, each PMIx API is mirrored
|
||
* here in a function call to be provided by the server. When a
|
||
* request is received from the client, the corresponding server function
|
||
* will be called with the information.
|
||
*
|
||
* Any functions not supported by the RM can be indicated by a NULL for
|
||
* the function pointer. Client calls to such functions will have a
|
||
* "not supported" error returned.
|
||
*/
|
||
|
||
#ifndef PMIx_TOOL_API_H
|
||
#define PMIx_TOOL_API_H
|
||
|
||
/* provide access to the rest of the client functions */
|
||
#include <pmix.h>
|
||
#include <pmix_server.h>
|
||
|
||
#if defined(c_plusplus) || defined(__cplusplus)
|
||
extern "C" {
|
||
#endif
|
||
|
||
/**** TOOL INIT/FINALIZE FUNCTIONS ****/
|
||
|
||
/* Initialize the PMIx tool, returning the process identifier assigned
|
||
* to this tool in the provided pmix_proc_t struct.
|
||
*
|
||
* When called the PMIx tool library will check for the required connection
|
||
* information of the local PMIx server and will establish the connection.
|
||
* If the information is not found, or the server connection fails, then
|
||
* an appropriate error constant will be returned.
|
||
*
|
||
* If successful, the function will return PMIX_SUCCESS and will fill the
|
||
* provided structure with the server-assigned namespace and rank of the tool.
|
||
*
|
||
* Note that the PMIx tool library is referenced counted, and so multiple
|
||
* calls to PMIx_tool_init are allowed. Thus, one way to obtain the namespace and
|
||
* rank of the process is to simply call PMIx_tool_init with a non-NULL parameter.
|
||
*
|
||
* The info array is used to pass user requests pertaining to the init
|
||
* and subsequent operations. Passing a _NULL_ value for the array pointer
|
||
* is supported if no directives are desired.
|
||
*/
|
||
PMIX_EXPORT pmix_status_t PMIx_tool_init(pmix_proc_t *proc,
|
||
pmix_info_t info[], size_t ninfo);
|
||
|
||
/* Provide an entry point by which a tool can provide a server function
|
||
* pointer module.
|
||
*/
|
||
PMIX_EXPORT pmix_status_t PMIx_tool_set_server_module(pmix_server_module_t *module);
|
||
|
||
/* Finalize the PMIx tool library, closing the connection to the local server.
|
||
* An error code will be returned if, for some reason, the connection
|
||
* cannot be closed.
|
||
*
|
||
* The info array is used to pass user requests regarding the finalize
|
||
* operation. */
|
||
PMIX_EXPORT pmix_status_t PMIx_tool_finalize(void);
|
||
|
||
/* Check if the tool is connected to a PMIx server */
|
||
PMIX_EXPORT bool PMIx_tool_is_connected(void);
|
||
|
||
/* Establish a connection to a PMIx server. The target server can
|
||
* be given as:
|
||
*
|
||
* - PMIX_CONNECT_TO_SYSTEM: connect solely to the system server
|
||
*
|
||
* - PMIX_CONNECT_SYSTEM_FIRST: a request to use the system server first,
|
||
* if existing, and then look for the server specified in a different
|
||
* attribute
|
||
*
|
||
* - PMIX_SERVER_URI: connect to the server at the given URI
|
||
*
|
||
* - PMIX_SERVER_NSPACE: connect to the server of a given nspace
|
||
*
|
||
* - PMIX_SERVER_PIDINFO: connect to a server embedded in the process with
|
||
* the given pid
|
||
*
|
||
* Passing a _NULL_ value for the info array pointer is not allowed and will
|
||
* result in return of an error.
|
||
*
|
||
* NOTE: PMIx does not currently support on-the-fly changes to the tool's
|
||
* identifier. Thus, the new server must be under the same nspace manager
|
||
* (e.g., host RM) as the prior server so that the original nspace remains
|
||
* a unique assignment. The proc parameter is included here for obsolence
|
||
* protection in case this constraint is someday removed. Meantime, the
|
||
* proc parameter will be filled with the tool's existing nspace/rank, and
|
||
* the caller is welcome to pass _NULL_ in that location
|
||
*/
|
||
/* REPLACES CONNECT_TO_SERVER, ADDING ABILITY TO RETURN
|
||
* IDENTIFIER OF SERVER TO WHICH TOOL ATTACHED
|
||
*/
|
||
PMIX_EXPORT pmix_status_t PMIx_tool_attach_to_server(pmix_proc_t *myproc, pmix_proc_t *server,
|
||
pmix_info_t info[], size_t ninfo);
|
||
|
||
|
||
/* Disconnect the PMIx tool from the specified server connection while
|
||
* leaving the tool library initialized.
|
||
*
|
||
* server - Process identifier of the server from which the tool is
|
||
* to be disconnected
|
||
*
|
||
* Returns PMIX_SUCCESS or a PMIx error constant
|
||
*/
|
||
PMIX_EXPORT pmix_status_t PMIx_tool_disconnect(const pmix_proc_t *server);
|
||
|
||
|
||
/* Get an array containing the pmix_proc_t process identifiers of all
|
||
* servers to which the tool is currently connected.
|
||
*
|
||
* servers - Address where the pointer to an array of pmix_proc_t
|
||
* structures shall be returned
|
||
*
|
||
* nservers - Address where the number of elements in servers
|
||
* shall be returned
|
||
*
|
||
* Returns PMIX_SUCCESS or a PMIx error constant
|
||
*/
|
||
PMIX_EXPORT pmix_status_t PMIx_tool_get_servers(pmix_proc_t *servers[], size_t *nservers);
|
||
|
||
|
||
/* Designate a server as the tool’s primary server.
|
||
*
|
||
* server - Process identifier of the target server
|
||
*
|
||
* Returns PMIX_SUCCESS or a PMIx error constant
|
||
*/
|
||
PMIX_EXPORT pmix_status_t PMIx_tool_set_server(const pmix_proc_t *server,
|
||
pmix_info_t info[], size_t ninfo);
|
||
|
||
|
||
/* Define a callback function for delivering forwarded IO to a process
|
||
* This function will be called whenever data becomes available, or a
|
||
* specified buffering size and/or time has been met. The function
|
||
* will be passed the following values:
|
||
*
|
||
* iofhdlr - the returned registration number of the handler being invoked.
|
||
* This is required when deregistering the handler.
|
||
*
|
||
* channel - a bitmask identifying the channel the data arrived on
|
||
*
|
||
* source - the nspace/rank of the process that generated the data
|
||
*
|
||
* payload - pointer to a PMIx byte object containing the data. Note that
|
||
* multiple strings may be included, and that the data may
|
||
* _not_ be NULL terminated
|
||
*
|
||
* info - an optional array of info provided by the source containing
|
||
* metadata about the payload. This could include PMIX_IOF_COMPLETE
|
||
*
|
||
* ninfo - number of elements in the optional info array
|
||
*/
|
||
typedef void (*pmix_iof_cbfunc_t)(size_t iofhdlr, pmix_iof_channel_t channel,
|
||
pmix_proc_t *source, pmix_byte_object_t *payload,
|
||
pmix_info_t info[], size_t ninfo);
|
||
|
||
|
||
/* Register to receive output forwarded from a remote process.
|
||
*
|
||
* procs - array of identifiers for sources whose IO is being
|
||
* requested. Wildcard rank indicates that all procs
|
||
* in the specified nspace are included in the request
|
||
*
|
||
* nprocs - number of identifiers in the procs array
|
||
*
|
||
* directives - optional array of attributes to control the
|
||
* behavior of the request. For example, this
|
||
* might include directives on buffering IO
|
||
* before delivery, and/or directives to include
|
||
* or exclude any backlogged data
|
||
*
|
||
* ndirs - number of elements in the directives array
|
||
*
|
||
* channel - bitmask of IO channels included in the request.
|
||
* NOTE: STDIN is not supported as it will always
|
||
* be delivered to the stdin file descriptor
|
||
*
|
||
* cbfunc - function to be called when relevant IO is received. A
|
||
* NULL indicates that the IO is to be written to stdout
|
||
* or stderr as per the originating channel
|
||
*
|
||
* regcbfunc - since registration is async, this is the
|
||
* function to be called when registration is
|
||
* completed. The function itself will return
|
||
* a non-success error if the registration cannot
|
||
* be submitted - in this case, the regcbfunc
|
||
* will _not_ be called.
|
||
* If regcbfunc is NULL, then this will be treated
|
||
* as a BLOCKING call - a positive return value
|
||
* represents the reference ID for the request,
|
||
* while negative values indicate the corresponding
|
||
* error
|
||
*
|
||
* cbdata - pointer to object to be returned in regcbfunc
|
||
*/
|
||
PMIX_EXPORT pmix_status_t PMIx_IOF_pull(const pmix_proc_t procs[], size_t nprocs,
|
||
const pmix_info_t directives[], size_t ndirs,
|
||
pmix_iof_channel_t channel, pmix_iof_cbfunc_t cbfunc,
|
||
pmix_hdlr_reg_cbfunc_t regcbfunc, void *regcbdata);
|
||
|
||
/* Deregister from output forwarded from a remote process.
|
||
*
|
||
* iofhdlr - the registration number returned from the
|
||
* call to PMIx_IOF_pull
|
||
*
|
||
* directives - optional array of attributes to control the
|
||
* behavior of the request. For example, this
|
||
* might include directives regarding what to
|
||
* do with any data currently in the IO buffer
|
||
* for this process
|
||
*
|
||
* cbfunc - function to be called when deregistration has
|
||
* been completed. Note that any IO to be flushed
|
||
* may continue to be received after deregistration
|
||
* has completed. If cbfunc is NULL, then this is
|
||
* treated as a BLOCKING call and the result of
|
||
* the operation will be provided in the returned status
|
||
*
|
||
* cbdata - pointer to object to be returned in cbfunc
|
||
*/
|
||
PMIX_EXPORT pmix_status_t PMIx_IOF_deregister(size_t iofhdlr,
|
||
const pmix_info_t directives[], size_t ndirs,
|
||
pmix_op_cbfunc_t cbfunc, void *cbdata);
|
||
|
||
/* Push data collected locally (typically from stdin) to
|
||
* stdin of target recipients.
|
||
*
|
||
* targets - array of process identifiers to which the data is to be delivered. Note
|
||
* that a WILDCARD rank indicates that all procs in the given nspace are
|
||
* to receive a copy of the data
|
||
*
|
||
* ntargets - number of procs in the targets array
|
||
*
|
||
* directives - optional array of attributes to control the
|
||
* behavior of the request. For example, this
|
||
* might include directives on buffering IO
|
||
* before delivery, and/or directives to include
|
||
* or exclude any backlogged data
|
||
*
|
||
* ndirs - number of elements in the directives array
|
||
*
|
||
* bo - pointer to a byte object containing the stdin data
|
||
*
|
||
* cbfunc - callback function when the data has been forwarded. If
|
||
* cbfunc is NULL, then this is treated as a BLOCKING call
|
||
* and the result of the operation will be provided in the
|
||
* returned status
|
||
*
|
||
* cbdata - object to be returned in cbfunc
|
||
*/
|
||
PMIX_EXPORT pmix_status_t PMIx_IOF_push(const pmix_proc_t targets[], size_t ntargets,
|
||
pmix_byte_object_t *bo,
|
||
const pmix_info_t directives[], size_t ndirs,
|
||
pmix_op_cbfunc_t cbfunc, void *cbdata);
|
||
|
||
#if defined(c_plusplus) || defined(__cplusplus)
|
||
}
|
||
#endif
|
||
|
||
#endif
|