File: docnotes

package info (click to toggle)
mpich 3.3-3
  • links: PTS, VCS
  • area: main
  • in suites: bullseye, buster, sid
  • size: 131,836 kB
  • sloc: ansic: 975,868; cpp: 57,437; f90: 53,762; perl: 19,562; xml: 12,464; sh: 12,303; fortran: 7,875; makefile: 7,078; ruby: 126; java: 100; python: 98; lisp: 19; php: 8; sed: 4
file content (559 lines) | stat: -rw-r--r-- 18,507 bytes parent folder | download
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
282
283
284
285
286
287
288
289
290
291
292
293
294
295
296
297
298
299
300
301
302
303
304
305
306
307
308
309
310
311
312
313
314
315
316
317
318
319
320
321
322
323
324
325
326
327
328
329
330
331
332
333
334
335
336
337
338
339
340
341
342
343
344
345
346
347
348
349
350
351
352
353
354
355
356
357
358
359
360
361
362
363
364
365
366
367
368
369
370
371
372
373
374
375
376
377
378
379
380
381
382
383
384
385
386
387
388
389
390
391
392
393
394
395
396
397
398
399
400
401
402
403
404
405
406
407
408
409
410
411
412
413
414
415
416
417
418
419
420
421
422
423
424
425
426
427
428
429
430
431
432
433
434
435
436
437
438
439
440
441
442
443
444
445
446
447
448
449
450
451
452
453
454
455
456
457
458
459
460
461
462
463
464
465
466
467
468
469
470
471
472
473
474
475
476
477
478
479
480
481
482
483
484
485
486
487
488
489
490
491
492
493
494
495
496
497
498
499
500
501
502
503
504
505
506
507
508
509
510
511
512
513
514
515
516
517
518
519
520
521
522
523
524
525
526
527
528
529
530
531
532
533
534
535
536
537
538
539
540
541
542
543
544
545
546
547
548
549
550
551
552
553
554
555
556
557
558
559
This file contains the named document blocks for use in generating the 
documentation.  This is divided into several main blocks:
   Threads and interrups/signals
   Fortran
   Misc MPI (e.g., status null)
   Error classes

-----------------------------------------------------------------------------
Note that only one of ThreadSafe and SignalSafe may be used
/*N ThreadSafe
   Thread and Interrupt Safety:

   This routine is thread-safe.  This means that this routine may be
   safely used by multiple threads without the need for any user-provided 
   thread locks.  However, the routine is not interrupt safe.  Typically, 
   this is due to the use of memory allocation routines such as 'malloc'
   or other non-MPICH runtime routines that are themselves not interrupt-safe.
N*/
/*N SignalSafe
   Thread and Interrupt Safety:

   This routine is both thread- and interrupt-safe. 
   This means that this routine may safely be used by multiple threads and
   from within a signal handler.   
N*/
/*N NotThreadSafe
   Thread and Interrupt Safety:

   The user is responsible for ensuring that multiple threads do not try to
   update the same MPI object from different threads.  This routine should 
   not be used from within a signal handler.

   The MPI standard defined a thread-safe interface but this does not 
   mean that all routines may be called without any thread locks.  For
   example, two threads must not attempt to change the contents of the
   same 'MPI_Info' object concurrently.  The user is responsible in this
   case for using some mechanism, such as thread locks, to ensure that 
   only one thread at a time makes use of this routine.  
N*/

Most of the MPI objects are static enough that it isn't necessary to
lock around the routines (even though some ops require updates).  Info isn't
expected to be as robust (there was discussion on the MPI-Forum list
on this). 

/*N ThreadSafeInfoRead

   Thread and Interrupt Safety:

   This routine is thread and interrupt safe only if no MPI routine that 
   updates or frees the same 'MPI_Info' object may be called concurrently 
   with this routine.

   The MPI standard defined a thread-safe interface but this does not 
   mean that all routines may be called without any thread locks.  For
   example, two threads must not attempt to change the contents of the
   same 'MPI_Info' object concurrently.  The user is responsible in this
   case for using some mechanism, such as thread locks, to ensure that 
   only one thread at a time makes use of this routine.  
N*/

/*N ThreadSafeNoUpdate

    Thread and Interrupt Safety:

   This routine is thread and interrupt safe only if no MPI routine that 
   updates or frees the same MPI object may be called concurrently 
   with this routine.

   The MPI standard defined a thread-safe interface but this does not 
   mean that all routines may be called without any thread locks.  For
   example, two threads must not attempt to change the contents of the
   same 'MPI_Info' object concurrently.  The user is responsible in this
   case for using some mechanism, such as thread locks, to ensure that 
   only one thread at a time makes use of this routine.  

N*/
-----------------------------------------------------------------------------
/*N Fortran
Notes for Fortran:
All MPI routines in Fortran (except for 'MPI_WTIME' and 'MPI_WTICK') have 
an additional argument 'ierr' at the end of the argument list.  'ierr'
is an integer and has the same meaning as the return value of the routine 
in C.  In Fortran, MPI routines are subroutines, and are invoked with the 
'call' statement.  

All MPI objects (e.g., 'MPI_Datatype', 'MPI_Comm') are of type 'INTEGER'
in Fortran.  
N*/

Try this as an alias
/*N fortran
.N Fortran
N*/

/*N FortranStatus
 The 'status' argument must be declared as an array of size 'MPI_STATUS_SIZE',
 as in 'integer status(MPI_STATUS_SIZE)'.
N*/

/*N FortStatusArray
 The 'status' argument must be declared as an array of sise 'MPI_STATUS_SIZE',
 as in 'integer status(MPI_STATUS_SIZE,10)' (assuming no more than 10 
 requests are provided as input).
N*/

/*N FortranString

 The sizes of MPI strings in Fortran are one less than the sizes of that 
 string in C/C++ because the C/C++ versions provide room for the trailing
 null character required by C/C++.  For example, 'MPI_MAX_ERROR_STRING' is 
 'mpif.h' is one smaller than the same value in 'mpi.h'.  See the MPI
 standard, sections 2.6.2 and 4.12.9.

N*/


-----------------------------------------------------------------------------
/*N collops
Notes on collective operations:

The reduction functions ('MPI_Op') do not return an error value.  As a result,
if the functions detect an error, all they can do is either call 'MPI_Abort'
or silently skip the problem.  Thus, if you change the error handler from
'MPI_ERRORS_ARE_FATAL' to something else, for example, 'MPI_ERRORS_RETURN', 
then no error may be indicated.

The reason for this is the performance problems in ensuring that 
all collective routines return the same error value.
N*/

/*N waitstatus
 Notes on the MPI_Status argument:

 The 'MPI_ERROR' field of the status return is only set if 
 the return from the MPI routine is 'MPI_ERR_IN_STATUS'.  That error class
 is only returned by the routines that take an array of status arguments
 ('MPI_Testall', 'MPI_Testsome', 'MPI_Waitall', and 'MPI_Waitsome').  In
 all other cases, the value of the 'MPI_ERROR' field in the status is
 unchanged.  See section 3.2.5 in the MPI-1.1 specification for the 
 exact text.

 For send operations, the only use of status is for 'MPI_Test_cancelled' or
 in the case that there is an error in one of the four routines that 
 may return the error class 'MPI_ERR_IN_STATUS', in which case the 
 'MPI_ERROR' field of status will be set.  In that case, the value 
 will be set to 'MPI_SUCCESS' for any send or receive operation that completed
 successfully, or 'MPI_ERR_PENDING' for any operation which has neither
 failed nor completed.
N*/

-----------------------------------------------------------------------------
MPI-2 deprecated some routines (see 2.6.1)
/*N Deprecated
 Deprecated Function:
 The MPI-2 standard deprecated a number of routines because MPI-2 provides
 better versions.  This routine is one of those that was deprecated.  The
 routine may continue to be used, but new code should use the replacement
 routine.
N*/
-----------------------------------------------------------------------------
/*N Errhandler
    Error handlers:
    The MPI error handler for this routine is taken from 'MPI_COMM_WORLD'.
    For MPI routines that do not have an obvious communicator, file, or
    window object, the MPI standard specifies that the error handler 
    attached to 'MPI_COMM_WORLD' be used.
N*/
-----------------------------------------------------------------------------

This part of the file contains definitions of the MPI error CLASSES for
inclusion in the man pages.  Use .N err name

/*N Errors
Errors:

 All MPI routines (except 'MPI_Wtime' and 'MPI_Wtick') return an error value; 
 C routines as the value of the function and Fortran routines in the last 
 argument.  Before the value is returned, the current MPI error handler is
 called.  By default, this error handler aborts the MPI job.  The error handler
 may be changed with 'MPI_Comm_set_errhandler' (for communicators), 
 'MPI_File_set_errhandler' (for files), and 'MPI_Win_set_errhandler' (for
 RMA windows).  The MPI-1 routine 'MPI_Errhandler_set' may be used but
 its use is deprecated.  The predefined error handler 
 'MPI_ERRORS_RETURN' may be used to cause error values to be returned.
 Note that MPI does `not` guarentee that an MPI program can continue past
 an error; however, MPI implementations will attempt to continue whenever
 possible.

N*/
/*N MPI_SUCCESS
. MPI_SUCCESS - No error; MPI routine completed successfully.
N*/
/*N MPI_ERR_BUFFER
. MPI_ERR_BUFFER - Invalid buffer pointer.  Usually a null buffer where
  one is not valid.
N*/
/*N MPI_ERR_COUNT
. MPI_ERR_COUNT - Invalid count argument.  Count arguments must be 
  non-negative; a count of zero is often valid.
N*/
/*N MPI_ERR_TYPE
. MPI_ERR_TYPE - Invalid datatype argument.  Additionally, this error can
  occur if an uncommitted MPI_Datatype (see 'MPI_Type_commit') is used
  in a communication call.
N*/
/*N MPI_ERR_TAG
.  MPI_ERR_TAG - Invalid tag argument.  Tags must be non-negative; tags
   in a receive ('MPI_Recv', 'MPI_Irecv', 'MPI_Sendrecv', etc.) may
   also be 'MPI_ANY_TAG'.  The largest tag value is available through the 
   the attribute 'MPI_TAG_UB'.
N*/
/*N MPI_ERR_COMM
. MPI_ERR_COMM - Invalid communicator.  A common error is to use a null
  communicator in a call (not even allowed in 'MPI_Comm_rank').
N*/
/*N MPI_ERR_RANK
. MPI_ERR_RANK - Invalid source or destination rank.  Ranks must be between
  zero and the size of the communicator minus one; ranks in a receive
  ('MPI_Recv', 'MPI_Irecv', 'MPI_Sendrecv', etc.) may also be 'MPI_ANY_SOURCE'.
N*/
/*N MPI_ERR_ROOT
. MPI_ERR_ROOT - Invalid root.  The root must be specified as a rank in the
  communicator.  Ranks must be between zero and the size of the communicator 
  minus one.
N*/
/*N MPI_ERR_GROUP
. MPI_ERR_GROUP - Null or invalid group passed to function.  
N*/
/*N MPI_ERR_OP
. MPI_ERR_OP - Invalid operation.  MPI operations (objects of type 'MPI_Op')
  must either be one of the predefined operations (e.g., 'MPI_SUM') or
  created with 'MPI_Op_create'.
N*/
/*N MPI_ERR_TOPOLOGY
. MPI_ERR_TOPOLOGY - Invalid topology.  Either there is no topology 
  associated with this communicator, or it is not the correct type (e.g.,
  'MPI_CART' when expecting 'MPI_GRAPH').
N*/
/*N MPI_ERR_DIMS
. MPI_ERR_DIMS - Invalid dimension argument.  A dimension argument
  is null or its length is less than or equal to zero.
N*/
/*N MPI_ERR_ARG
. MPI_ERR_ARG - Invalid argument.  Some argument is invalid and is not
  identified by a specific error class (e.g., 'MPI_ERR_RANK').
N*/
/*N MPI_ERR_PERM_OP
. MPI_ERR_ARG - Invalid argument; the error code associated with this
  error indicates an attempt to free an MPI permanent operation (e.g., 
  'MPI_SUM').
N*/
/*N MPI_ERR_PERM_KEY
. MPI_ERR_ARG - Invalid argument; the error code associated with this
  error indicates an attempt to free or chnage an MPI permanent keyval (e.g., 
  'MPI_TAG_UB').
N*/
/*N MPI_ERR_UNKNOWN
. MPI_ERR_UNKNOWN - Unknown error.  You should never see this.  If you
  do, report it to 'mpi-bugs@mcs.anl.gov'.
N*/
/*N MPI_ERR_TRUNCATE
. MPI_ERR_TRUNCATE - Message truncated on receive.  The buffer size specified
  was too small for the received message.  This is a recoverable error in
  the MPICH implementation.
N*/
/*N MPI_ERR_OTHER
. MPI_ERR_OTHER - Other error; use 'MPI_Error_string' to get more information
  about this error code. 
N*/
/*N MPI_ERR_KEYVAL
. MPI_ERR_KEYVAL - Invalid keyval
N*/
/*N MPI_ERR_INTERN
.  MPI_ERR_INTERN - An internal error has been detected.  This is fatal.
   Please send a bug report to 'mpi-bugs@mcs.anl.gov'.
N*/
/*N MPI_ERR_EXHAUSTED
.   MPI_ERR_INTERN - This error is returned when some part of the MPICH 
    implementation is unable to acquire memory.  
N*/
/*N MPI_ERR_IN_STATUS
. MPI_ERR_IN_STATUS - The actual error value is in the 'MPI_Status' argument.
  This error class is returned only from the multiple-completion routines
  ('MPI_Testall', 'MPI_Testany', 'MPI_Testsome', 'MPI_Waitall', 'MPI_Waitany',
  and 'MPI_Waitsome').  The field 'MPI_ERROR' in the status argument
  contains the error value or 'MPI_SUCCESS' (no error and complete) or
  'MPI_ERR_PENDING' to indicate that the request has not completed.
  
  The MPI Standard does not specify what the result of the multiple 
  completion routines is when an error occurs.  For example, in an 
  'MPI_WAITALL', does the routine wait for all requests to either fail or
  complete, or does it return immediately (with the MPI definition of 
  immediately, which means independent of actions of other MPI processes)?
  MPICH has chosen to make the return immediate (alternately, local in MPI 
  terms), and to use the error class 'MPI_ERR_PENDING' (introduced in MPI 1.1)
  to indicate which requests have not completed.  In most cases, only
  one request with an error will be detected in each call to an MPI routine
  that tests multiple requests.  The requests that have not been processed
  (because an error occured in one of the requests) will have their
  'MPI_ERROR' field marked with 'MPI_ERR_PENDING'.
N*/
/*N MPI_ERR_PENDING
. MPI_ERR_PENDING - Pending request (not an error).  See 'MPI_ERR_IN_STATUS'. 
  This value indicates that the request is not complete nor has a encountered
  a detected error.  
N*/
/*N MPI_ERR_REQUEST
. MPI_ERR_REQUEST - Invalid 'MPI_Request'.  Either null or, in the case of a
  'MPI_Start' or 'MPI_Startall', not a persistent request.
N*/
/*N MPI_ERR_BUFFER_ALIAS
.   MPI_ERR_BUFFER - This error class is associcated with an error code that
    indicates that two buffer arguments are `aliased`; that is, the 
    describe overlapping storage (often the exact same storage).  This
    is prohibited in MPI (because it is prohibited by the Fortran 
    standard, and rather than have a separate case for C and Fortran, the
    MPI Forum adopted the more restrictive requirements of Fortran).
N*/

/*N MPI_ERR_PERM_KEY
. MPI_ERR_ARG - This error class is associated with an error code that 
  indicates that an attempt was made to free one of the permanent keys.
N*/

/*N MPI_ERR_PERM_GROUP
. MPI_ERR_ARG - This error class is associated with an error code that 
  indicates that an attempt was made to free one of the permanent groups.
N*/

/*N MPI_ERR_INIT
. MPI_ERR_OTHER - This error class is associated with an error code that 
  indicates that an attempt was made to call 'MPI_INIT' a second time.
  'MPI_INIT' may only be called once in a program.
N*/

/*N MPI_ERR_INFO
. MPI_ERR_INFO - Invalid Info 
N*/

/*N MPI_ERR_INFO_KEY  
. MPI_ERR_INFO_KEY - Invalid or null key string for info.
N*/

/*N MPI_ERR_INFO_VALUE
. MPI_ERR_INFO_VALUE - Invalid or null value string for info
N*/

/*N MPI_ERR_INFO_NOKEY 
. MPI_ERR_INFO_NOKEY - 
N*/

/*N MPI_ERR_NAME
. MPI_ERR_NAME - 
N*/

/*N MPI_ERR_NO_MEM
. MPI_ERR_NO_MEM - Insufficient memory available for allocation by 
  'MPI_Alloc_mem'
N*/

/*N MPI_ERR_NOT_SAME
. MPI_ERR_NOT_SAME - 
N*/

/*N MPI_ERR_PORT
. MPI_ERR_PORT -
N*/

/*N MPI_ERR_QUOTA
. MPI_ERR_QUOTA - 
N*/

/*N MPI_ERR_SERVICE
. MPI_ERR_SERVICE - 
N*/

/*N MPI_ERR_SPAWN
. MPI_ERR_SPAWN -
N*/

/*N MPI_ERR_UNSUPPORTED_OPERATION
. MPI_ERR_UNSUPPORTED_OPERATION - 
N*/

/*N MPI_ERR_WIN
. MPI_ERR_WIN - Invalid MPI window object
N*/

/*N MPI_ERR_BASE
. MPI_ERR_BASE - 
N*/

/*N MPI_ERR_LOCKTYPE
. MPI_ERR_LOCKTYPE - 
N*/

/*N MPI_ERR_RMA_CONFLICT
. MPI_ERR_RMA_CONFLICT - 
N*/

/*N MPI_ERR_RMA_SYNC
. MPI_ERR_RMA_SYNC -
N*/

/*N MPI_ERR_SIZE
. MPI_ERR_SIZE - 
N*/

/*N MPI_ERR_DISP
. MPI_ERR_DISP - 
N*/

/*N MPI_ERR_ASSERT
. MPI_ERR_ASSERT - 
N*/

/* MPI I/O Information */
/*N MPI_ERR_FILE
. MPI_ERR_FILE - Invalid MPI File handle
N*/

/*N MPI_ERR_ACCESS
. MPI_ERR_ACCESS -
N*/

/*N MPI_ERR_AMODE
. MPI_ERR_AMODE - 
N*/

/*N MPI_ERR_BAD_FILE
. MPI_ERR_BAD_FILE - 
N*/

/*N MPI_ERR_FILE_EXISTS
. MPI_ERR_FILE_EXISTS - 
N*/

/*N MPI_ERR_FILE_IN_USE
. MPI_ERR_FILE_IN_USE - 
N*/

/*N MPI_ERR_NO_SPACE
. MPI_ERR_NO_SPACE - 
N*/

/*N MPI_ERR_NO_SUCH_FILE
. MPI_ERR_NO_SUCH_FILE - 
N*/

/*N MPI_ERR_IO
. MPI_ERR_IO - 
N*/

/*N MPI_ERR_READ_ONLY
. MPI_ERR_READ_ONLY - 
N*/

/*N MPI_ERR_CONVERSION
. MPI_ERR_CONVERSION - 
N*/

/*N MPI_ERR_DUP_DATAREP
. MPI_ERR_DUP_DATAREP - 
N*/

/*N MPI_ERR_UNSUPPORTED_DATAREP
. MPI_ERR_UNSUPPORTED_DATAREP - 
N*/

/*N MPI_T_ERR_NOT_INITIALIZED
. MPI_T_ERR_NOT_INITIALIZED - The MPI tool information interface is not initialized.
N*/

/*N MPI_T_ERR_MEMORY
. MPI_T_ERR_MEMORY - The MPI tool information interface is out of memory.
N*/

/*N MPI_T_ERR_CANNOT_INIT
. MPI_T_ERR_CANNOT_INIT - The MPI tool information interface is not in the state to be initialized.
N*/

/*N MPI_T_ERR_INVALID_INDEX
. MPI_T_ERR_INVALID_INDEX - Index is invalid or has been deleted.
N*/

/*N MPI_T_ERR_INVALID_ITEM
. MPI_T_ERR_INVALID_ITEM - Item index queried is out of range.
N*/

/*N MPI_T_ERR_INVALID_NAME
. MPI_T_ERR_INVALID_NAME - The variable or category name is invalid
N*/

/*N MPI_T_ERR_INVALID_HANDLE
. MPI_T_ERR_INVALID_HANDLE - The handle is invalid.
N*/

/*N MPI_T_ERR_OUT_OF_HANDLES
. MPI_T_ERR_OUT_OF_HANDLES - No more handles available.
N*/

/*N MPI_T_ERR_OUT_OF_SESSIONS
. MPI_T_ERR_OUT_OF_SESSIONS - No more sessions available.
N*/

/*N MPI_T_ERR_INVALID_SESSION
. MPI_T_ERR_INVALID_SESSION - Session argument is not valid.
N*/

/*N MPI_T_ERR_CVAR_SET_NOT_NOW
. MPI_T_ERR_CVAR_SET_NOT_NOW - The control variable can not be set at this moment.
N*/

/*N MPI_T_ERR_CVAR_SET_NEVER
. MPI_T_ERR_CVAR_SET_NEVER -  The control variable can not be set until end of execution.
N*/

/*N MPI_T_ERR_PVAR_NO_STARTSTOP
. MPI_T_ERR_PVAR_NO_STARTSTOP - The performance variable can not be started or stopped.
N*/

/*N MPI_T_ERR_PVAR_NO_WRITE
. MPI_T_ERR_PVAR_NO_WRITE - The performance variable can not be written or reset.
N*/

/*N MPI_T_ERR_PVAR_NO_ATOMIC
. MPI_T_ERR_PVAR_NO_ATOMIC - The performance variable can not be read/write atomically.
N*/

/*N NULL
Null Handles:
The MPI 1.1 specification, in the section on opaque objects, explicitly
disallows freeing a null communicator.  The text from the standard is\:
.vb
 A null handle argument is an erroneous IN argument in MPI calls, unless an
 exception is explicitly stated in the text that defines the function. Such
 exception is allowed for handles to request objects in Wait and Test calls
 (sections Communication Completion and Multiple Completions ). Otherwise, a
 null handle can only be passed to a function that allocates a new object and
 returns a reference to it in the handle.
.ve
N*/

/*N COMMNULL
 Because MPI specifies that null objects (e.g., 'MPI_COMM_NULL') are invalid
 as input to MPI routines unless otherwise specified, using 'MPI_COMM_NULL'
 as input to this routine is an error.
N*/

/*N AttrErrReturn
 
 Return value from attribute callbacks:
 The MPI-2 versions of the attribute callbacks should return either 
 'MPI_SUCCESS' on success or a valid MPI error code or class on failure.
 The MPI standard is ambiguous on this point, but as MPI-2 provides
 the routines 'MPI_Add_error_class' and 'MPI_Add_error_code' that allow the
 user to define and use MPI error codes and classes.
N*/