[Mpi3-rma] RMA chapter for quick review

[Bronis R. de Supinski]

Torsten:

Re:
>> [1, 35-38]: In the list: "MPI_PUT (remote write), MPI_GET (remote read),
>> [and] MPI_ACCUMULATE (remote update), MPI_GET_ACCUMULATE,
>> MPI_FETCH_AND_OP
>> (remote read and update), MPI_COMPARE_AND_SWAP (remote atomic swap
>> operations), MPI_RPUT, MPI_RGET, MPI_RACCUMULATE and
>> MPI_RGET_ACCUMULATE";
>> it is odd that a subset of the operations have parenthetical expressions
>> that indicate the nature of the functionality. Either all operations
>> should be followed with a parenthetical explanation or none of them.
>> The right solution is probably to reformat into a list with each
>> item being the group of operations that provide functionality of the
>> same nature (e.g., I am guessing that MPI_GET and MPI_RGET are both
>> remote read operations). Initially I thought the ones that are not
>> followed by a parenthetical expression were being grouped with the
>> following one that has the parenthetical expression (so MPI_GET_ACCUMULATE
>> is a remote read and update operation). However, the list ends with
>> several operations with no following parenthetical expression. Anyway,
>> the implicit grouping is unclear. Making it explicit would be better.
>> It would also simplify how the following sentence ("When a reference is
>> made to “accumulate” operations in this chapter, it refers to the
>> following operations: MPI_ACCUMULATE, MPI_GET_ACCUMULATE,
>> MPI_FETCH_AND_OP,
>> MPI_COMPARE_AND_SWAP, MPI_RACCUMULATE and MPI_RGET_ACCUMULATE.") simpler.
> Ok, I added the descriptions to the R-operations.

Hmm. the more I thought about the more I though this would
be better as a bulleted list, like the one about the types
of collective operations. I think that instead of "The
following communication calls are provided:" (etc.) something
like this would be best:

----------------------------------------------------------------

One-sided operations can be classified as follows:

* Remote read: MPI_GET, MPI_RGET;

* Remote write: MPI_PUT, MPI_RPUT;

* Remote update: MPI_ACCUMULATE, MPI_RACCUMULATE;

* Remote read and update: MPI_GET_ACCUMULATE, MPI_FETCH_AND_OP,
                           MPI_RGET_ACCUMULATE;

* Remote atomic swap operations: MPI_COMPARE_AND_SWAP.

This chapter refers to operations set that includes all remote
update, remote read and update, and remote atomic swap operations
as “accumulate” operations.

-------------------------------------------------------------------

This version makes it much clearer that grouping is intended
and makes the definition of accumulate operations simpler.
It also makes it clearer that the ommission of an 
MPI_RCOMPARE_AND_SWAP operation is intentional.

[snip]

>> [2, 12] Use active voice: "However, support for asynchronous communication
>> agents in software (handlers, threads, etc.) might be needed, for certain
>> RMA functions, in a distributed memory environment." => "However, certain
>> RMA functions might need support for asynchronous communication agents in
>> software (handlers, threads, etc.) in a distributed memory environment."
> I'll defer this one for now because it doesn't seem essential and it's a
> macro-mess :).

I'm not sure that I understand.

> Generally, I fear that it will be a lot of work if we're trying to fix
> all the little wording things in the OS chapter. Many of them (most of
> the ones you found) have been there since MPI-2 and are in the places
> that we didn't want to touch. It might be better to not apply such
> changes at this point so that reviewers can focus on the semantic
> changes (and not have colored sections all over the document).

Hmm. I will need to read through the whole chapter in order
to vote on the changes. In that process, I will hit these
types of corrections. How would you prefer that we handle them?

Bronis