[mpi-21] Ballot 4 proposal: INOUT arguments

[Rolf Rabenseifner]

Proposal:
The current text in MPI 2.0 Sect. 2.3 Procedure Specification,
page 6 lines 30-34 read:

  There is one special case — if an argument is a handle to an 
  opaque object (these terms are defined in Section 2.5.1), and
  the object is updated by the procedure call, then the argument
  is marked OUT. It is marked this way even though the handle
  itself is not modified — we use the OUT attribute to denote
  that what the handle references is updated. Thus, in C++,
  IN arguments are either references or pointers to const objects.

but should read:

  There is one special case — if an argument is a handle to an 
  opaque object (these terms are defined in Section 2.5.1), and
  the object is updated by the procedure call 
  but the handle itself is not modified , then the argument
  is marked IN/INOUT. 
  We use the first part (IN) to specify the use of the handle 
  and the second part (INOUT) to specify the use of the opaque 
  object. 
  Thus, in C++,
  IN arguments are either references or pointers to const objects,
  IN/INOUT arguments are references to const handles to non-const
  objects.

In all reoutines mentioned in the clarification below,
the INOUT handle declaration (in MPI-2.0) and the IN handle declaration
(in MPI-1.1) ist modified into a IN/INOUT handle declaaration.
____________________________

Rationale for this proposal:

I have checked the total MPI 1.1 and 2.0 standard to find 
all routines with an argument specification according to 
the following declaration pattern:

  Language independent interface:
     INOUT   handle
  C interface
     MPI_handletype handle

We can find this pattern only in MPI-2.0 at following 
routines:

  MPI_INFO_SET / _DELETE
  MPI_xxxx_SET_ERRHANDLER  with xxxx=COMM / TYPE / WIN
  MPI_GREQUEST_COMPLETE
  MPI_xxxx_SET_NAME        with xxxx=COMM / TYPE / WIN
  MPI_xxxx_SET_ATTR        with xxxx=COMM / TYPE / WIN
  MPI_xxxx_DELETE_ATTR     with xxxx=COMM / TYPE / WIN
  MPI_FILE_SET_SIZE / _PREALLOCATE  / _SET_INFO  / _SET_VIEW 
  MPI_FILE_WRITE_AT / _WRITE_AT_ALL / _IWRITE_AT
  MPI_FILE_READ     / _READ_ALL     / _WRITE     / _WRITE_ALL
  MPI_FILE_IREAD    / _IWRITE    
  MPI_FILE_SEEK
  MPI_FILE_READ_SHARED              / _WRITE_SHARED
  MPI_FILE_IREAD_SHARED             / _IWRITE_SHARED    
  MPI_FILE_READ_ORDERED             / _WRITE_ORDERED
  MPI_FILE_SEEK_SHARED
  MPI_FILE_WRITE_AT_ALL_BEGIN       / MPI_FILE_WRITE_AT_ALL_END
  MPI_FILE_READ_ALL_BEGIN           / MPI_FILE_READ_ALL_END
  MPI_FILE_WRITE_ALL_BEGIN          / MPI_FILE_WRITE_ALL_END
  MPI_FILE_READ_ORDERED_BEGIN       / MPI_FILE_READ_ORDERED_END
  MPI_FILE_WRITE_ORDERED_BEGIN      / MPI_FILE_WRITE_ORDERED_END
  MPI_FILE_SET_ATOMICITY            / _SYNC
  
All these routines keep the handle itself unchanged, but the 
opaque object is modified in a way, that with oother MPI routines
this change can be detected.
For example, an attribute is cached or changed, a file pointer 
is moved, the content of a file was modified.

The current text in MPI 2.0 Sect. 2.3 Procedure Specification,
page 6 lines 30-34 read:

  There is one special case — if an argument is a handle to an 
  opaque object (these terms are defined in Section 2.5.1), and
  the object is updated by the procedure call, then the argument
  is marked OUT. It is marked this way even though the handle
  itself is not modified — we use the OUT attribute to denote
  that what the handle references is updated. Thus, in C++,
  IN arguments are either references or pointers to const objects.

With this definition (that I want to change later on) the use
of INOUT is correct.

In MPI-1.1 we have several of such routines, but in all cases, 
the handle is declared only as IN.

I hope, I could find all of them: 

  MPI_ATTR_PUT / _ DELETE 
  MPI_ERRHANDLER_SET
    (these routines are now deprecated, but compare with use of 
     INOUT in MPI_COMM_SET_ATTR and MPI_COMM_DELETE_ATTR in MPI-2.0)

The following proposal should remove this inconsistency and
should be a basis for correct definition of const.
____________________________

I hope, with this proposal, the INOUT handle problem can be really solved.

Best regards
Rolf 

Dr. Rolf Rabenseifner . . . . . . . . . .. email rabenseifner_at_[hidden]
High Performance Computing Center (HLRS) . phone ++49(0)711/685-65530
University of Stuttgart . . . . . . . . .. fax ++49(0)711 / 685-65832
Head of Dpmt Parallel Computing . . . www.hlrs.de/people/rabenseifner
Nobelstr. 19, D-70550 Stuttgart, Germany . (Office: Allmandring 30)