EIC code displayed by LXR master/​include/​pmix_server.h	Source navigation Diff markup Identifier search General search
	Version: master test Revert   Change

File indexing completed on 2025-01-17 09:55:56

 /*
  * 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) 2021-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_SERVER_API_H
 #define PMIx_SERVER_API_H
 
 /* Structure and constant definitions */
 #include <pmix_common.h>
 
 #if defined(c_plusplus) || defined(__cplusplus)
 extern "C" {
 #endif
 
 /****    SERVER FUNCTION-SHIPPED APIs    ****/
 /* NOTE: for performance purposes, the host server is required to
  * return as quickly as possible from all functions. Execution of
  * the function is thus to be done asynchronously so as to allow
  * the PMIx server support library to handle multiple client requests
  * as quickly and scalably as possible.
  *
  * ALL data passed to the host server functions is "owned" by the
  * PMIX server support library and MUST NOT be free'd. Data returned
  * by the host server via callback function is owned by the host
  * server, which is free to release it upon return from the callback */
 
 /* Notify the host server that a client connected to us - note
  * that the client will be in a blocked state until the host server
  * executes the callback function, thus allowing the PMIx server support
  * library to release the client */
 typedef pmix_status_t (*pmix_server_client_connected_fn_t)(const pmix_proc_t *proc, void* server_object,
                                                            pmix_op_cbfunc_t cbfunc, void *cbdata);
 
 /* REPLACES ABOVE FUNCTION TO ALLOW PASSING ADDITIONAL INFO */
 typedef pmix_status_t (*pmix_server_client_connected2_fn_t)(const pmix_proc_t *proc, void* server_object,
                                                             pmix_info_t info[], size_t ninfo,
                                                             pmix_op_cbfunc_t cbfunc, void *cbdata);
 
 
 /* Notify the host server that a client called PMIx_Finalize - note
  * that the client will be in a blocked state until the host server
  * executes the callback function, thus allowing the PMIx server support
  * library to release the client */
 typedef pmix_status_t (*pmix_server_client_finalized_fn_t)(const pmix_proc_t *proc, void* server_object,
                                                            pmix_op_cbfunc_t cbfunc, void *cbdata);
 
 /* A local client called PMIx_Abort - note that the client will be in a blocked
  * state until the host server executes the callback function, thus
  * allowing the PMIx server support library to release the client. The
  * array of procs indicates which processes are to be terminated. A NULL
  * indicates that all procs in the client's nspace are to be terminated */
 typedef pmix_status_t (*pmix_server_abort_fn_t)(const pmix_proc_t *proc, void *server_object,
                                                 int status, const char msg[],
                                                 pmix_proc_t procs[], size_t nprocs,
                                                 pmix_op_cbfunc_t cbfunc, void *cbdata);
 
 /* At least one client called either PMIx_Fence or PMIx_Fence_nb. In either case,
  * the host server will be called via a non-blocking function to execute
  * the specified operation once all participating local procs have
  * contributed. All processes in the specified array are required to participate
  * in the Fence[_nb] operation. The callback is to be executed once each daemon
  * hosting at least one participant has called the host server's fencenb function.
  *
  * The provided data is to be collectively shared with all PMIx
  * servers involved in the fence operation, and returned in the modex
  * cbfunc. A _NULL_ data value indicates that the local procs had
  * no data to contribute.
  *
  * The array of info structs is used to pass user-requested options to the server.
  * This can include directives as to the algorithm to be used to execute the
  * fence operation. The directives are optional _unless_ the _mandatory_ flag
  * has been set - in such cases, the host RM is required to return an error
  * if the directive cannot be met. */
 typedef pmix_status_t (*pmix_server_fencenb_fn_t)(const pmix_proc_t procs[], size_t nprocs,
                                                   const pmix_info_t info[], size_t ninfo,
                                                   char *data, size_t ndata,
                                                   pmix_modex_cbfunc_t cbfunc, void *cbdata);
 
 
 /* Used by the PMIx server to request its local host contact the
  * PMIx server on the remote node that hosts the specified proc to
  * obtain and return a direct modex blob for that proc.
  *
  * The array of info structs is used to pass user-requested options to the server.
  * This can include a timeout to preclude an indefinite wait for data that
  * may never become available. The directives are optional _unless_ the _mandatory_ flag
  * has been set - in such cases, the host RM is required to return an error
  * if the directive cannot be met. */
 typedef pmix_status_t (*pmix_server_dmodex_req_fn_t)(const pmix_proc_t *proc,
                                                      const pmix_info_t info[], size_t ninfo,
                                                      pmix_modex_cbfunc_t cbfunc, void *cbdata);
 
 
 /* Publish data per the PMIx API specification. The callback is to be executed
  * upon completion of the operation. The default data range is expected to be
  * PMIX_SESSION, and the default persistence PMIX_PERSIST_SESSION. These values
  * can be modified by including the respective pmix_info_t struct in the
  * provided array.
  *
  * Note that the host server is not required to guarantee support for any specific
  * range - i.e., the server does not need to return an error if the data store
  * doesn't support range-based isolation. However, the server must return an error
  * (a) if the key is duplicative within the storage range, and (b) if the server
  * does not allow overwriting of published info by the original publisher - it is
  * left to the discretion of the host server to allow info-key-based flags to modify
  * this behavior.
  *
  * The persistence indicates how long the server should retain the data.
  *
  * The identifier of the publishing process is also provided and is expected to
  * be returned on any subsequent lookup request */
 typedef pmix_status_t (*pmix_server_publish_fn_t)(const pmix_proc_t *proc,
                                                   const pmix_info_t info[], size_t ninfo,
                                                   pmix_op_cbfunc_t cbfunc, void *cbdata);
 
 /* Lookup published data. The host server will be passed a NULL-terminated array
  * of string keys.
  *
  * The array of info structs is used to pass user-requested options to the server.
  * This can include a wait flag to indicate that the server should wait for all
  * data to become available before executing the callback function, or should
  * immediately callback with whatever data is available. In addition, a timeout
  * can be specified on the wait to preclude an indefinite wait for data that
  * may never be published. */
 typedef pmix_status_t (*pmix_server_lookup_fn_t)(const pmix_proc_t *proc, char **keys,
                                                  const pmix_info_t info[], size_t ninfo,
                                                  pmix_lookup_cbfunc_t cbfunc, void *cbdata);
 
 /* Delete data from the data store. The host server will be passed a NULL-terminated array
  * of string keys, plus potential directives such as the data range within which the
  * keys should be deleted. The callback is to be executed upon completion of the delete
  * procedure */
 typedef pmix_status_t (*pmix_server_unpublish_fn_t)(const pmix_proc_t *proc, char **keys,
                                                     const pmix_info_t info[], size_t ninfo,
                                                     pmix_op_cbfunc_t cbfunc, void *cbdata);
 
 /* Spawn a set of applications/processes as per the PMIx API. Note that
  * applications are not required to be MPI or any other programming model.
  * Thus, the host server cannot make any assumptions as to their required
  * support. The callback function is to be executed once all processes have
  * been started. An error in starting any application or process in this
  * request shall cause all applications and processes in the request to
  * be terminated, and an error returned to the originating caller.
  *
  * Note that a timeout can be specified in the job_info array to indicate
  * that failure to start the requested job within the given time should
  * result in termination to avoid hangs */
 typedef pmix_status_t (*pmix_server_spawn_fn_t)(const pmix_proc_t *proc,
                                                 const pmix_info_t job_info[], size_t ninfo,
                                                 const pmix_app_t apps[], size_t napps,
                                                 pmix_spawn_cbfunc_t cbfunc, void *cbdata);
 
 /* Record the specified processes as "connected". This means that the resource
  * manager should treat the failure of any process in the specified group as
  * a reportable event, and take appropriate action. The callback function is
  * to be called once all participating processes have called connect. Note that
  * a process can only engage in *one* connect operation involving the identical
  * set of procs at a time. However, a process *can* be simultaneously engaged
  * in multiple connect operations, each involving a different set of procs
  *
  * Note also that this is a collective operation within the client library, and
  * thus the client will be blocked until all procs participate. Thus, the info
  * array can be used to pass user directives, including a timeout.
  * The directives are optional _unless_ the _mandatory_ flag
  * has been set - in such cases, the host RM is required to return an error
  * if the directive cannot be met. */
 typedef pmix_status_t (*pmix_server_connect_fn_t)(const pmix_proc_t procs[], size_t nprocs,
                                                   const pmix_info_t info[], size_t ninfo,
                                                   pmix_op_cbfunc_t cbfunc, void *cbdata);
 
 /* Disconnect a previously connected set of processes. An error should be returned
  * if the specified set of procs was not previously "connected". As above, a process
  * may be involved in multiple simultaneous disconnect operations. However, a process
  * is not allowed to reconnect to a set of ranges that has not fully completed
  * disconnect - i.e., you have to fully disconnect before you can reconnect to the
  * same group of processes.
   *
  * Note also that this is a collective operation within the client library, and
  * thus the client will be blocked until all procs participate. Thus, the info
  * array can be used to pass user directives, including a timeout.
  * The directives are optional _unless_ the _mandatory_ flag
  * has been set - in such cases, the host RM is required to return an error
  * if the directive cannot be met. */
 typedef pmix_status_t (*pmix_server_disconnect_fn_t)(const pmix_proc_t procs[], size_t nprocs,
                                                      const pmix_info_t info[], size_t ninfo,
                                                      pmix_op_cbfunc_t cbfunc, void *cbdata);
 
 /* Register to receive notifications for the specified events. The resource
  * manager is _required_ to pass along to the local PMIx server all events
  * that directly relate to a registered namespace. However, the RM may have
  * access to events beyond those - e.g., environmental events. The PMIx server
  * will register to receive environmental events that match specific PMIx
  * event codes. If the host RM supports such notifications, it will need to
  * translate its own internal event codes to fit into a corresponding PMIx event
  * code - any specific info beyond that can be passed in via the pmix_info_t
  * upon notification.
  *
  * The info array included in this API is reserved for possible future directives
  * to further steer notification.
  */
  typedef pmix_status_t (*pmix_server_register_events_fn_t)(pmix_status_t *codes, size_t ncodes,
                                                            const pmix_info_t info[], size_t ninfo,
                                                            pmix_op_cbfunc_t cbfunc, void *cbdata);
 
 /* Deregister to receive notifications for the specified environmental events
  * for which the PMIx server has previously registered. The host RM remains
  * required to notify of any job-related events */
  typedef pmix_status_t (*pmix_server_deregister_events_fn_t)(pmix_status_t *codes, size_t ncodes,
                                                              pmix_op_cbfunc_t cbfunc, void *cbdata);
 
 /* Notify the specified processes of an event generated either by
  * the PMIx server itself, or by one of its local clients. The process
  * generating the event is provided in the source parameter. */
 typedef pmix_status_t (*pmix_server_notify_event_fn_t)(pmix_status_t code,
                                                        const pmix_proc_t *source,
                                                        pmix_data_range_t range,
                                                        pmix_info_t info[], size_t ninfo,
                                                        pmix_op_cbfunc_t cbfunc, void *cbdata);
 
 /* Callback function for incoming connection requests from
  * local clients */
 typedef void (*pmix_connection_cbfunc_t)(int incoming_sd, void *cbdata);
 
 /* Register a socket the host server can monitor for connection
  * requests, harvest them, and then call our internal callback
  * function for further processing. A listener thread is essential
  * to efficiently harvesting connection requests from large
  * numbers of local clients such as occur when running on large
  * SMPs. The host server listener is required to call accept
  * on the incoming connection request, and then passing the
  * resulting soct to the provided cbfunc. A NULL for this function
  * will cause the internal PMIx server to spawn its own listener
  * thread */
 typedef pmix_status_t (*pmix_server_listener_fn_t)(int listening_sd,
                                                    pmix_connection_cbfunc_t cbfunc,
                                                    void *cbdata);
 
 /* Query information from the resource manager. The query will include
  * the nspace/rank of the proc that is requesting the info, an
  * array of pmix_query_t describing the request, and a callback
  * function/data for the return. */
 typedef pmix_status_t (*pmix_server_query_fn_t)(pmix_proc_t *proct,
                                                 pmix_query_t *queries, size_t nqueries,
                                                 pmix_info_cbfunc_t cbfunc,
                                                 void *cbdata);
 
 /* Callback function for incoming tool connections - the host
  * RM shall provide an nspace/rank for the connecting tool. We
  * assume that a rank=0 will be the normal assignment, but allow
  * for the future possibility of a parallel set of tools
  * connecting, and thus each proc requiring a rank*/
 typedef void (*pmix_tool_connection_cbfunc_t)(pmix_status_t status,
                                               pmix_proc_t *proc, void *cbdata);
 
 /* Register that a tool has connected to the server, and request
  * that the tool be assigned an nspace/rank for further interactions.
  * The optional pmix_info_t array can be used to pass qualifiers for
  * the connection request:
  *
  * (a) PMIX_USERID - effective userid of the tool
  * (b) PMIX_GRPID - effective groupid of the tool
  * (c) PMIX_FWD_STDOUT - forward any stdout to this tool
  * (d) PMIX_FWD_STDERR - forward any stderr to this tool
  * (e) PMIX_FWD_STDIN - forward stdin from this tool to any
  *     processes spawned on its behalf
  */
 typedef void (*pmix_server_tool_connection_fn_t)(pmix_info_t *info, size_t ninfo,
                                                  pmix_tool_connection_cbfunc_t cbfunc,
                                                  void *cbdata);
 
 /* Log data on behalf of a client. Calls to the host thru this
  * function must _NOT_ call the PMIx_Log API as this will
  * trigger an infinite loop. Instead, the implementation must
  * perform one of three operations:
  *
  * (a) transfer the data+directives to a "gateway" server
  *     where they can be logged. Gateways are designated
  *     servers on nodes (typically service nodes) where
  *     centralized logging is supported. The data+directives
  *     may be passed to the PMIx_Log API once arriving at
  *     that destination.
  *
  * (b) transfer the data to a logging channel outside of
  *     PMIx, but directly supported by the host
  *
  * (c) return an error to the caller indicating that the
  *     requested action is not supported
  */
 typedef void (*pmix_server_log_fn_t)(const pmix_proc_t *client,
                                      const pmix_info_t data[], size_t ndata,
                                      const pmix_info_t directives[], size_t ndirs,
                                      pmix_op_cbfunc_t cbfunc, void *cbdata);
 
 /* Request allocation modifications on behalf of a client */
 typedef pmix_status_t (*pmix_server_alloc_fn_t)(const pmix_proc_t *client,
                                                 pmix_alloc_directive_t directive,
                                                 const pmix_info_t data[], size_t ndata,
                                                 pmix_info_cbfunc_t cbfunc, void *cbdata);
 
 /* Execute a job control action on behalf of a client */
 typedef pmix_status_t (*pmix_server_job_control_fn_t)(const pmix_proc_t *requestor,
                                                       const pmix_proc_t targets[], size_t ntargets,
                                                       const pmix_info_t directives[], size_t ndirs,
                                                       pmix_info_cbfunc_t cbfunc, void *cbdata);
 
 /* Request that a client be monitored for activity */
 typedef pmix_status_t (*pmix_server_monitor_fn_t)(const pmix_proc_t *requestor,
                                                   const pmix_info_t *monitor, pmix_status_t error,
                                                   const pmix_info_t directives[], size_t ndirs,
                                                   pmix_info_cbfunc_t cbfunc, void *cbdata);
 
 /* Request a credential from the host SMS
  * Input values include:
  *
  * proc - pointer to a pmix_proc_t identifier of the process on whose behalf
  *        the request is being made (i.e., the client originating the request)
  *
  * directives - an array of pmix_info_t structures containing directives pertaining
  *              to the request. This will typically include any pmix_info_t structs
  *              passed by the requesting client, but may also include directives
  *              required by (or available from) the PMIx server implementation - e.g.,
  *              the effective user and group ID's of the requesting process.
  *
  * ndirs - number of pmix_info_t structures in the directives array
  *
  * cbfunc - the pmix_credential_cbfunc_t function to be called upon completion
  *          of the request
  *
  * cbdata - pointer to an object to be returned when cbfunc is called
  *
  * Returned values:
  * PMIX_SUCCESS - indicates that the request is being processed by the host system
  *                management stack. The response will be coming in the provided
  *                callback function.
  *
  * Any other value indicates an appropriate error condition. The callback function
  * will _not_ be called in such cases.
  */
 typedef pmix_status_t (*pmix_server_get_cred_fn_t)(const pmix_proc_t *proc,
                                                    const pmix_info_t directives[], size_t ndirs,
                                                    pmix_credential_cbfunc_t cbfunc, void *cbdata);
 
 /* Request validation of a credential from the host SMS
  * Input values include:
  *
  * proc - pointer to a pmix_proc_t identifier of the process on whose behalf
  *        the request is being made (i.e., the client issuing the request)
  *
  * cred - pointer to a pmix_byte_object_t containing the provided credential
  *
  * directives - an array of pmix_info_t structures containing directives pertaining
  *              to the request. This will typically include any pmix_info_t structs
  *              passed by the requesting client, but may also include directives
  *              used by the PMIx server implementation
  *
  * ndirs - number of pmix_info_t structures in the directives array
  *
  * cbfunc - the pmix_validation_cbfunc_t function to be called upon completion
  *          of the request
  *
  * cbdata - pointer to an object to be returned when cbfunc is called
  *
  * Returned values:
  * PMIX_SUCCESS - indicates that the request is being processed by the host system
  *                management stack. The response will be coming in the provided
  *                callback function.
  *
  * Any other value indicates an appropriate error condition. The callback function
  * will _not_ be called in such cases.
  */
 typedef pmix_status_t (*pmix_server_validate_cred_fn_t)(const pmix_proc_t *proc,
                                                         const pmix_byte_object_t *cred,
                                                         const pmix_info_t directives[], size_t ndirs,
                                                         pmix_validation_cbfunc_t cbfunc, void *cbdata);
 
 /* Request the specified IO channels be forwarded from the given array of procs.
  * The function shall return PMIX_SUCCESS once the host RM accepts the request for
  * processing, or a PMIx error code if the request itself isn't correct or supported.
  * The callback function shall be called when the request has been processed,
  * returning either PMIX_SUCCESS to indicate that IO shall be forwarded as requested,
  * or some appropriate error code if the request has been denied.
  *
  * NOTE: STDIN is not supported in this call! The forwarding of stdin is a "push"
  * process - procs cannot request that it be "pulled" from some other source
  *
  * procs - array of process identifiers whose IO is being requested.
  *
  * nprocs - size of the procs array
  *
  * directives - array of key-value attributes further defining the request. This
  *              might include directives on buffering and security credentials for
  *              access to protected channels
  *
  * ndirs - size of the directives array
  *
  * channels - bitmask identifying the channels to be forwarded
  *
  * cbfunc - callback function when the IO forwarding has been setup
  *
  * cbdata - object to be returned in cbfunc
  *
  * This call serves as a registration with the host RM for the given IO channels from
  * the specified procs - the host RM is expected to ensure that this local PMIx server
  * is on the distribution list for the channel/proc combination. IF the PMIX_IOF_STOP
  * is included in the directives, then the local PMIx server is requesting that the
  * host RM remove the server from the distribution list for the specified channel/proc
  * combination.
  */
 typedef pmix_status_t (*pmix_server_iof_fn_t)(const pmix_proc_t procs[], size_t nprocs,
                                               const pmix_info_t directives[], size_t ndirs,
                                               pmix_iof_channel_t channels,
                                               pmix_op_cbfunc_t cbfunc, void *cbdata);
 
 /* Passes stdin to the host RM for transmission to specified recipients. The host RM is
  * responsible for forwarding the data to all PMIx servers that host the specified
  * target.
  *
  * source - pointer to the identifier of the process whose stdin is being provided
  *
  * 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 - array of key-value attributes further defining the request. This
  *              might include directives on buffering and security credentials for
  *              access to protected channels
  *
  * ndirs - size of the directives array
  *
  * bo - pointer to a byte object containing the stdin data
  *
  * cbfunc - callback function when the data has been forwarded
  *
  * cbdata - object to be returned in cbfunc
  *
  */
 
 typedef pmix_status_t (*pmix_server_stdin_fn_t)(const pmix_proc_t *source,
                                                 const pmix_proc_t targets[], size_t ntargets,
                                                 const pmix_info_t directives[], size_t ndirs,
                                                 const pmix_byte_object_t *bo,
                                                 pmix_op_cbfunc_t cbfunc, void *cbdata);
 
 
 /* Perform a "fence" operation across the specified procs, plus any special
  * actions included in the directives. Return the result of any special action
  * requests in the info cbfunc when the fence is completed. Actions may include:
  *
  * PMIX_GROUP_ASSIGN_CONTEXT_ID - request that the RM assign a unique
  *                                numerical (size_t) ID to this group
  *
  * grp - user-assigned string ID of this group
  *
  * op - pmix_group_operation_t value indicating the operation to perform
  *      Current values support construct and destruct of the group
  *
  * procs - pointer to array of pmix_proc_t ID's of group members
  *
  * nprocs - number of group members
  *
  * directives - array of key-value attributes specifying special actions.
  *
  * ndirs - size of the directives array
  *
  * cbfunc - callback function when the operation is completed
  *
  * cbdata - object to be returned in cbfunc
  */
 typedef pmix_status_t (*pmix_server_grp_fn_t)(pmix_group_operation_t op, char grp[],
                                               const pmix_proc_t procs[], size_t nprocs,
                                               const pmix_info_t directives[], size_t ndirs,
                                               pmix_info_cbfunc_t cbfunc, void *cbdata);
 
 /* Retrieve fabric-related information from the server supporting
  * the system scheduler.
  */
 typedef pmix_status_t (*pmix_server_fabric_fn_t)(const pmix_proc_t *requestor,
                                                  pmix_fabric_operation_t op,
                                                  const pmix_info_t directives[], size_t ndirs,
                                                  pmix_info_cbfunc_t cbfunc, void *cbdata);
 
 /* Execute a session control operation request */
 typedef pmix_status_t (*pmix_server_session_control_fn_t)(const pmix_proc_t *requestor,
                                                           uint32_t sessionID,
                                                           const pmix_info_t directives[], size_t ndirs,
                                                           pmix_info_cbfunc_t cbfunc, void *cbdata);
 
 typedef struct pmix_server_module_4_0_0_t {
     /* v1x interfaces */
     pmix_server_client_connected_fn_t   client_connected;
     pmix_server_client_finalized_fn_t   client_finalized;
     pmix_server_abort_fn_t              abort;
     pmix_server_fencenb_fn_t            fence_nb;
     pmix_server_dmodex_req_fn_t         direct_modex;
     pmix_server_publish_fn_t            publish;
     pmix_server_lookup_fn_t             lookup;
     pmix_server_unpublish_fn_t          unpublish;
     pmix_server_spawn_fn_t              spawn;
     pmix_server_connect_fn_t            connect;
     pmix_server_disconnect_fn_t         disconnect;
     pmix_server_register_events_fn_t    register_events;
     pmix_server_deregister_events_fn_t  deregister_events;
     pmix_server_listener_fn_t           listener;
     /* v2x interfaces */
     pmix_server_notify_event_fn_t       notify_event;
     pmix_server_query_fn_t              query;
     pmix_server_tool_connection_fn_t    tool_connected;
     pmix_server_log_fn_t                log;
     pmix_server_alloc_fn_t              allocate;
     pmix_server_job_control_fn_t        job_control;
     pmix_server_monitor_fn_t            monitor;
     /* v3x interfaces */
     pmix_server_get_cred_fn_t           get_credential;
     pmix_server_validate_cred_fn_t      validate_credential;
     pmix_server_iof_fn_t                iof_pull;
     pmix_server_stdin_fn_t              push_stdin;
     /* v4x interfaces */
     pmix_server_grp_fn_t                group;
     pmix_server_fabric_fn_t             fabric;
     pmix_server_client_connected2_fn_t  client_connected2;
     /* v5x interfaces */
     pmix_server_session_control_fn_t    session_control;
 } pmix_server_module_t;
 
 /****    HOST RM FUNCTIONS FOR INTERFACE TO PMIX SERVER    ****/
 
 /* Initialize the server support library, and provide a
  * pointer to a pmix_server_module_t structure
  * containing the caller's callback functions. The
  * array of pmix_info_t structs is used to pass
  * additional info that may be required by the server
  * when initializing - e.g., a user/group ID to set
  * on the rendezvous file for the Unix Domain Socket. It
  * also may include the PMIX_SERVER_TOOL_SUPPORT key, thereby
  * indicating that the daemon is willing to accept connection
  * requests from tools */
 PMIX_EXPORT pmix_status_t PMIx_server_init(pmix_server_module_t *module,
                                            pmix_info_t info[], size_t ninfo);
 
 /* Finalize the server support library. If internal comm is
  * in-use, the server will shut it down at this time. All
  * memory usage is released */
 PMIX_EXPORT pmix_status_t PMIx_server_finalize(void);
 
 /* Given a comma-separated list of \refarg{input} values, generate
  * a reduced size representation of the input that can be passed
  * down to PMIx_server_register_nspace for parsing. The order of
  * the individual values in the \refarg{input} string is preserved
  * across the operation. The caller is responsible for releasing
  * the returned data.
  *
  * The returned representation may be an arbitrary array of bytes
  * as opposed to a valid NULL-terminated string. However, the
  * method used to generate the representation shall be identified
  * with a colon-delimited string at the beginning of the output.
  * For example, an output starting with "pmix:" indicates that
  * the representation is a PMIx-defined regular expression.
  * In contrast, an output starting with "blob:" is a compressed
  * binary array.
  */
 PMIX_EXPORT pmix_status_t PMIx_generate_regex(const char *input, char **regex);
 
 /* The input shall consist of a semicolon-separated list of ranges
  * representing the ranks of processes on each node of the job -
  * e.g.,  "1-4;2-5;8,10,11,12;6,7,9". Each field of the input must
  * correspond to the node name provided at that position in the
  * input to PMIx_generate_regex. Thus, in the example, ranks 1-4
  * would be located on the first node of the comma-separated list
  * of names provided to PMIx_generate_regex, and ranks 2-5 would
  * be on the second name in the list.
  *
  * The returned representation may be an arbitrary array of bytes
  * as opposed to a valid NULL-terminated string. However, the
  * method used to generate the representation shall be identified
  * with a colon-delimited string at the beginning of the output.
  * For example, an output starting with "pmix:" indicates that
  * the representation is a PMIx-defined regular expression.
  * In contrast, an output starting with "blob:" is a compressed
  * binary array.
  */
 PMIX_EXPORT pmix_status_t PMIx_generate_ppn(const char *input, char **ppn);
 
 /* Setup the data about a particular nspace so it can
  * be passed to any child process upon startup. The PMIx
  * connection procedure provides an opportunity for the
  * host PMIx server to pass job-related info down to a
  * child process. This might include the number of
  * processes in the job, relative local ranks of the
  * processes within the job, and other information of
  * use to the process. The server is free to determine
  * which, if any, of the supported elements it will
  * provide - defined values are provided in pmix_common.h.
  *
  * NOTE: the server must register ALL nspaces that will
  * participate in collective operations with local processes.
  * This means that the server must register an nspace even
  * if it will not host any local procs from within that
  * nspace IF any local proc might at some point perform
  * a collective operation involving one or more procs from
  * that nspace. This is necessary so that the collective
  * operation can know when it is locally complete.
  *
  * The caller must also provide the number of local procs
  * that will be launched within this nspace. This is required
  * for the PMIx server library to correctly handle collectives
  * as a collective operation call can occur before all the
  * procs have been started */
 PMIX_EXPORT pmix_status_t PMIx_server_register_nspace(const pmix_nspace_t nspace, int nlocalprocs,
                                           pmix_info_t info[], size_t ninfo,
                                           pmix_op_cbfunc_t cbfunc, void *cbdata);
 
 /* Deregister an nspace and purge all objects relating to
  * it, including any client info from that nspace. This is
  * intended to support persistent PMIx servers by providing
  * an opportunity for the host RM to tell the PMIx server
  * library to release all memory for a completed job */
 PMIX_EXPORT void PMIx_server_deregister_nspace(const pmix_nspace_t nspace,
                                                pmix_op_cbfunc_t cbfunc, void *cbdata);
 
 /* Register a client process with the PMIx server library. The
  * expected user ID and group ID of the child process helps the
  * server library to properly authenticate clients as they connect
  * by requiring the two values to match.
  *
  * The host server can also, if it desires, provide an object
  * it wishes to be returned when a server function is called
  * that relates to a specific process. For example, the host
  * server may have an object that tracks the specific client.
  * Passing the object to the library allows the library to
  * return that object when the client calls "finalize", thus
  * allowing the host server to access the object without
  * performing a lookup. */
 PMIX_EXPORT pmix_status_t PMIx_server_register_client(const pmix_proc_t *proc,
                                                       uid_t uid, gid_t gid,
                                                       void *server_object,
                                                       pmix_op_cbfunc_t cbfunc, void *cbdata);
 
 /* Deregister a client and purge all data relating to it. The
  * deregister_nspace API will automatically delete all client
  * info for that nspace - this API is therefore intended solely
  * for use in exception cases */
 PMIX_EXPORT void PMIx_server_deregister_client(const pmix_proc_t *proc,
                                                pmix_op_cbfunc_t cbfunc, void *cbdata);
 
 /* Setup the environment of a child process to be forked
  * by the host so it can correctly interact with the PMIx
  * server. The PMIx client needs some setup information
  * so it can properly connect back to the server. This function
  * will set appropriate environmental variables for this purpose. */
 PMIX_EXPORT pmix_status_t PMIx_server_setup_fork(const pmix_proc_t *proc, char ***env);
 
 /* Define a callback function the PMIx server will use to return
  * direct modex requests to the host server. The PMIx server
  * will free the data blob upon return from the response fn */
 typedef void (*pmix_dmodex_response_fn_t)(pmix_status_t status,
                                           char *data, size_t sz,
                                           void *cbdata);
 
 /* Define a function by which the host server can request modex data
  * from the local PMIx server. This is used to support the direct modex
  * operation - i.e., where data is cached locally on each PMIx
  * server for its own local clients, and is obtained on-demand
  * for remote requests. Upon receiving a request from a remote
  * server, the host server will call this function to pass the
  * request into the PMIx server. The PMIx server will return a blob
  * (once it becomes available) via the cbfunc - the host
  * server shall send the blob back to the original requestor */
 PMIX_EXPORT pmix_status_t PMIx_server_dmodex_request(const pmix_proc_t *proc,
                                                      pmix_dmodex_response_fn_t cbfunc,
                                                      void *cbdata);
 
 /* define a callback function for the setup_application API. The returned info
  * array is owned by the PMIx server library and will be free'd when the
  * provided cbfunc is called. */
 typedef void (*pmix_setup_application_cbfunc_t)(pmix_status_t status,
                                                 pmix_info_t info[], size_t ninfo,
                                                 void *provided_cbdata,
                                                 pmix_op_cbfunc_t cbfunc, void *cbdata);
 
 /* Provide a function by which the resource manager can request
  * any application-specific environmental variables, resource
  * assignments, and/or other data prior to launch of an application.
  * For example, network libraries may opt to provide security
  * credentials for the application. This is defined as a non-blocking
  * operation in case network libraries need to perform some action
  * before responding. Any returned env will be distributed along
  * with the application */
 PMIX_EXPORT pmix_status_t PMIx_server_setup_application(const pmix_nspace_t nspace,
                                                         pmix_info_t info[], size_t ninfo,
                                                         pmix_setup_application_cbfunc_t cbfunc, void *cbdata);
 
 /* Provide a function by which the local PMIx server can perform
  * any application-specific operations prior to spawning local
  * clients of a given application. For example, a network library
  * might need to setup the local driver for "instant on" addressing.
  * Data provided in the info array will be stored in the job-info
  * region for the nspace. Operations included in the info array
  * will be cached until the server calls PMIx_server_setup_fork,
  * thereby indicating that local clients of this nspace will exist.
  * Operations indicated by the provided data will only be executed
  * for the first local client - i.e., they will only be executed
  * once for a given nspace
  */
 PMIX_EXPORT pmix_status_t PMIx_server_setup_local_support(const pmix_nspace_t nspace,
                                                           pmix_info_t info[], size_t ninfo,
                                                           pmix_op_cbfunc_t cbfunc, void *cbdata);
 
 /* Provide a function by which the host RM can pass forwarded IO
  * to the local PMIx server for distribution to its clients. The
  * PMIx server is responsible for determining which of its clients
  * have actually registered for the provided data
  *
  * Parameters include:
  *
  * source - the process that provided the data being forwarded
  *
  * channel - the IOF channel (stdin, stdout, etc.)
  *
  * bo - a byte object containing the data
  *
  * info - an optional array of metadata describing the data, including
  *        attributes such as PMIX_IOF_COMPLETE to indicate that the
  *        source channel has been closed
  *
  * ninfo - number of elements in the info array
  *
  * cbfunc - a callback function to be executed once the provided data
  *          is no longer required. The host RM is required to retain
  *          the byte object until the callback is executed, or a
  *          non-success status is returned by the function
  *
  * cbdata - object pointer to be returned in the callback function
  */
 PMIX_EXPORT pmix_status_t PMIx_server_IOF_deliver(const pmix_proc_t *source,
                                                   pmix_iof_channel_t channel,
                                                   const pmix_byte_object_t *bo,
                                                   const pmix_info_t info[], size_t ninfo,
                                                   pmix_op_cbfunc_t cbfunc, void *cbdata);
 
 /* Collect inventory of local resources. This is a non-blocking
  * API as it may involve somewhat lengthy operations to obtain
  * the requested information. Servers designated as "gateways"
  * and whose plugins support collection of infrastructure info
  * (e.g., switch and fabric topology, connectivity maps) shall
  * return that information - plugins on non-gateway servers
  * shall only return the node-local inventory. */
 PMIX_EXPORT pmix_status_t PMIx_server_collect_inventory(pmix_info_t directives[], size_t ndirs,
                                                         pmix_info_cbfunc_t cbfunc, void *cbdata);
 
 /* Deliver collected inventory for archiving by the corresponding
  * plugins. Typically executed on a "gateway" associated with the
  * system scheduler to enable use of inventory information by the
  * the scheduling algorithm. May also be used on compute nodes to
  * store a broader picture of the system for access by applications,
  * if desired */
 PMIX_EXPORT pmix_status_t PMIx_server_deliver_inventory(pmix_info_t info[], size_t ninfo,
                                                         pmix_info_t directives[], size_t ndirs,
                                                         pmix_op_cbfunc_t cbfunc, void *cbdata);
 
 
 /******      ATTRIBUTE REGISTRATION      ******/
 /**
  * This function is used by the host environment to register with its
  * server library the attributes it supports for each pmix_server_module_t
  * function.
  *
  * Parameters include:
  *
  * function - the string name of the server module function
  *            (e.g., "register_events", "validate_credential",
  *            or "allocate") whose attributes are being registered.
  *
  * attrs - NULL-terminated argv array of attributes supported
  *         by the host environment for the specified function
  *
  */
 PMIX_EXPORT pmix_status_t PMIx_Register_attributes(char *function, char *attrs[]);
 
 /* Generate a PMIx locality string from a given cpuset.
  * Provide a function by which the host environment can generate a PMIx locality
  * string for inclusion in the call to PMIx_server_register_nspace . This function
  * shall only be called for local client processes, with the returned locality
  * included in the job-level information (via the PMIX_LOCALITY_STRING attribute)
  * provided to local clients.
  */
 PMIX_EXPORT pmix_status_t PMIx_server_generate_locality_string(const pmix_cpuset_t *cpuset,
                                                                char **locality);
 
 /* Generate a PMIx string representation of the provided cpuset.
  * Provide a function by which the host environment can generate a string
  * representation of the cpuset bitmap for inclusion in the call to
  * PMIx_server_register_nspace . This function shall only be called for local
  * client processes, with the returned string included in the job-level information
  * (via the PMIX_CPUSET attribute) provided to local clients.
  */
 PMIX_EXPORT pmix_status_t PMIx_server_generate_cpuset_string(const pmix_cpuset_t *cpuset,
                                                              char **cpuset_string);
 
 /* Define a process set
  * Provide a function by which the host environment can define a new process set.
  */
 PMIX_EXPORT pmix_status_t PMIx_server_define_process_set(const pmix_proc_t *members,
                                                          size_t nmembers, const char *pset_name);
 
 /* Delete a process set
  * Provide a function by which the host environment can delete a new process set.
  */
 PMIX_EXPORT pmix_status_t PMIx_server_delete_process_set(char *pset_name);
 
 
 /* Register non-namespace related information with the local PMIx server library.
  */
 PMIX_EXPORT pmix_status_t PMIx_server_register_resources(pmix_info_t info[], size_t ninfo,
                                                          pmix_op_cbfunc_t cbfunc,
                                                          void *cbdata);
 
 /* Remove specified non-namespace related information from the local PMIx server library.
  */
 PMIX_EXPORT pmix_status_t PMIx_server_deregister_resources(pmix_info_t info[], size_t ninfo,
                                                            pmix_op_cbfunc_t cbfunc,
                                                            void *cbdata);
 
 #if defined(c_plusplus) || defined(__cplusplus)
 }
 #endif
 
 #endif

This page was automatically generated by the 2.3.7 LXR engine. The LXR team