MPIRequestfree(3OpenMPI) MPIRequestfree(3OpenMPI)

NAME
       MMPPIIRReeqquueessttffrreeee - Frees a communication request object.


SSYYNNTTAAXX
CC SSyynnttaaxx
       #include 
       int MPIRequestfree(MPIRequest *request)


FFoorrttrraann SSyynnttaaxx
       INCLUDE 'mpif.h'
       MPIREQUESTFREE(REQUEST, IERROR)
            INTEGER   REQUEST, IERROR


CC++++ SSyynnttaaxx
       #include 
       void Request::Free()


IINNPPUUTT//OOUUTTPPUUTT PPAARRAAMMEETTEERR
       request         Communication request (handle).


DESCRIPTION
       This  operation allows a request object to be deallocated without wait-
       ing for the associated communication to complete.

       MPIRequestfree marks the request object  for  deallocation  and  sets
       request  to MPIREQUESTNULL. Any ongoing communication that is associ-
       ated with the request will be allowed to complete. The request will  be
       deallocated only after its completion.


NNOOTTEESS
       Once a request is freed by a call to MPIRequestfree, it is not possi-
       ble to check for the successful completion of the associated communica-
       tion  with calls to MPIWait or MPITest. Also, if an error occurs sub-
       sequently during the communication, an error code cannot be returned to
       the  user - such an error must be treated as fatal. Questions arise as
       to how  one  knows  when  the  operations  have  completed  when  using
       MPIRequestfree.  Depending  on  the program logic, there may be other
       ways in which the program knows that certain operations have  completed
       and  this  makes  usage  of MPIRequestfree practical. For example, an
       active send request could be freed when the logic  of  the  program  is
       such that the receiver sends a reply to the message sent - the arrival
       of the reply informs the sender that the send  has  completed  and  the
       send  buffer  can  be reused. An active receive request should never be
       freed, as the receiver will have no way to verify that the receive  has
       completed and the receive buffer can be reused.


       EExxaammppllee::

           CALL MPICOMMRANK(MPICOMMWORLD, rank)
           IF(rank.EQ.0) THEN
               DO i=1, n
                 CALL MPIISEND(outval, 1, MPIREAL, 1, 0, req, ierr)
                 CALL MPIREQUESTFREE(req, ierr)
                 CALL MPIIRECV(inval, 1, MPIREAL, 1, 0, req, ierr)
                 CALL MPIWAIT(req, status, ierr)
               END DO
           ELSE    ! rank.EQ.1
               CALL MPIIRECV(inval, 1, MPIREAL, 0, 0, req, ierr)
               CALL MPIWAIT(req, status)
               DO I=1, n-1
                  CALL MPIISEND(outval, 1, MPIREAL, 0, 0, req, ierr)
                  CALL MPIREQUESTFREE(req, ierr)
                  CALL MPIIRECV(inval, 1, MPIREAL, 0, 0, req, ierr)
                  CALL MPIWAIT(req, status, ierr)
               END DO
               CALL MPIISEND(outval, 1, MPIREAL, 0, 0, req, ierr)
               CALL MPIWAIT(req, status)
           END IF

       This  routine is normally used to free persistent requests created with
       either MPIRecvinit or MPISendinit and friends.  However, it can  be
       used to free a request created with MPIIrecv or MPIIsend and friends;
       in that case the use can not use the test/wait routines on the request.

       It  iiss  permitted  to free an active request.  However, once freed, you
       can not use the request in a wait or test routine (e.g., MPIWait ).


EERRRROORRSS
       Almost all MPI routines return an error value; C routines as the  value
       of  the  function  and Fortran routines in the last argument. C++ func-
       tions do not return errors. If the default  error  handler  is  set  to
       MPI::ERRORSTHROWEXCEPTIONS, then on error the C++ exception mechanism
       will be used to throw an MPI:Exception object.

       Before the error value is returned, the current MPI  error  handler  is
       called.  By  default, this error handler aborts the MPI job, except for
       I/O  function  errors.  The  error  handler   may   be   changed   with
       MPICommseterrhandler; the predefined error handler MPIERRORSRETURN
       may be used to cause error values to be returned. Note  that  MPI  does
       not guarantee that an MPI program can continue past an error.


SEE ALSO
       MPIIsend
       MPIIrecv
       MPIIssend
       MPIIbsend
       MPIIrsend
       MPIRecvinit
       MPISendinit
       MPISsendinit
       MPIRsendinit
       MPITest
       MPIWait
       MPIWaitall
       MPIWaitany
       MPIWaitsome
       MPITestall
       MPITestany
       MPITestsome






Open MPI 1.2                    September 2006      MPIRequestfree(3OpenMPI)