1 /*
2 * Copyright (c) 2013-2019 Intel, Inc. All rights reserved.
3 * Copyright (c) 2015 Artem Y. Polyakov <artpol84@gmail.com>.
4 * All rights reserved.
5 * Copyright (c) 2015 Research Organization for Information Science
6 * and Technology (RIST). All rights reserved.
7 * $COPYRIGHT$
8 *
9 * Redistribution and use in source and binary forms, with or without
10 * modification, are permitted provided that the following conditions are
11 * met:
12 *
13 * - Redistributions of source code must retain the above copyright
14 * notice, this list of conditions and the following disclaimer.
15 *
16 * - Redistributions in binary form must reproduce the above copyright
17 * notice, this list of conditions and the following disclaimer listed
18 * in this license in the documentation and/or other materials
19 * provided with the distribution.
20 *
21 * - Neither the name of the copyright holders nor the names of its
22 * contributors may be used to endorse or promote products derived from
23 * this software without specific prior written permission.
24 *
25 * The copyright holders provide no reassurances that the source code
26 * provided does not infringe any patent, copyright, or any other
27 * intellectual property rights of third parties. The copyright holders
28 * disclaim any liability to any recipient for claims brought against
29 * recipient by any third party for infringement of that parties
30 * intellectual property rights.
31 *
32 * THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS
33 * "AS IS" AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT
34 * LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR
35 * A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT
36 * OWNER OR CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL,
37 * SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT
38 * LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE,
39 * DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY
40 * THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT
41 * (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE
42 * OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
43 *
44 * $HEADER$
45 *
46 * PMIx provides a "function-shipping" approach to support for
47 * implementing the server-side of the protocol. This method allows
48 * resource managers to implement the server without being burdened
49 * with PMIx internal details. Accordingly, each PMIx API is mirrored
50 * here in a function call to be provided by the server. When a
51 * request is received from the client, the corresponding server function
52 * will be called with the information.
53 *
54 * Any functions not supported by the RM can be indicated by a NULL for
55 * the function pointer. Client calls to such functions will have a
56 * "not supported" error returned.
57 */
58
59 #ifndef PMIx_SERVER_API_H
60 #define PMIx_SERVER_API_H
61
62 /* Structure and constant definitions */
63 #include <pmix_common.h>
64
65 #if defined(c_plusplus) || defined(__cplusplus)
66 extern "C" {
67 #endif
68
69 /**** SERVER FUNCTION-SHIPPED APIs ****/
70 /* NOTE: for performance purposes, the host server is required to
71 * return as quickly as possible from all functions. Execution of
72 * the function is thus to be done asynchronously so as to allow
73 * the PMIx server support library to handle multiple client requests
74 * as quickly and scalably as possible.
75 *
76 * ALL data passed to the host server functions is "owned" by the
77 * PMIX server support library and MUST NOT be free'd. Data returned
78 * by the host server via callback function is owned by the host
79 * server, which is free to release it upon return from the callback */
80
81 /* Notify the host server that a client connected to us - note
82 * that the client will be in a blocked state until the host server
83 * executes the callback function, thus allowing the PMIx server support
84 * library to release the client */
85 typedef pmix_status_t (*pmix_server_client_connected_fn_t)(const pmix_proc_t *proc, void* server_object,
86 pmix_op_cbfunc_t cbfunc, void *cbdata);
87
88 /* Notify the host server that a client called PMIx_Finalize - note
89 * that the client will be in a blocked state until the host server
90 * executes the callback function, thus allowing the PMIx server support
91 * library to release the client */
92 typedef pmix_status_t (*pmix_server_client_finalized_fn_t)(const pmix_proc_t *proc, void* server_object,
93 pmix_op_cbfunc_t cbfunc, void *cbdata);
94
95 /* A local client called PMIx_Abort - note that the client will be in a blocked
96 * state until the host server executes the callback function, thus
97 * allowing the PMIx server support library to release the client. The
98 * array of procs indicates which processes are to be terminated. A NULL
99 * indicates that all procs in the client's nspace are to be terminated */
100 typedef pmix_status_t (*pmix_server_abort_fn_t)(const pmix_proc_t *proc, void *server_object,
101 int status, const char msg[],
102 pmix_proc_t procs[], size_t nprocs,
103 pmix_op_cbfunc_t cbfunc, void *cbdata);
104
105 /* At least one client called either PMIx_Fence or PMIx_Fence_nb. In either case,
106 * the host server will be called via a non-blocking function to execute
107 * the specified operation once all participating local procs have
108 * contributed. All processes in the specified array are required to participate
109 * in the Fence[_nb] operation. The callback is to be executed once each daemon
110 * hosting at least one participant has called the host server's fencenb function.
111 *
112 * The provided data is to be collectively shared with all PMIx
113 * servers involved in the fence operation, and returned in the modex
114 * cbfunc. A _NULL_ data value indicates that the local procs had
115 * no data to contribute.
116 *
117 * The array of info structs is used to pass user-requested options to the server.
118 * This can include directives as to the algorithm to be used to execute the
119 * fence operation. The directives are optional _unless_ the _mandatory_ flag
120 * has been set - in such cases, the host RM is required to return an error
121 * if the directive cannot be met. */
122 typedef pmix_status_t (*pmix_server_fencenb_fn_t)(const pmix_proc_t procs[], size_t nprocs,
123 const pmix_info_t info[], size_t ninfo,
124 char *data, size_t ndata,
125 pmix_modex_cbfunc_t cbfunc, void *cbdata);
126
127
128 /* Used by the PMIx server to request its local host contact the
129 * PMIx server on the remote node that hosts the specified proc to
130 * obtain and return a direct modex blob for that proc.
131 *
132 * The array of info structs is used to pass user-requested options to the server.
133 * This can include a timeout to preclude an indefinite wait for data that
134 * may never become available. The directives are optional _unless_ the _mandatory_ flag
135 * has been set - in such cases, the host RM is required to return an error
136 * if the directive cannot be met. */
137 typedef pmix_status_t (*pmix_server_dmodex_req_fn_t)(const pmix_proc_t *proc,
138 const pmix_info_t info[], size_t ninfo,
139 pmix_modex_cbfunc_t cbfunc, void *cbdata);
140
141
142 /* Publish data per the PMIx API specification. The callback is to be executed
143 * upon completion of the operation. The default data range is expected to be
144 * PMIX_SESSION, and the default persistence PMIX_PERSIST_SESSION. These values
145 * can be modified by including the respective pmix_info_t struct in the
146 * provided array.
147 *
148 * Note that the host server is not required to guarantee support for any specific
149 * range - i.e., the server does not need to return an error if the data store
150 * doesn't support range-based isolation. However, the server must return an error
151 * (a) if the key is duplicative within the storage range, and (b) if the server
152 * does not allow overwriting of published info by the original publisher - it is
153 * left to the discretion of the host server to allow info-key-based flags to modify
154 * this behavior.
155 *
156 * The persistence indicates how long the server should retain the data.
157 *
158 * The identifier of the publishing process is also provided and is expected to
159 * be returned on any subsequent lookup request */
160 typedef pmix_status_t (*pmix_server_publish_fn_t)(const pmix_proc_t *proc,
161 const pmix_info_t info[], size_t ninfo,
162 pmix_op_cbfunc_t cbfunc, void *cbdata);
163
164 /* Lookup published data. The host server will be passed a NULL-terminated array
165 * of string keys.
166 *
167 * The array of info structs is used to pass user-requested options to the server.
168 * This can include a wait flag to indicate that the server should wait for all
169 * data to become available before executing the callback function, or should
170 * immediately callback with whatever data is available. In addition, a timeout
171 * can be specified on the wait to preclude an indefinite wait for data that
172 * may never be published. */
173 typedef pmix_status_t (*pmix_server_lookup_fn_t)(const pmix_proc_t *proc, char **keys,
174 const pmix_info_t info[], size_t ninfo,
175 pmix_lookup_cbfunc_t cbfunc, void *cbdata);
176
177 /* Delete data from the data store. The host server will be passed a NULL-terminated array
178 * of string keys, plus potential directives such as the data range within which the
179 * keys should be deleted. The callback is to be executed upon completion of the delete
180 * procedure */
181 typedef pmix_status_t (*pmix_server_unpublish_fn_t)(const pmix_proc_t *proc, char **keys,
182 const pmix_info_t info[], size_t ninfo,
183 pmix_op_cbfunc_t cbfunc, void *cbdata);
184
185 /* Spawn a set of applications/processes as per the PMIx API. Note that
186 * applications are not required to be MPI or any other programming model.
187 * Thus, the host server cannot make any assumptions as to their required
188 * support. The callback function is to be executed once all processes have
189 * been started. An error in starting any application or process in this
190 * request shall cause all applications and processes in the request to
191 * be terminated, and an error returned to the originating caller.
192 *
193 * Note that a timeout can be specified in the job_info array to indicate
194 * that failure to start the requested job within the given time should
195 * result in termination to avoid hangs */
196 typedef pmix_status_t (*pmix_server_spawn_fn_t)(const pmix_proc_t *proc,
197 const pmix_info_t job_info[], size_t ninfo,
198 const pmix_app_t apps[], size_t napps,
199 pmix_spawn_cbfunc_t cbfunc, void *cbdata);
200
201 /* Record the specified processes as "connected". This means that the resource
202 * manager should treat the failure of any process in the specified group as
203 * a reportable event, and take appropriate action. The callback function is
204 * to be called once all participating processes have called connect. Note that
205 * a process can only engage in *one* connect operation involving the identical
206 * set of procs at a time. However, a process *can* be simultaneously engaged
207 * in multiple connect operations, each involving a different set of procs
208 *
209 * Note also that this is a collective operation within the client library, and
210 * thus the client will be blocked until all procs participate. Thus, the info
211 * array can be used to pass user directives, including a timeout.
212 * The directives are optional _unless_ the _mandatory_ flag
213 * has been set - in such cases, the host RM is required to return an error
214 * if the directive cannot be met. */
215 typedef pmix_status_t (*pmix_server_connect_fn_t)(const pmix_proc_t procs[], size_t nprocs,
216 const pmix_info_t info[], size_t ninfo,
217 pmix_op_cbfunc_t cbfunc, void *cbdata);
218
219 /* Disconnect a previously connected set of processes. An error should be returned
220 * if the specified set of procs was not previously "connected". As above, a process
221 * may be involved in multiple simultaneous disconnect operations. However, a process
222 * is not allowed to reconnect to a set of ranges that has not fully completed
223 * disconnect - i.e., you have to fully disconnect before you can reconnect to the
224 * same group of processes.
225 *
226 * Note also that this is a collective operation within the client library, and
227 * thus the client will be blocked until all procs participate. Thus, the info
228 * array can be used to pass user directives, including a timeout.
229 * The directives are optional _unless_ the _mandatory_ flag
230 * has been set - in such cases, the host RM is required to return an error
231 * if the directive cannot be met. */
232 typedef pmix_status_t (*pmix_server_disconnect_fn_t)(const pmix_proc_t procs[], size_t nprocs,
233 const pmix_info_t info[], size_t ninfo,
234 pmix_op_cbfunc_t cbfunc, void *cbdata);
235
236 /* Register to receive notifications for the specified events. The resource
237 * manager is _required_ to pass along to the local PMIx server all events
238 * that directly relate to a registered namespace. However, the RM may have
239 * access to events beyond those - e.g., environmental events. The PMIx server
240 * will register to receive environmental events that match specific PMIx
241 * event codes. If the host RM supports such notifications, it will need to
242 * translate its own internal event codes to fit into a corresponding PMIx event
243 * code - any specific info beyond that can be passed in via the pmix_info_t
244 * upon notification.
245 *
246 * The info array included in this API is reserved for possible future directives
247 * to further steer notification.
248 */
249 typedef pmix_status_t (*pmix_server_register_events_fn_t)(pmix_status_t *codes, size_t ncodes,
250 const pmix_info_t info[], size_t ninfo,
251 pmix_op_cbfunc_t cbfunc, void *cbdata);
252
253 /* Deregister to receive notifications for the specified environmental events
254 * for which the PMIx server has previously registered. The host RM remains
255 * required to notify of any job-related events */
256 typedef pmix_status_t (*pmix_server_deregister_events_fn_t)(pmix_status_t *codes, size_t ncodes,
257 pmix_op_cbfunc_t cbfunc, void *cbdata);
258
259 /* Notify the specified processes of an event generated either by
260 * the PMIx server itself, or by one of its local clients. The process
261 * generating the event is provided in the source parameter. */
262 typedef pmix_status_t (*pmix_server_notify_event_fn_t)(pmix_status_t code,
263 const pmix_proc_t *source,
264 pmix_data_range_t range,
265 pmix_info_t info[], size_t ninfo,
266 pmix_op_cbfunc_t cbfunc, void *cbdata);
267
268 /* Callback function for incoming connection requests from
269 * local clients */
270 typedef void (*pmix_connection_cbfunc_t)(int incoming_sd, void *cbdata);
271
272 /* Register a socket the host server can monitor for connection
273 * requests, harvest them, and then call our internal callback
274 * function for further processing. A listener thread is essential
275 * to efficiently harvesting connection requests from large
276 * numbers of local clients such as occur when running on large
277 * SMPs. The host server listener is required to call accept
278 * on the incoming connection request, and then passing the
279 * resulting soct to the provided cbfunc. A NULL for this function
280 * will cause the internal PMIx server to spawn its own listener
281 * thread */
282 typedef pmix_status_t (*pmix_server_listener_fn_t)(int listening_sd,
283 pmix_connection_cbfunc_t cbfunc,
284 void *cbdata);
285
286 /* Query information from the resource manager. The query will include
287 * the nspace/rank of the proc that is requesting the info, an
288 * array of pmix_query_t describing the request, and a callback
289 * function/data for the return. */
290 typedef pmix_status_t (*pmix_server_query_fn_t)(pmix_proc_t *proct,
291 pmix_query_t *queries, size_t nqueries,
292 pmix_info_cbfunc_t cbfunc,
293 void *cbdata);
294
295 /* Callback function for incoming tool connections - the host
296 * RM shall provide an nspace/rank for the connecting tool. We
297 * assume that a rank=0 will be the normal assignment, but allow
298 * for the future possibility of a parallel set of tools
299 * connecting, and thus each proc requiring a rank*/
300 typedef void (*pmix_tool_connection_cbfunc_t)(pmix_status_t status,
301 pmix_proc_t *proc, void *cbdata);
302
303 /* Register that a tool has connected to the server, and request
304 * that the tool be assigned an nspace/rank for further interactions.
305 * The optional pmix_info_t array can be used to pass qualifiers for
306 * the connection request:
307 *
308 * (a) PMIX_USERID - effective userid of the tool
309 * (b) PMIX_GRPID - effective groupid of the tool
310 * (c) PMIX_FWD_STDOUT - forward any stdout to this tool
311 * (d) PMIX_FWD_STDERR - forward any stderr to this tool
312 * (e) PMIX_FWD_STDIN - forward stdin from this tool to any
313 * processes spawned on its behalf
314 */
315 typedef void (*pmix_server_tool_connection_fn_t)(pmix_info_t *info, size_t ninfo,
316 pmix_tool_connection_cbfunc_t cbfunc,
317 void *cbdata);
318
319 /* Log data on behalf of a client. Calls to the host thru this
320 * function must _NOT_ call the PMIx_Log API as this will
321 * trigger an infinite loop. Instead, the implementation must
322 * perform one of three operations:
323 *
324 * (a) transfer the data+directives to a "gateway" server
325 * where they can be logged. Gateways are designated
326 * servers on nodes (typically service nodes) where
327 * centralized logging is supported. The data+directives
328 * may be passed to the PMIx_Log API once arriving at
329 * that destination.
330 *
331 * (b) transfer the data to a logging channel outside of
332 * PMIx, but directly supported by the host
333 *
334 * (c) return an error to the caller indicating that the
335 * requested action is not supported
336 */
337 typedef void (*pmix_server_log_fn_t)(const pmix_proc_t *client,
338 const pmix_info_t data[], size_t ndata,
339 const pmix_info_t directives[], size_t ndirs,
340 pmix_op_cbfunc_t cbfunc, void *cbdata);
341
342 /* Request allocation modifications on behalf of a client */
343 typedef pmix_status_t (*pmix_server_alloc_fn_t)(const pmix_proc_t *client,
344 pmix_alloc_directive_t directive,
345 const pmix_info_t data[], size_t ndata,
346 pmix_info_cbfunc_t cbfunc, void *cbdata);
347
348 /* Execute a job control action on behalf of a client */
349 typedef pmix_status_t (*pmix_server_job_control_fn_t)(const pmix_proc_t *requestor,
350 const pmix_proc_t targets[], size_t ntargets,
351 const pmix_info_t directives[], size_t ndirs,
352 pmix_info_cbfunc_t cbfunc, void *cbdata);
353
354 /* Request that a client be monitored for activity */
355 typedef pmix_status_t (*pmix_server_monitor_fn_t)(const pmix_proc_t *requestor,
356 const pmix_info_t *monitor, pmix_status_t error,
357 const pmix_info_t directives[], size_t ndirs,
358 pmix_info_cbfunc_t cbfunc, void *cbdata);
359
360 /* Request a credential from the host SMS
361 * Input values include:
362 *
363 * proc - pointer to a pmix_proc_t identifier of the process on whose behalf
364 * the request is being made (i.e., the client originating the request)
365 *
366 * directives - an array of pmix_info_t structures containing directives pertaining
367 * to the request. This will typically include any pmix_info_t structs
368 * passed by the requesting client, but may also include directives
369 * required by (or available from) the PMIx server implementation - e.g.,
370 * the effective user and group ID's of the requesting process.
371 *
372 * ndirs - number of pmix_info_t structures in the directives array
373 *
374 * cbfunc - the pmix_credential_cbfunc_t function to be called upon completion
375 * of the request
376 *
377 * cbdata - pointer to an object to be returned when cbfunc is called
378 *
379 * Returned values:
380 * PMIX_SUCCESS - indicates that the request is being processed by the host system
381 * management stack. The response will be coming in the provided
382 * callback function.
383 *
384 * Any other value indicates an appropriate error condition. The callback function
385 * will _not_ be called in such cases.
386 */
387 typedef pmix_status_t (*pmix_server_get_cred_fn_t)(const pmix_proc_t *proc,
388 const pmix_info_t directives[], size_t ndirs,
389 pmix_credential_cbfunc_t cbfunc, void *cbdata);
390
391 /* Request validation of a credential from the host SMS
392 * Input values include:
393 *
394 * proc - pointer to a pmix_proc_t identifier of the process on whose behalf
395 * the request is being made (i.e., the client issuing the request)
396 *
397 * cred - pointer to a pmix_byte_object_t containing the provided credential
398 *
399 * directives - an array of pmix_info_t structures containing directives pertaining
400 * to the request. This will typically include any pmix_info_t structs
401 * passed by the requesting client, but may also include directives
402 * used by the PMIx server implementation
403 *
404 * ndirs - number of pmix_info_t structures in the directives array
405 *
406 * cbfunc - the pmix_validation_cbfunc_t function to be called upon completion
407 * of the request
408 *
409 * cbdata - pointer to an object to be returned when cbfunc is called
410 *
411 * Returned values:
412 * PMIX_SUCCESS - indicates that the request is being processed by the host system
413 * management stack. The response will be coming in the provided
414 * callback function.
415 *
416 * Any other value indicates an appropriate error condition. The callback function
417 * will _not_ be called in such cases.
418 */
419 typedef pmix_status_t (*pmix_server_validate_cred_fn_t)(const pmix_proc_t *proc,
420 const pmix_byte_object_t *cred,
421 const pmix_info_t directives[], size_t ndirs,
422 pmix_validation_cbfunc_t cbfunc, void *cbdata);
423
424 /* Request the specified IO channels be forwarded from the given array of procs.
425 * The function shall return PMIX_SUCCESS once the host RM accepts the request for
426 * processing, or a PMIx error code if the request itself isn't correct or supported.
427 * The callback function shall be called when the request has been processed,
428 * returning either PMIX_SUCCESS to indicate that IO shall be forwarded as requested,
429 * or some appropriate error code if the request has been denied.
430 *
431 * NOTE: STDIN is not supported in this call! The forwarding of stdin is a "push"
432 * process - procs cannot request that it be "pulled" from some other source
433 *
434 * procs - array of process identifiers whose IO is being requested.
435 *
436 * nprocs - size of the procs array
437 *
438 * directives - array of key-value attributes further defining the request. This
439 * might include directives on buffering and security credentials for
440 * access to protected channels
441 *
442 * ndirs - size of the directives array
443 *
444 * channels - bitmask identifying the channels to be forwarded
445 *
446 * cbfunc - callback function when the IO forwarding has been setup
447 *
448 * cbdata - object to be returned in cbfunc
449 *
450 * This call serves as a registration with the host RM for the given IO channels from
451 * the specified procs - the host RM is expected to ensure that this local PMIx server
452 * is on the distribution list for the channel/proc combination
453 */
454 typedef pmix_status_t (*pmix_server_iof_fn_t)(const pmix_proc_t procs[], size_t nprocs,
455 const pmix_info_t directives[], size_t ndirs,
456 pmix_iof_channel_t channels,
457 pmix_op_cbfunc_t cbfunc, void *cbdata);
458
459 /* Passes stdin to the host RM for transmission to specified recipients. The host RM is
460 * responsible for forwarding the data to all PMIx servers that host the specified
461 * target.
462 *
463 * source - pointer to the identifier of the process whose stdin is being provided
464 *
465 * targets - array of process identifiers to which the data is to be delivered. Note
466 * that a WILDCARD rank indicates that all procs in the given nspace are
467 * to receive a copy of the data
468 *
469 * ntargets - number of procs in the targets array
470 *
471 * directives - array of key-value attributes further defining the request. This
472 * might include directives on buffering and security credentials for
473 * access to protected channels
474 *
475 * ndirs - size of the directives array
476 *
477 * bo - pointer to a byte object containing the stdin data
478 *
479 * cbfunc - callback function when the data has been forwarded
480 *
481 * cbdata - object to be returned in cbfunc
482 *
483 */
484
485 typedef pmix_status_t (*pmix_server_stdin_fn_t)(const pmix_proc_t *source,
486 const pmix_proc_t targets[], size_t ntargets,
487 const pmix_info_t directives[], size_t ndirs,
488 const pmix_byte_object_t *bo,
489 pmix_op_cbfunc_t cbfunc, void *cbdata);
490
491
492 /* Perform a "fence" operation across the specified procs, plus any special
493 * actions included in the directives. Return the result of any special action
494 * requests in the info cbfunc when the fence is completed. Actions may include:
495 *
496 * PMIX_GROUP_ASSIGN_CONTEXT_ID - request that the RM assign a unique
497 * numerical (size_t) ID to this group
498 *
499 * grp - user-assigned string ID of this group
500 *
501 * op - pmix_group_operation_t value indicating the operation to perform
502 * Current values support construct and destruct of the group
503 *
504 * procs - pointer to array of pmix_proc_t ID's of group members
505 *
506 * nprocs - number of group members
507 *
508 * directives - array of key-value attributes specifying special actions.
509 *
510 * ndirs - size of the directives array
511 *
512 * cbfunc - callback function when the operation is completed
513 *
514 * cbdata - object to be returned in cbfunc
515 */
516 typedef pmix_status_t (*pmix_server_grp_fn_t)(pmix_group_operation_t op, char grp[],
517 const pmix_proc_t procs[], size_t nprocs,
518 const pmix_info_t directives[], size_t ndirs,
519 pmix_info_cbfunc_t cbfunc, void *cbdata);
520
521 typedef struct pmix_server_module_2_0_0_t {
522 /* v1x interfaces */
523 pmix_server_client_connected_fn_t client_connected;
524 pmix_server_client_finalized_fn_t client_finalized;
525 pmix_server_abort_fn_t abort;
526 pmix_server_fencenb_fn_t fence_nb;
527 pmix_server_dmodex_req_fn_t direct_modex;
528 pmix_server_publish_fn_t publish;
529 pmix_server_lookup_fn_t lookup;
530 pmix_server_unpublish_fn_t unpublish;
531 pmix_server_spawn_fn_t spawn;
532 pmix_server_connect_fn_t connect;
533 pmix_server_disconnect_fn_t disconnect;
534 pmix_server_register_events_fn_t register_events;
535 pmix_server_deregister_events_fn_t deregister_events;
536 pmix_server_listener_fn_t listener;
537 /* v2x interfaces */
538 pmix_server_notify_event_fn_t notify_event;
539 pmix_server_query_fn_t query;
540 pmix_server_tool_connection_fn_t tool_connected;
541 pmix_server_log_fn_t log;
542 pmix_server_alloc_fn_t allocate;
543 pmix_server_job_control_fn_t job_control;
544 pmix_server_monitor_fn_t monitor;
545 /* v3x interfaces */
546 pmix_server_get_cred_fn_t get_credential;
547 pmix_server_validate_cred_fn_t validate_credential;
548 pmix_server_iof_fn_t iof_pull;
549 pmix_server_stdin_fn_t push_stdin;
550 /* v4x interfaces */
551 pmix_server_grp_fn_t group;
552 } pmix_server_module_t;
553
554 /**** HOST RM FUNCTIONS FOR INTERFACE TO PMIX SERVER ****/
555
556 /* Initialize the server support library, and provide a
557 * pointer to a pmix_server_module_t structure
558 * containing the caller's callback functions. The
559 * array of pmix_info_t structs is used to pass
560 * additional info that may be required by the server
561 * when initializing - e.g., a user/group ID to set
562 * on the rendezvous file for the Unix Domain Socket. It
563 * also may include the PMIX_SERVER_TOOL_SUPPORT key, thereby
564 * indicating that the daemon is willing to accept connection
565 * requests from tools */
566 PMIX_EXPORT pmix_status_t PMIx_server_init(pmix_server_module_t *module,
567 pmix_info_t info[], size_t ninfo);
568
569 /* Finalize the server support library. If internal comm is
570 * in-use, the server will shut it down at this time. All
571 * memory usage is released */
572 PMIX_EXPORT pmix_status_t PMIx_server_finalize(void);
573
574 /* given a semicolon-separated list of input values, generate
575 * a regex that can be passed down to the client for parsing.
576 * The caller is responsible for free'ing the resulting
577 * string
578 *
579 * If values have leading zero's, then that is preserved. You
580 * have to add back any prefix/suffix for node names
581 * odin[009-015,017-023,076-086]
582 *
583 * "pmix:odin[009-015,017-023,076-086]"
584 *
585 * Note that the "pmix" at the beginning of each regex indicates
586 * that the PMIx native parser is to be used by the client for
587 * parsing the provided regex. Other parsers may be supported - see
588 * the pmix_client.h header for a list.
589 */
590 PMIX_EXPORT pmix_status_t PMIx_generate_regex(const char *input, char **regex);
591
592 /* The input is expected to consist of a comma-separated list
593 * of ranges. Thus, an input of:
594 * "1-4;2-5;8,10,11,12;6,7,9"
595 * would generate a regex of
596 * "[pmix:2x(3);8,10-12;6-7,9]"
597 *
598 * Note that the "pmix" at the beginning of each regex indicates
599 * that the PMIx native parser is to be used by the client for
600 * parsing the provided regex. Other parsers may be supported - see
601 * the pmix_client.h header for a list.
602 */
603 PMIX_EXPORT pmix_status_t PMIx_generate_ppn(const char *input, char **ppn);
604
605 /* Setup the data about a particular nspace so it can
606 * be passed to any child process upon startup. The PMIx
607 * connection procedure provides an opportunity for the
608 * host PMIx server to pass job-related info down to a
609 * child process. This might include the number of
610 * processes in the job, relative local ranks of the
611 * processes within the job, and other information of
612 * use to the process. The server is free to determine
613 * which, if any, of the supported elements it will
614 * provide - defined values are provided in pmix_common.h.
615 *
616 * NOTE: the server must register ALL nspaces that will
617 * participate in collective operations with local processes.
618 * This means that the server must register an nspace even
619 * if it will not host any local procs from within that
620 * nspace IF any local proc might at some point perform
621 * a collective operation involving one or more procs from
622 * that nspace. This is necessary so that the collective
623 * operation can know when it is locally complete.
624 *
625 * The caller must also provide the number of local procs
626 * that will be launched within this nspace. This is required
627 * for the PMIx server library to correctly handle collectives
628 * as a collective operation call can occur before all the
629 * procs have been started */
630 PMIX_EXPORT pmix_status_t PMIx_server_register_nspace(const pmix_nspace_t nspace, int nlocalprocs,
631 pmix_info_t info[], size_t ninfo,
632 pmix_op_cbfunc_t cbfunc, void *cbdata);
633
634 /* Deregister an nspace and purge all objects relating to
635 * it, including any client info from that nspace. This is
636 * intended to support persistent PMIx servers by providing
637 * an opportunity for the host RM to tell the PMIx server
638 * library to release all memory for a completed job */
639 PMIX_EXPORT void PMIx_server_deregister_nspace(const pmix_nspace_t nspace,
640 pmix_op_cbfunc_t cbfunc, void *cbdata);
641
642 /* Register a client process with the PMIx server library. The
643 * expected user ID and group ID of the child process helps the
644 * server library to properly authenticate clients as they connect
645 * by requiring the two values to match.
646 *
647 * The host server can also, if it desires, provide an object
648 * it wishes to be returned when a server function is called
649 * that relates to a specific process. For example, the host
650 * server may have an object that tracks the specific client.
651 * Passing the object to the library allows the library to
652 * return that object when the client calls "finalize", thus
653 * allowing the host server to access the object without
654 * performing a lookup. */
655 PMIX_EXPORT pmix_status_t PMIx_server_register_client(const pmix_proc_t *proc,
656 uid_t uid, gid_t gid,
657 void *server_object,
658 pmix_op_cbfunc_t cbfunc, void *cbdata);
659
660 /* Deregister a client and purge all data relating to it. The
661 * deregister_nspace API will automatically delete all client
662 * info for that nspace - this API is therefore intended solely
663 * for use in exception cases */
664 PMIX_EXPORT void PMIx_server_deregister_client(const pmix_proc_t *proc,
665 pmix_op_cbfunc_t cbfunc, void *cbdata);
666
667 /* Setup the environment of a child process to be forked
668 * by the host so it can correctly interact with the PMIx
669 * server. The PMIx client needs some setup information
670 * so it can properly connect back to the server. This function
671 * will set appropriate environmental variables for this purpose. */
672 PMIX_EXPORT pmix_status_t PMIx_server_setup_fork(const pmix_proc_t *proc, char ***env);
673
674 /* Define a callback function the PMIx server will use to return
675 * direct modex requests to the host server. The PMIx server
676 * will free the data blob upon return from the response fn */
677 typedef void (*pmix_dmodex_response_fn_t)(pmix_status_t status,
678 char *data, size_t sz,
679 void *cbdata);
680
681 /* Define a function by which the host server can request modex data
682 * from the local PMIx server. This is used to support the direct modex
683 * operation - i.e., where data is cached locally on each PMIx
684 * server for its own local clients, and is obtained on-demand
685 * for remote requests. Upon receiving a request from a remote
686 * server, the host server will call this function to pass the
687 * request into the PMIx server. The PMIx server will return a blob
688 * (once it becomes available) via the cbfunc - the host
689 * server shall send the blob back to the original requestor */
690 PMIX_EXPORT pmix_status_t PMIx_server_dmodex_request(const pmix_proc_t *proc,
691 pmix_dmodex_response_fn_t cbfunc,
692 void *cbdata);
693
694 /* define a callback function for the setup_application API. The returned info
695 * array is owned by the PMIx server library and will be free'd when the
696 * provided cbfunc is called. */
697 typedef void (*pmix_setup_application_cbfunc_t)(pmix_status_t status,
698 pmix_info_t info[], size_t ninfo,
699 void *provided_cbdata,
700 pmix_op_cbfunc_t cbfunc, void *cbdata);
701
702 /* Provide a function by which the resource manager can request
703 * any application-specific environmental variables, resource
704 * assignments, and/or other data prior to launch of an application.
705 * For example, network libraries may opt to provide security
706 * credentials for the application. This is defined as a non-blocking
707 * operation in case network libraries need to perform some action
708 * before responding. Any returned env will be distributed along
709 * with the application */
710 PMIX_EXPORT pmix_status_t PMIx_server_setup_application(const pmix_nspace_t nspace,
711 pmix_info_t info[], size_t ninfo,
712 pmix_setup_application_cbfunc_t cbfunc, void *cbdata);
713
714 /* Provide a function by which the local PMIx server can perform
715 * any application-specific operations prior to spawning local
716 * clients of a given application. For example, a network library
717 * might need to setup the local driver for "instant on" addressing.
718 * Data provided in the info array will be stored in the job-info
719 * region for the nspace. Operations included in the info array
720 * will be cached until the server calls PMIx_server_setup_fork,
721 * thereby indicating that local clients of this nspace will exist.
722 * Operations indicated by the provided data will only be executed
723 * for the first local client - i.e., they will only be executed
724 * once for a given nspace
725 */
726 PMIX_EXPORT pmix_status_t PMIx_server_setup_local_support(const pmix_nspace_t nspace,
727 pmix_info_t info[], size_t ninfo,
728 pmix_op_cbfunc_t cbfunc, void *cbdata);
729
730 /* Provide a function by which the host RM can pass forwarded IO
731 * to the local PMIx server for distribution to its clients. The
732 * PMIx server is responsible for determining which of its clients
733 * have actually registered for the provided data
734 *
735 * Parameters include:
736 *
737 * source - the process that provided the data being forwarded
738 *
739 * channel - the IOF channel (stdin, stdout, etc.)
740 *
741 * bo - a byte object containing the data
742 *
743 * info - an optional array of metadata describing the data, including
744 * attributes such as PMIX_IOF_COMPLETE to indicate that the
745 * source channel has been closed
746 *
747 * ninfo - number of elements in the info array
748 *
749 * cbfunc - a callback function to be executed once the provided data
750 * is no longer required. The host RM is required to retain
751 * the byte object until the callback is executed, or a
752 * non-success status is returned by the function
753 *
754 * cbdata - object pointer to be returned in the callback function
755 */
756 PMIX_EXPORT pmix_status_t PMIx_server_IOF_deliver(const pmix_proc_t *source,
757 pmix_iof_channel_t channel,
758 const pmix_byte_object_t *bo,
759 const pmix_info_t info[], size_t ninfo,
760 pmix_op_cbfunc_t cbfunc, void *cbdata);
761
762 /* Collect inventory of local resources. This is a non-blocking
763 * API as it may involve somewhat lengthy operations to obtain
764 * the requested information. Servers designated as "gateways"
765 * and whose plugins support collection of infrastructure info
766 * (e.g., switch and fabric topology, connectivity maps) shall
767 * return that information - plugins on non-gateway servers
768 * shall only return the node-local inventory. */
769 PMIX_EXPORT pmix_status_t PMIx_server_collect_inventory(pmix_info_t directives[], size_t ndirs,
770 pmix_info_cbfunc_t cbfunc, void *cbdata);
771
772 /* Deliver collected inventory for archiving by the corresponding
773 * plugins. Typically executed on a "gateway" associated with the
774 * system scheduler to enable use of inventory information by the
775 * the scheduling algorithm. May also be used on compute nodes to
776 * store a broader picture of the system for access by applications,
777 * if desired */
778 PMIX_EXPORT pmix_status_t PMIx_server_deliver_inventory(pmix_info_t info[], size_t ninfo,
779 pmix_info_t directives[], size_t ndirs,
780 pmix_op_cbfunc_t cbfunc, void *cbdata);
781
782 /****** ATTRIBUTE REGISTRATION ******/
783 /**
784 * This function is used by the host environment to register with its
785 * server library the attributes it supports for each pmix_server_module_t
786 * function.
787 *
788 * Parameters include:
789 *
790 * function - the string name of the server module function
791 * (e.g., "register_events", "validate_credential",
792 * or "allocate") whose attributes are being registered.
793 *
794 * attrs - array of pmix_regattr_t describing the attributes supported
795 * by the host environment for the specified function
796 *
797 * nattrs - number of elements in the attrs array
798 *
799 */
800 PMIX_EXPORT pmix_status_t PMIx_Register_attributes(char *function,
801 pmix_regattr_t attrs[], size_t nattrs);
802
803
804 #if defined(c_plusplus) || defined(__cplusplus)
805 }
806 #endif
807
808 #endif