[Mpi-comments] Comments on MPI 3.0 draft 2 [part 5]

[Jeremiah Willcock]

These are in reference to the draft at 
<URL:http://meetings.mpi-forum.org/mpi3.0_draft_2.pdf>.  Thank you for 
considering them.

-- Jeremiah Willcock

Chapter 13:

Page 492 line 47: "8th" should be "eighth".

Page 492 line 48: Although "formal parameter" is the correct term 
normally, MPI typically uses "argument" to mean that.

Page 494 lines 11-21: Some of the example text in here might be worth 
putting in code font.

Page 494 line 31: Is MPI_MODE_RDWR intended to be equal to MPI_MODE_RDONLY 
| MPI_MODE_WRONLY?  If so, that will require changes in some of the nearby 
text.

Page 495 lines 11-12: Are there any guarantees about the behavior of 
MPI_MODE_DELETE_ON_CLOSE if the program exits (normally or abnormally) 
without explicitly closing the file?

Page 499 lines 44-45: Wouldn't using log on the bit to test and then mod 
and integer division on the amode be simpler than the loop? 
Floating-point errors might cause trouble there, however, or if one of the 
masks was not a single bit.

Page 500 line 36: "Section" should be "Chapter".

Page 501 line 20: There is an unnecessary line break at the end of the 
line.

Page 501 line 47: "pair" should be "pairs".

Page 502 line 3: The "and" might need to be changed to "or".

Page 502 line 12: "Section" should be "Chapter".

Page 502 line 34: Is there a reason that "CYCLIC" is all-uppercase?

Page 503 lines 22-23: Is this hint intended to say how many devices to 
use, not how many are in the system?

Page 505 lines 15, 25-28, and 32: "etype" and "filetype" should be in text 
font when they are not referring to specific argument names.

Page 505 line 30: There should be a comma after "etype".

Page 506 lines 30-33: Is there an easy way to tell that a datatype is 
derived?  Is the datatype returned, if derived, guaranteed to be new (and 
not, for example, one passed into MPI_FILE_SET_VIEW by the user)?

Page 506 lines 40-42: There is extra space after "vs." here (probably 
needs to be 'vs.\ ' in LaTeX).  I don't remember whether vs is italicized 
elsewhere in the standard.

Page 506 line 44: The POSIX function names might need to be in code font.

Page 507 line 25: The em-dash should have spaces around it to match the 
rest of the standard.  This issue may occur elsewhere in the chapter as 
well.

Page 508 line 3: "in to" should be "into".

Page 508 lines 9-11: Does that mean a buffer being written to a file can't 
be concurrently sent?  It seems like that restriction may be too strong, 
especially when you can use a datatype to write the same data to a file 
more than once in a single operation.

Page 509 lines 8-12: The section titles should be in the normal text font, 
the commas and final period should be inside the quotes, and there needs 
to be a comma after "Temporary Data Movements".

Page 509 line 18: The fields in MPI_Status are referred to in sans-serif 
on page 30 where they are introduced.

Page 520 lines 30-31: Do all processes need to use equivalent views of the 
file to use the shared file pointer?  If not, what is the file pointer 
relative to (i.e., if I read using it in a process with one view, then 
read using it in a process with a different view, what happens)?

Pages 524-525: Are MPI_FILE_SEEK_SHARED and/or 
MPI_FILE_GET_POSITION_SHARED collective?

Page 534 line 24: "of the MPI-1 document" should be removed, and "page" 
should be "pages".

Page 536 line 26: There should be a comma after "8".

Page 536 line 30: This list should also include the C++ bool type now that 
there is an MPI datatype for it.

Page 536 line 31: There should be a comma after "double _Complex".  This 
list should include the C++ complex types.  In what order do the real and 
imaginary components appear in the file?

Page 536 lines 34-35: Unicode has several encoding formats; which one are 
you intending (UTF-7, UTF-8, UTF-16, UCS-16, UCS-32, or something else)?

Page 537 line 5: "size" should be "sizes".

Page 537 line 10: "less" should be "least".

Page 537 lines 9-12: Some of this information (what happens on overflows 
from down-converting number formats, for example) is normative and should 
be in the main text.  Also, taking the least-significant bytes of a larger 
number does not always preserve the sign bit in case of overflows 
(converting the MPI_INT 32768 to an MPI_INTEGER2 leads to -32768, for 
example).  Is making sure to preserve the sign bit always the intended 
behavior?

Page 538 line 9: Defining wchar as two bytes prevents it from representing 
all valid Unicode code points (some of them are above 2^16).  If such code 
points are forbidden (even on platforms where wchar_t is 32 bits), be sure 
to say that explicitly.

Page 538 line 40: Why is MPI_LOGICAL defined as 4 bytes instead of 1?

Does the MPI standard say anywhere that a byte is assumed to be 8 bits?

Page 540 line 17: There is extra whitespace at the end of the line.

Page 541 lines 29 and 44: What does "equivalent" mean?  That they have the 
same typemap and displacements, or that they are exactly the handles that 
the user passed in (allowing caching)?

Page 541 lines 47-48: Does that mean that point-to-point operations are 
OK?  Non-collective file I/O?

Page 542 line 14: The first quotation mark is backwards.

Page 542 lines 17-25: The first item in this list appears to be a superset 
of the third one, and it seems like all of them might be required to be 
satisfied when applicable (not just "at least one").

Page 542 lines 47-: "FH", "fh", and "FOO" in math mode might need to be in 
\mathit (I can't tell for sure).

Page 543 lines 4-5: How do you get multiple file handles out of the same 
collective open of a file?  Accesses from different processes only?  Or 
can file descriptors be sent between processes?

Page 545 line 32: There need to be spaces around the em dash.

Page 546 line 27: "dup" should be "duplicate", there should be spaces 
around the em dash.

Page 547 line 10: Is MPI_Offset required to be signed?

Page 547 line 16: "KIND" might need to be in another font and/or 
lowercase.

Page 547 line 26: "info" (and maybe "hints") should be in text font.

Page 550 line 31: "myfile" might need to be in code font.

Page 552 line 11: The em dash needs spaces around it.

Page 552 line 27: The comma should be a period.

Page 552 line 34: The line has extra space at the end.

Page 555 line 40: The ranges here appear to have hyphens in them, rather 
than the correct en dashes.

Chapter 14:

Page 559 line 28: The default definition of MPI_PCONTROL needs to return 
successfully; that is not stated explicitly.

Page 560: Line 20 should be moved above line 17 in the example so that the 
MPI_Type_size call is not timed.

Page 560 line 33: "system" should be capitalized as a proper noun.

Page 560 line 47: ", however" should be "; however,".

Page 561 line 47: "they're" should be "they are", and there is extra space 
just before the question mark.

Page 562 line 2: "single threaded" should be hyphenated.

Page 562 line 18: There should be a comma after "Therefore".

Page 562 line 25: "ared out" is not a standard term as far as I know; 
maybe say something like "copied out of the base library and into the 
profiling one using a tool such as ar.".

Why is the information on enumerations first in the documentation, before 
any discussion of variables or how to use them?

Page 564 line 11: There should be a comma after "tuners".

Page 564 line 12: There should be a comma after "detailed".

Page 564 line 27, page 565 line 14, page 567 line 22, page 571 line 26, 
page 591 line 45: Table captions in the standard typically do not end with 
periods.

Page 567 line 30: Remove the comma before "which".

Page 568 line 18: Add a comma and space between "type" and "as".

Page 568 line 20: "enumerations" should be singular.

Page 568 lines 44-45: "of at least length one" should be "of length at 
least one".

Page 569 line 10: The first comma should be before the closing quote.

Page 569 line 21: "its value" should be "their values".

Page 570 line 30: Can the number and/or names of enumerators change during 
the course of a run?

Page 570 line 42: "mpiargenumtype" is a typo.

Page 571 line 33: Example titles have normally been subsections (with 
numbers) before the bold "Example n.n" text.

Page 573 line 7: There is extra space at the end of this line.

Page 573 line 18: "variables" should be singular.

Page 574 line 21: There should be a comma after the right parenthesis.

Page 575 lines 17-18: "implementation specific" should be hyphenated when 
used as an adjective (this applies to other parts of the standard as 
well).

Page 575 line 34: "reseting" should be "resetting".

Page 576-577: The datatype names in here should be in sans-serif.

Page 577 line 21: "MPI_T_PVAR_CLASS_AGGREGATE" should be in sans-serif.

Page 577 lines 33-34: "variable specific" and "implementation defined" 
both need to be hyphenated.

Page 577 line 40: ", otherwise" should be "; otherwise,".

Page 577 line 46: "its value" should be "their values".

Page 579 line 31: Remove the comma after "one".

Why are control variables and performance variables separate, given that 
they have so much in common and relatively few differences (in operations, 
attributes, etc.)?  It does look like performance variables need to be 
relative to a session, but there can be a flag for "session-specific" or 
similar to handle that.

Does MPI_INIT need to be called before running performance experiments?

Page 580 line 44: "such object handles" should be "such an object handle".

Page 581 line 1: There is extra space at the end of the line.

Page 583 line 45, page 584 line 4: "sampling based" should be hyphenated.

Page 584 line 6: "guaranteeing" should be "requiring".

Page 584 line 11: There should be a comma after "write".

Page 584 line 21: The opening quotation mark is backwards.

Page 584 line 26: "clean up" should be "cleanup" or hyphenated.

Page 584 line 46, page 586 line 20: These lines are indented more than 
those around them.

Page 589 line 43: "have been" should be "may have been".

Page 590 line 2: There should be a comma after "MPI_T_CATEGORY_GET_PVARS".

Page 590 line 3: There should be a comma after "MPI_T_PVAR_GET_INFO".

Page 590 line 20: "user provided" should be hyphenated.

Page 591 lines 11-12: "or has been deleted" seems to conflict with 
enumeration indices not being allowed to be deleted (as far as I can 
tell).  By the way, can they be added during the run?

Page 591 line 26: The function names should be in sans-serif font.

Page 591 line 31: "READREST" should be "READRESET".