1 /*****************************************************************************\
2 * pmi.h - Process Management Interface for MPICH2
3 * See http://www-unix.mcs.anl.gov/mpi/mpich2/
4 *
5 * NOTE: Dynamic Process Management functions (PMI part 2) are not supported
6 * at this time. Functions required for MPI-1 (PMI part 1) are supported.
7 *****************************************************************************
8 * COPYRIGHT
9 *
10 * The following is a notice of limited availability of the code, and
11 * disclaimer which must be included in the prologue of the code and in all
12 * source listings of the code.
13 *
14 * Copyright Notice + 2002 University of Chicago
15 *
16 * Permission is hereby granted to use, reproduce, prepare derivative
17 * works, and to redistribute to others. This software was authored by:
18 *
19 * Argonne National Laboratory Group
20 * W. Gropp: (630) 252-4318; FAX: (630) 252-5986; e-mail: gropp@mcs.anl.gov
21 * E. Lusk: (630) 252-7852; FAX: (630) 252-5986; e-mail: lusk@mcs.anl.gov
22 * Mathematics and Computer Science Division Argonne National Laboratory,
23 * Argonne IL 60439
24 *
25 * GOVERNMENT LICENSE
26 *
27 * Portions of this material resulted from work developed under a U.S.
28 * Government Contract and are subject to the following license: the
29 * Government is granted for itself and others acting on its behalf a
30 * paid-up, nonexclusive, irrevocable worldwide license in this computer
31 * software to reproduce, prepare derivative works, and perform publicly
32 * and display publicly.
33 *
34 * DISCLAIMER
35 *
36 * This computer code material was prepared, in part, as an account of work
37 * sponsored by an agency of the United States Government. Neither the
38 * United States, nor the University of Chicago, nor any of their
39 * employees, makes any warranty express or implied, or assumes any legal
40 * liability or responsibility for the accuracy, completeness, or
41 * usefulness of any information, apparatus, product, or process disclosed,
42 * or represents that its use would not infringe privately owned rights.
43 *
44 * MCS Division <http://www.mcs.anl.gov> Argonne National Laboratory
45 * <http://www.anl.gov> University of Chicago <http://www.uchicago.edu>
46 \*****************************************************************************/
47
48 #ifndef PMI_H
49 #define PMI_H
50
51 /* Structure and constant definitions */
52 #include <pmix_common.h>
53
54 /* prototypes for the PMI interface in MPICH2 */
55
56 #if defined(__cplusplus)
57 extern "C" {
58 #endif
59
60 /*D
61 PMI_CONSTANTS - PMI definitions
62
63 Error Codes:
64 + PMI_SUCCESS - operation completed successfully
65 . PMI_FAIL - operation failed
66 . PMI_ERR_NOMEM - input buffer not large enough
67 . PMI_ERR_INIT - PMI not initialized
68 . PMI_ERR_INVALID_ARG - invalid argument
69 . PMI_ERR_INVALID_KEY - invalid key argument
70 . PMI_ERR_INVALID_KEY_LENGTH - invalid key length argument
71 . PMI_ERR_INVALID_VAL - invalid val argument
72 . PMI_ERR_INVALID_VAL_LENGTH - invalid val length argument
73 . PMI_ERR_INVALID_LENGTH - invalid length argument
74 . PMI_ERR_INVALID_NUM_ARGS - invalid number of arguments
75 . PMI_ERR_INVALID_ARGS - invalid args argument
76 . PMI_ERR_INVALID_NUM_PARSED - invalid num_parsed length argument
77 . PMI_ERR_INVALID_KEYVALP - invalid keyvalp argument
78 - PMI_ERR_INVALID_SIZE - invalid size argument
79
80 Booleans:
81 + PMI_TRUE - true
82 - PMI_FALSE - false
83
84 D*/
85 #define PMI_SUCCESS 0
86 #define PMI_FAIL -1
87 #define PMI_ERR_INIT 1
88 #define PMI_ERR_NOMEM 2
89 #define PMI_ERR_INVALID_ARG 3
90 #define PMI_ERR_INVALID_KEY 4
91 #define PMI_ERR_INVALID_KEY_LENGTH 5
92 #define PMI_ERR_INVALID_VAL 6
93 #define PMI_ERR_INVALID_VAL_LENGTH 7
94 #define PMI_ERR_INVALID_LENGTH 8
95 #define PMI_ERR_INVALID_NUM_ARGS 9
96 #define PMI_ERR_INVALID_ARGS 10
97 #define PMI_ERR_INVALID_NUM_PARSED 11
98 #define PMI_ERR_INVALID_KEYVALP 12
99 #define PMI_ERR_INVALID_SIZE 13
100 #define PMI_ERR_INVALID_KVS 14
101
102 typedef int PMI_BOOL;
103 #define PMI_TRUE 1
104 #define PMI_FALSE 0
105
106 /* PMI Group functions */
107
108 /*@
109 PMI_Init - initialize the Process Manager Interface
110
111 Output Parameter:
112 . spawned - spawned flag
113
114 Return values:
115 + PMI_SUCCESS - initialization completed successfully
116 . PMI_ERR_INVALID_ARG - invalid argument
117 - PMI_FAIL - initialization failed
118
119 Notes:
120 Initialize PMI for this process group. The value of spawned indicates whether
121 this process was created by 'PMI_Spawn_multiple'. 'spawned' will be 'PMI_TRUE' if
122 this process group has a parent and 'PMI_FALSE' if it does not.
123
124 @*/
125 PMIX_EXPORT int PMI_Init( int *spawned );
126
127 /*@
128 PMI_Initialized - check if PMI has been initialized
129
130 Output Parameter:
131 . initialized - boolean value
132
133 Return values:
134 + PMI_SUCCESS - initialized successfully set
135 . PMI_ERR_INVALID_ARG - invalid argument
136 - PMI_FAIL - unable to set the variable
137
138 Notes:
139 On successful output, initialized will either be 'PMI_TRUE' or 'PMI_FALSE'.
140
141 + PMI_TRUE - initialize has been called.
142 - PMI_FALSE - initialize has not been called or previously failed.
143
144 @*/
145 PMIX_EXPORT int PMI_Initialized( PMI_BOOL *initialized );
146
147 /*@
148 PMI_Finalize - finalize the Process Manager Interface
149
150 Return values:
151 + PMI_SUCCESS - finalization completed successfully
152 - PMI_FAIL - finalization failed
153
154 Notes:
155 Finalize PMI for this process group.
156
157 @*/
158 PMIX_EXPORT int PMI_Finalize( void );
159
160 /*@
161 PMI_Get_size - obtain the size of the process group
162
163 Output Parameters:
164 . size - pointer to an integer that receives the size of the process group
165
166 Return values:
167 + PMI_SUCCESS - size successfully obtained
168 . PMI_ERR_INVALID_ARG - invalid argument
169 - PMI_FAIL - unable to return the size
170
171 Notes:
172 This function returns the size of the process group to which the local process
173 belongs.
174
175 @*/
176 PMIX_EXPORT int PMI_Get_size( int *size );
177
178 /*@
179 PMI_Get_rank - obtain the rank of the local process in the process group
180
181 Output Parameters:
182 . rank - pointer to an integer that receives the rank in the process group
183
184 Return values:
185 + PMI_SUCCESS - rank successfully obtained
186 . PMI_ERR_INVALID_ARG - invalid argument
187 - PMI_FAIL - unable to return the rank
188
189 Notes:
190 This function returns the rank of the local process in its process group.
191
192 @*/
193 PMIX_EXPORT int PMI_Get_rank( int *rank );
194
195 /*@
196 PMI_Get_universe_size - obtain the universe size
197
198 Output Parameters:
199 . size - pointer to an integer that receives the size
200
201 Return values:
202 + PMI_SUCCESS - size successfully obtained
203 . PMI_ERR_INVALID_ARG - invalid argument
204 - PMI_FAIL - unable to return the size
205
206
207 @*/
208 PMIX_EXPORT int PMI_Get_universe_size( int *size );
209
210 /*@
211 PMI_Get_appnum - obtain the application number
212
213 Output parameters:
214 . appnum - pointer to an integer that receives the appnum
215
216 Return values:
217 + PMI_SUCCESS - appnum successfully obtained
218 . PMI_ERR_INVALID_ARG - invalid argument
219 - PMI_FAIL - unable to return the size
220
221
222 @*/
223 PMIX_EXPORT int PMI_Get_appnum( int *appnum );
224
225 /*@
226 PMI_Publish_name - publish a name
227
228 Input parameters:
229 . service_name - string representing the service being published
230 . port - string representing the port on which to contact the service
231
232 Return values:
233 + PMI_SUCCESS - port for service successfully published
234 . PMI_ERR_INVALID_ARG - invalid argument
235 - PMI_FAIL - unable to publish service
236
237
238 @*/
239 PMIX_EXPORT int PMI_Publish_name( const char service_name[], const char port[] );
240
241 /*@
242 PMI_Unpublish_name - unpublish a name
243
244 Input parameters:
245 . service_name - string representing the service being unpublished
246
247 Return values:
248 + PMI_SUCCESS - port for service successfully published
249 . PMI_ERR_INVALID_ARG - invalid argument
250 - PMI_FAIL - unable to unpublish service
251
252
253 @*/
254 PMIX_EXPORT int PMI_Unpublish_name( const char service_name[] );
255
256 /*@
257 PMI_Lookup_name - lookup a service by name
258
259 Input parameters:
260 . service_name - string representing the service being published
261
262 Output parameters:
263 . port - string representing the port on which to contact the service
264
265 Return values:
266 + PMI_SUCCESS - port for service successfully obtained
267 . PMI_ERR_INVALID_ARG - invalid argument
268 - PMI_FAIL - unable to lookup service
269
270
271 @*/
272 PMIX_EXPORT int PMI_Lookup_name( const char service_name[], char port[] );
273
274 /*@
275 PMI_Get_id - obtain the id of the process group
276
277 Input Parameter:
278 . length - length of the id_str character array
279
280 Output Parameter:
281 . id_str - character array that receives the id of the process group
282
283 Return values:
284 + PMI_SUCCESS - id successfully obtained
285 . PMI_ERR_INVALID_ARG - invalid rank argument
286 . PMI_ERR_INVALID_LENGTH - invalid length argument
287 - PMI_FAIL - unable to return the id
288
289 Notes:
290 This function returns a string that uniquely identifies the process group
291 that the local process belongs to. The string passed in must be at least
292 as long as the number returned by 'PMI_Get_id_length_max()'.
293
294 @*/
295 PMIX_EXPORT int PMI_Get_id( char id_str[], int length );
296
297 /*@
298 PMI_Get_kvs_domain_id - obtain the id of the PMI domain
299
300 Input Parameter:
301 . length - length of id_str character array
302
303 Output Parameter:
304 . id_str - character array that receives the id of the PMI domain
305
306 Return values:
307 + PMI_SUCCESS - id successfully obtained
308 . PMI_ERR_INVALID_ARG - invalid argument
309 . PMI_ERR_INVALID_LENGTH - invalid length argument
310 - PMI_FAIL - unable to return the id
311
312 Notes:
313 This function returns a string that uniquely identifies the PMI domain
314 where keyval spaces can be shared. The string passed in must be at least
315 as long as the number returned by 'PMI_Get_id_length_max()'.
316
317 @*/
318 PMIX_EXPORT int PMI_Get_kvs_domain_id( char id_str[], int length );
319
320 /*@
321 PMI_Get_id_length_max - obtain the maximum length of an id string
322
323 Output Parameters:
324 . length - the maximum length of an id string
325
326 Return values:
327 + PMI_SUCCESS - length successfully set
328 . PMI_ERR_INVALID_ARG - invalid argument
329 - PMI_FAIL - unable to return the maximum length
330
331 Notes:
332 This function returns the maximum length of a process group id string.
333
334 @*/
335 PMIX_EXPORT int PMI_Get_id_length_max( int *length );
336
337 /*@
338 PMI_Barrier - barrier across the process group
339
340 Return values:
341 + PMI_SUCCESS - barrier successfully finished
342 - PMI_FAIL - barrier failed
343
344 Notes:
345 This function is a collective call across all processes in the process group
346 the local process belongs to. It will not return until all the processes
347 have called 'PMI_Barrier()'.
348
349 @*/
350 PMIX_EXPORT int PMI_Barrier( void );
351
352 /*@
353 PMI_Get_clique_size - obtain the number of processes on the local node
354
355 Output Parameters:
356 . size - pointer to an integer that receives the size of the clique
357
358 Return values:
359 + PMI_SUCCESS - size successfully obtained
360 . PMI_ERR_INVALID_ARG - invalid argument
361 - PMI_FAIL - unable to return the clique size
362
363 Notes:
364 This function returns the number of processes in the local process group that
365 are on the local node along with the local process. This is a simple topology
366 function to distinguish between processes that can communicate through IPC
367 mechanisms (e.g., shared memory) and other network mechanisms.
368
369 @*/
370 PMIX_EXPORT int PMI_Get_clique_size( int *size );
371
372 /*@
373 PMI_Get_clique_ranks - get the ranks of the local processes in the process group
374
375 Input Parameters:
376 . length - length of the ranks array
377
378 Output Parameters:
379 . ranks - pointer to an array of integers that receive the local ranks
380
381 Return values:
382 + PMI_SUCCESS - ranks successfully obtained
383 . PMI_ERR_INVALID_ARG - invalid argument
384 . PMI_ERR_INVALID_LENGTH - invalid length argument
385 - PMI_FAIL - unable to return the ranks
386
387 Notes:
388 This function returns the ranks of the processes on the local node. The array
389 must be at least as large as the size returned by 'PMI_Get_clique_size()'. This
390 is a simple topology function to distinguish between processes that can
391 communicate through IPC mechanisms (e.g., shared memory) and other network
392 mechanisms.
393
394 @*/
395 PMIX_EXPORT int PMI_Get_clique_ranks( int ranks[], int length);
396
397 /*@
398 PMI_Abort - abort the process group associated with this process
399
400 Input Parameters:
401 + exit_code - exit code to be returned by this process
402 - error_msg - error message to be printed
403
404 Return values:
405 . none - this function should not return
406 @*/
407 PMIX_EXPORT int PMI_Abort(int exit_code, const char error_msg[]);
408
409 /* PMI Keymap functions */
410 /*@
411 PMI_KVS_Get_my_name - obtain the name of the keyval space the local process group has access to
412
413 Input Parameters:
414 . length - length of the kvsname character array
415
416 Output Parameters:
417 . kvsname - a string that receives the keyval space name
418
419 Return values:
420 + PMI_SUCCESS - kvsname successfully obtained
421 . PMI_ERR_INVALID_ARG - invalid argument
422 . PMI_ERR_INVALID_LENGTH - invalid length argument
423 - PMI_FAIL - unable to return the kvsname
424
425 Notes:
426 This function returns the name of the keyval space that this process and all
427 other processes in the process group have access to. The output parameter,
428 kvsname, must be at least as long as the value returned by
429 'PMI_KVS_Get_name_length_max()'.
430
431 @*/
432 PMIX_EXPORT int PMI_KVS_Get_my_name( char kvsname[], int length );
433
434 /*@
435 PMI_KVS_Get_name_length_max - obtain the length necessary to store a kvsname
436
437 Output Parameter:
438 . length - maximum length required to hold a keyval space name
439
440 Return values:
441 + PMI_SUCCESS - length successfully set
442 . PMI_ERR_INVALID_ARG - invalid argument
443 - PMI_FAIL - unable to set the length
444
445 Notes:
446 This function returns the string length required to store a keyval space name.
447
448 A routine is used rather than setting a maximum value in 'pmi.h' to allow
449 different implementations of PMI to be used with the same executable. These
450 different implementations may allow different maximum lengths; by using a
451 routine here, we can interface with a variety of implementations of PMI.
452
453 @*/
454 PMIX_EXPORT int PMI_KVS_Get_name_length_max( int *length );
455
456 /*@
457 PMI_KVS_Get_key_length_max - obtain the length necessary to store a key
458
459 Output Parameter:
460 . length - maximum length required to hold a key string.
461
462 Return values:
463 + PMI_SUCCESS - length successfully set
464 . PMI_ERR_INVALID_ARG - invalid argument
465 - PMI_FAIL - unable to set the length
466
467 Notes:
468 This function returns the string length required to store a key.
469
470 @*/
471 PMIX_EXPORT int PMI_KVS_Get_key_length_max( int *length );
472
473 /*@
474 PMI_KVS_Get_value_length_max - obtain the length necessary to store a value
475
476 Output Parameter:
477 . length - maximum length required to hold a keyval space value
478
479 Return values:
480 + PMI_SUCCESS - length successfully set
481 . PMI_ERR_INVALID_ARG - invalid argument
482 - PMI_FAIL - unable to set the length
483
484 Notes:
485 This function returns the string length required to store a value from a
486 keyval space.
487
488 @*/
489 PMIX_EXPORT int PMI_KVS_Get_value_length_max( int *length );
490
491 /*@
492 PMI_KVS_Create - create a new keyval space
493
494 Input Parameter:
495 . length - length of the kvsname character array
496
497 Output Parameters:
498 . kvsname - a string that receives the keyval space name
499
500 Return values:
501 + PMI_SUCCESS - keyval space successfully created
502 . PMI_ERR_INVALID_ARG - invalid argument
503 . PMI_ERR_INVALID_LENGTH - invalid length argument
504 - PMI_FAIL - unable to create a new keyval space
505
506 Notes:
507 This function creates a new keyval space. Everyone in the same process group
508 can access this keyval space by the name returned by this function. The
509 function is not collective. Only one process calls this function. The output
510 parameter, kvsname, must be at least as long as the value returned by
511 'PMI_KVS_Get_name_length_max()'.
512
513 @*/
514 PMIX_EXPORT int PMI_KVS_Create( char kvsname[], int length );
515
516 /*@
517 PMI_KVS_Destroy - destroy keyval space
518
519 Input Parameters:
520 . kvsname - keyval space name
521
522 Return values:
523 + PMI_SUCCESS - keyval space successfully destroyed
524 . PMI_ERR_INVALID_ARG - invalid argument
525 - PMI_FAIL - unable to destroy the keyval space
526
527 Notes:
528 This function destroys a keyval space created by 'PMI_KVS_Create()'.
529
530 @*/
531 PMIX_EXPORT int PMI_KVS_Destroy( const char kvsname[] );
532
533 /*@
534 PMI_KVS_Put - put a key/value pair in a keyval space
535
536 Input Parameters:
537 + kvsname - keyval space name
538 . key - key
539 - value - value
540
541 Return values:
542 + PMI_SUCCESS - keyval pair successfully put in keyval space
543 . PMI_ERR_INVALID_KVS - invalid kvsname argument
544 . PMI_ERR_INVALID_KEY - invalid key argument
545 . PMI_ERR_INVALID_VAL - invalid val argument
546 - PMI_FAIL - put failed
547
548 Notes:
549 This function puts the key/value pair in the specified keyval space. The
550 value is not visible to other processes until 'PMI_KVS_Commit()' is called.
551 The function may complete locally. After 'PMI_KVS_Commit()' is called, the
552 value may be retrieved by calling 'PMI_KVS_Get()'. All keys put to a keyval
553 space must be unique to the keyval space. You may not put more than once
554 with the same key.
555
556 @*/
557 PMIX_EXPORT int PMI_KVS_Put( const char kvsname[], const char key[], const char value[]);
558
559 /*@
560 PMI_KVS_Commit - commit all previous puts to the keyval space
561
562 Input Parameters:
563 . kvsname - keyval space name
564
565 Return values:
566 + PMI_SUCCESS - commit succeeded
567 . PMI_ERR_INVALID_ARG - invalid argument
568 - PMI_FAIL - commit failed
569
570 Notes:
571 This function commits all previous puts since the last 'PMI_KVS_Commit()' into
572 the specified keyval space. It is a process local operation.
573
574 @*/
575 PMIX_EXPORT int PMI_KVS_Commit( const char kvsname[] );
576
577 /*@
578 PMI_KVS_Get - get a key/value pair from a keyval space
579
580 Input Parameters:
581 + kvsname - keyval space name
582 . key - key
583 - length - length of value character array
584
585 Output Parameters:
586 . value - value
587
588 Return values:
589 + PMI_SUCCESS - get succeeded
590 . PMI_ERR_INVALID_KVS - invalid kvsname argument
591 . PMI_ERR_INVALID_KEY - invalid key argument
592 . PMI_ERR_INVALID_VAL - invalid val argument
593 . PMI_ERR_INVALID_LENGTH - invalid length argument
594 - PMI_FAIL - get failed
595
596 Notes:
597 This function gets the value of the specified key in the keyval space.
598
599 @*/
600 PMIX_EXPORT int PMI_KVS_Get( const char kvsname[], const char key[], char value[], int length);
601
602 /*@
603 PMI_KVS_Iter_first - initialize the iterator and get the first value
604
605 Input Parameters:
606 + kvsname - keyval space name
607 . key_len - length of key character array
608 - val_len - length of val character array
609
610 Output Parameters:
611 + key - key
612 - value - value
613
614 Return values:
615 + PMI_SUCCESS - keyval pair successfully retrieved from the keyval space
616 . PMI_ERR_INVALID_KVS - invalid kvsname argument
617 . PMI_ERR_INVALID_KEY - invalid key argument
618 . PMI_ERR_INVALID_KEY_LENGTH - invalid key length argument
619 . PMI_ERR_INVALID_VAL - invalid val argument
620 . PMI_ERR_INVALID_VAL_LENGTH - invalid val length argument
621 - PMI_FAIL - failed to initialize the iterator and get the first keyval pair
622
623 Notes:
624 This function initializes the iterator for the specified keyval space and
625 retrieves the first key/val pair. The end of the keyval space is specified
626 by returning an empty key string. key and val must be at least as long as
627 the values returned by 'PMI_KVS_Get_key_length_max()' and
628 'PMI_KVS_Get_value_length_max()'.
629
630 @*/
631 PMIX_EXPORT int PMI_KVS_Iter_first(const char kvsname[], char key[], int key_len, char val[], int val_len);
632
633 /*@
634 PMI_KVS_Iter_next - get the next keyval pair from the keyval space
635
636 Input Parameters:
637 + kvsname - keyval space name
638 . key_len - length of key character array
639 - val_len - length of val character array
640
641 Output Parameters:
642 + key - key
643 - value - value
644
645 Return values:
646 + PMI_SUCCESS - keyval pair successfully retrieved from the keyval space
647 . PMI_ERR_INVALID_KVS - invalid kvsname argument
648 . PMI_ERR_INVALID_KEY - invalid key argument
649 . PMI_ERR_INVALID_KEY_LENGTH - invalid key length argument
650 . PMI_ERR_INVALID_VAL - invalid val argument
651 . PMI_ERR_INVALID_VAL_LENGTH - invalid val length argument
652 - PMI_FAIL - failed to get the next keyval pair
653
654 Notes:
655 This function retrieves the next keyval pair from the specified keyval space.
656 'PMI_KVS_Iter_first()' must have been previously called. The end of the keyval
657 space is specified by returning an empty key string. The output parameters,
658 key and val, must be at least as long as the values returned by
659 'PMI_KVS_Get_key_length_max()' and 'PMI_KVS_Get_value_length_max()'.
660
661 @*/
662 PMIX_EXPORT int PMI_KVS_Iter_next(const char kvsname[], char key[], int key_len, char val[], int val_len);
663
664 /* PMI Process Creation functions */
665
666 /*S
667 PMI_keyval_t - keyval structure used by PMI_Spawn_mulitiple
668
669 Fields:
670 + key - name of the key
671 - val - value of the key
672
673 S*/
674 typedef struct PMI_keyval_t
675 {
676 char * key;
677 char * val;
678 } PMI_keyval_t;
679
680 /*@
681 PMI_Spawn_multiple - spawn a new set of processes
682
683 Input Parameters:
684 + count - count of commands
685 . cmds - array of command strings
686 . argvs - array of argv arrays for each command string
687 . maxprocs - array of maximum processes to spawn for each command string
688 . info_keyval_sizes - array giving the number of elements in each of the
689 'info_keyval_vectors'
690 . info_keyval_vectors - array of keyval vector arrays
691 . preput_keyval_size - Number of elements in 'preput_keyval_vector'
692 - preput_keyval_vector - array of keyvals to be pre-put in the spawned keyval space
693
694 Output Parameter:
695 . errors - array of errors for each command
696
697 Return values:
698 + PMI_SUCCESS - spawn successful
699 . PMI_ERR_INVALID_ARG - invalid argument
700 - PMI_FAIL - spawn failed
701
702 Notes:
703 This function spawns a set of processes into a new process group. The 'count'
704 field refers to the size of the array parameters - 'cmd', 'argvs', 'maxprocs',
705 'info_keyval_sizes' and 'info_keyval_vectors'. The 'preput_keyval_size' refers
706 to the size of the 'preput_keyval_vector' array. The 'preput_keyval_vector'
707 contains keyval pairs that will be put in the keyval space of the newly
708 created process group before the processes are started. The 'maxprocs' array
709 specifies the desired number of processes to create for each 'cmd' string.
710 The actual number of processes may be less than the numbers specified in
711 maxprocs. The acceptable number of processes spawned may be controlled by
712 ``soft'' keyvals in the info arrays. The ``soft'' option is specified by
713 mpiexec in the MPI-2 standard. Environment variables may be passed to the
714 spawned processes through PMI implementation specific 'info_keyval' parameters.
715 @*/
716 PMIX_EXPORT int PMI_Spawn_multiple(int count,
717 const char * cmds[],
718 const char ** argvs[],
719 const int maxprocs[],
720 const int info_keyval_sizesp[],
721 const PMI_keyval_t * info_keyval_vectors[],
722 int preput_keyval_size,
723 const PMI_keyval_t preput_keyval_vector[],
724 int errors[]);
725
726
727 /*@
728 PMI_Parse_option - create keyval structures from a single command line argument
729
730 Input Parameters:
731 + num_args - length of args array
732 - args - array of command line arguments starting with the argument to be parsed
733
734 Output Parameters:
735 + num_parsed - number of elements of the argument array parsed
736 . keyvalp - pointer to an array of keyvals
737 - size - size of the allocated array
738
739 Return values:
740 + PMI_SUCCESS - success
741 . PMI_ERR_INVALID_NUM_ARGS - invalid number of arguments
742 . PMI_ERR_INVALID_ARGS - invalid args argument
743 . PMI_ERR_INVALID_NUM_PARSED - invalid num_parsed length argument
744 . PMI_ERR_INVALID_KEYVALP - invalid keyvalp argument
745 . PMI_ERR_INVALID_SIZE - invalid size argument
746 - PMI_FAIL - fail
747
748 Notes:
749 This function removes one PMI specific argument from the command line and
750 creates the corresponding 'PMI_keyval_t' structure for it. It returns
751 an array and size to the caller. The array must be freed by 'PMI_Free_keyvals()'.
752 If the first element of the args array is not a PMI specific argument, the function
753 returns success and sets num_parsed to zero. If there are multiple PMI specific
754 arguments in the args array, this function may parse more than one argument as long
755 as the options are contiguous in the args array.
756
757 @*/
758 PMIX_EXPORT int PMI_Parse_option(int num_args, char *args[], int *num_parsed, PMI_keyval_t **keyvalp, int *size);
759
760 /*@
761 PMI_Args_to_keyval - create keyval structures from command line arguments
762
763 Input Parameters:
764 + argcp - pointer to argc
765 - argvp - pointer to argv
766
767 Output Parameters:
768 + keyvalp - pointer to an array of keyvals
769 - size - size of the allocated array
770
771 Return values:
772 + PMI_SUCCESS - success
773 . PMI_ERR_INVALID_ARG - invalid argument
774 - PMI_FAIL - fail
775
776 Notes:
777 This function removes PMI specific arguments from the command line and
778 creates the corresponding 'PMI_keyval_t' structures for them. It returns
779 an array and size to the caller that can then be passed to 'PMI_Spawn_multiple()'.
780 The array can be freed by 'PMI_Free_keyvals()'. The routine 'free()' should
781 not be used to free this array as there is no requirement that the array be
782 allocated with 'malloc()'.
783
784 @*/
785 PMIX_EXPORT int PMI_Args_to_keyval(int *argcp, char *((*argvp)[]), PMI_keyval_t **keyvalp, int *size);
786
787 /*@
788 PMI_Free_keyvals - free the keyval structures created by PMI_Args_to_keyval
789
790 Input Parameters:
791 + keyvalp - array of keyvals
792 - size - size of the array
793
794 Return values:
795 + PMI_SUCCESS - success
796 . PMI_ERR_INVALID_ARG - invalid argument
797 - PMI_FAIL - fail
798
799 Notes:
800 This function frees the data returned by 'PMI_Args_to_keyval' and 'PMI_Parse_option'.
801 Using this routine instead of 'free' allows the PMI package to track
802 allocation of storage or to use interal storage as it sees fit.
803 @*/
804 PMIX_EXPORT int PMI_Free_keyvals(PMI_keyval_t keyvalp[], int size);
805
806 /*@
807 PMI_Get_options - get a string of command line argument descriptions that may be printed to the user
808
809 Input Parameters:
810 . length - length of str
811
812 Output Parameters:
813 + str - description string
814 - length - length of string or necessary length if input is not large enough
815
816 Return values:
817 + PMI_SUCCESS - success
818 . PMI_ERR_INVALID_ARG - invalid argument
819 . PMI_ERR_INVALID_LENGTH - invalid length argument
820 . PMI_ERR_NOMEM - input length too small
821 - PMI_FAIL - fail
822
823 Notes:
824 This function returns the command line options specific to the pmi implementation
825 @*/
826 PMIX_EXPORT int PMI_Get_options(char *str, int *length);
827
828 #if defined(__cplusplus)
829 }
830 #endif
831
832 #endif