support for mpi_comm_attach_buffer and friends

docs/Makefile.am

@@ -118,6 +118,8 @@ OMPI_MAN3 = \
         MPI_Bsend_init.3 \
         MPI_Buffer_attach.3 \
         MPI_Buffer_detach.3 \
+        MPI_Buffer_flush.3 \
+        MPI_Buffer_iflush.3 \
         MPI_Cancel.3 \
         MPI_Cart_coords.3 \
         MPI_Cart_create.3 \
@@ -129,6 +131,7 @@ OMPI_MAN3 = \
         MPI_Cart_sub.3 \
         MPI_Close_port.3 \
         MPI_Comm_accept.3 \
+        MPI_Comm_attach_buffer.3 \
         MPI_Comm_c2f.3 \
         MPI_Comm_call_errhandler.3 \
         MPI_Comm_compare.3 \
@@ -139,10 +142,12 @@ OMPI_MAN3 = \
         MPI_Comm_create_group.3 \
         MPI_Comm_create_keyval.3 \
         MPI_Comm_delete_attr.3 \
+        MPI_Comm_detach_buffer.3 \
         MPI_Comm_disconnect.3 \
         MPI_Comm_dup.3 \
         MPI_Comm_dup_with_info.3 \
         MPI_Comm_f2c.3 \
+        MPI_Comm_flush_buffer.3 \
         MPI_Comm_free.3 \
         MPI_Comm_free_keyval.3 \
         MPI_Comm_get_attr.3 \
@@ -153,6 +158,7 @@ OMPI_MAN3 = \
         MPI_Comm_group.3 \
         MPI_Comm_idup.3 \
         MPI_Comm_idup_with_info.3 \
+        MPI_Comm_iflush_buffer.3 \
         MPI_Comm_join.3 \
         MPI_Comm_rank.3 \
         MPI_Comm_remote_group.3 \
@@ -402,13 +408,17 @@ OMPI_MAN3 = \
         MPI_Send_init.3 \
         MPI_Sendrecv.3 \
         MPI_Sendrecv_replace.3 \
+        MPI_Session_attach_buffer.3 \
         MPI_Session_create_errhandler.3 \
+        MPI_Session_detach_buffer.3 \
         MPI_Session_f2c.3 \
         MPI_Session_finalize.3 \
+        MPI_Session_flush_buffer.3 \
         MPI_Session_get_info.3 \
         MPI_Session_get_nth_pset.3 \
         MPI_Session_get_num_psets.3 \
         MPI_Session_get_pset_info.3 \
+        MPI_Session_iflush_buffer.3 \
         MPI_Session_init.3 \
         MPI_Sizeof.3 \
         MPI_Ssend.3 \

docs/man-openmpi/man3/MPI_Buffer_attach.3.rst

@@ -14,7 +14,7 @@ INPUT PARAMETERS
 ----------------
 
 * ``buf`` : Initial buffer address (choice).
-* ``size`` : Buffer size, in bytes (integer).
+* ``size`` : Buffer size, in bytes (integer).  Ignored when buf is MPI_BUFFER_AUTOMATIC.
 
 OUTPUT PARAMETER
 ----------------
@@ -31,9 +31,15 @@ mode. Only one buffer can be attached to a process at a time.
 NOTES
 -----
 
-The size given should be the sum of the sizes of all outstanding Bsends
-that you intend to have, plus MPI_BSEND_OVERHEAD bytes for each Bsend
-that you do. For the purposes of calculating size, you should use
+This buffer is to be used for buffering outgoing messages sent when using a
+communicator to which no communicator specific buffer is attached or which
+is derived from a session to which no session-specific buffer is attached
+at the time the buffered mode send is started.
+
+When not using MPI_BUFFER_AUTOMATIC, the size given should be the sum
+of the sizes of all outstanding Bsends that you intend to have, plus
+MPI_BSEND_OVERHEAD bytes for each Bsend that you do. For the purposes
+of calculating size, you should use
 :ref:`MPI_Pack_size`. In other words, in the code
 
 .. code-block:: c

docs/man-openmpi/man3/MPI_Buffer_detach.3.rst

@@ -15,7 +15,7 @@ OUTPUT PARAMETERS
 -----------------
 
 * ``buf`` : Initial buffer address (choice).
-* ``size`` : Buffer size, in bytes (integer).
+* ``size`` : Buffer size, in bytes (integer). Undefined if MPI_BUFFER_AUTOMATIC was used when attaching.
 * ``ierror`` : Fortran only: Error status (integer).
 
 DESCRIPTION
@@ -67,7 +67,7 @@ usages).
 For Fortran: The Fortran binding for this routine is different. Because
 Fortran does not have pointers, it is impossible to provide a way to use
 the output of this routine to exchange buffers. In this case, only the
-size field is set.
+size field is set.  Note this does not apply when using the mpi_f08 bindings.
 
 For C: Even though the buf argument is declared as void, it is really
 the address of a void pointer. See Rationale, below, for more details.

docs/man-openmpi/man3/MPI_Buffer_flush.3.rst

@@ -0,0 +1,42 @@
+.. _mpi_buffer_flush:
+
+MPI_Buffer_flush
+================
+
+.. include_body
+
+:ref:`MPI_Buffer_flush`, :ref:`MPI_Buffer_iflush` |mdash| Wait till all messages currently in 
+the the MPI process specific buffer of the calling MPI process have been transmitted.
+
+.. The following directive tells the man page generation script to
+   generate multiple bindings for this file.
+.. mpi-bindings: MPI_Buffer_flush, MPI_Buffer_iflush
+
+.. The following file was automatically generated
+.. include:: ./bindings/mpi_buffer_flush.rst
+
+INPUT PARAMETERS
+----------------
+
+OUTPUT PARAMETER
+----------------
+
+* ``ierror`` : Fortran only: Error status (integer).
+
+DESCRIPTION
+-----------
+
+:ref:`MPI_Buffer_flush`  will not return until all messages currently in the MPI process
+specific buffer of the calling MPI process have been transmitted.  The non-blocking variant
+:ref:`MPI_Buffer_iflush` returns a MPI request that can be queried using MPI request
+status functions to determine when all messages in the MPI process specific  buffer of the
+call MPI process have been transmitted.
+
+ERRORS
+------
+
+.. include:: ./ERRORS.rst
+
+.. seealso::
+   * :ref:`MPI_Buffer_attach`
+   * :ref:`MPI_Buffer_detach`

docs/man-openmpi/man3/MPI_Buffer_iflush.3.rst

@@ -0,0 +1,8 @@
+.. _mpi_buffer_iflush:
+
+MPI_Buffer_iflush
+=================
+    .. include_body
+
+.. include:: ../man3/MPI_Buffer_flush.3.rst
+    :start-after: .. include_body

docs/man-openmpi/man3/MPI_Comm_attach_buffer.3.rst

@@ -0,0 +1,67 @@
+.. _mpi_comm_attach_buffer:
+
+MPI_Comm_attach_buffer
+======================
+
+.. include_body
+
+:ref:`MPI_Comm_attach_buffer` |mdash| Attaches a user-defined buffer to a communicator for sending.
+
+.. The following file was automatically generated
+.. include:: ./bindings/mpi_comm_attach_buffer.rst
+
+INPUT PARAMETERS
+----------------
+
+* ``comm``: Communicator (handle).
+* ``buf`` : Initial buffer address (choice). 
+* ``size`` : Buffer size, in bytes (integer). Ignored if buf is MPI_BUFFER_AUTOMATIC.
+
+OUTPUT PARAMETER
+----------------
+
+* ``ierror`` : Fortran only: Error status (integer).
+
+DESCRIPTION
+-----------
+
+Provides to MPI a buffer to attach to a communicator to be used for buffering
+outgoing messages. The buffer is used only by messages sent in buffered
+mode using the supplied communicator. Only one buffer can be attached to a communicator at a time.
+
+NOTES
+-----
+
+When not using MPI_BUFFER_AUTOMATIC, the size given should be the sum 
+of the sizes of all outstanding Bsends that you intend to have, 
+plus MPI_BSEND_OVERHEAD bytes for each Bsend that you do. For the purposes of 
+calculating size, you should use :ref:`MPI_Pack_size`. In other words, in the code
+
+.. code-block:: c
+
+   MPI_Comm_attach_buffer(MPI_COMM_WORLD,  buf, size )
+   MPI_Bsend( ..., count=20, datatype=type1, ... );
+   MPI_Bsend( ..., count=40, datatype=type2, ... );
+
+the value of size in the :ref:`MPI_Comm_attach_buffer` call should be greater than
+the value computed by
+
+.. code-block:: c
+
+   MPI_Pack_size( 20, type1, comm, &s1 );
+   MPI_Pack_size( 40, type2, comm, &s2 );
+   size = s1 + s2 + 2 * MPI_BSEND_OVERHEAD;
+
+MPI_BSEND_OVERHEAD gives the maximum amount of buffer space that may be
+used by the Bsend routines. This value is in mpi.h for C and mpif.h for
+Fortran.
+
+ERRORS
+------
+
+.. include:: ./ERRORS.rst
+
+.. seealso::
+   * :ref:`MPI_Comm_detach_buffer`
+   * :ref:`MPI_Session_attach_buffer`
+   * :ref:`MPI_Buffer_attach`

docs/man-openmpi/man3/MPI_Comm_detach_buffer.3.rst

@@ -0,0 +1,88 @@
+.. _mpi_comm_detach_buffer:
+
+MPI_Comm_detach_buffer
+======================
+
+.. include_body
+
+:ref:`MPI_Comm_detach_buffer` |mdash| Removes an existing buffer previously attached to the communicator(for use in in :ref:`MPI_Bsend`,
+etc.)
+
+.. The following file was automatically generated
+.. include:: ./bindings/mpi_comm_detach_buffer.rst
+
+OUTPUT PARAMETERS
+-----------------
+
+* ``comm``: Communicator (handle).
+* ``buf`` : Initial buffer address (choice).
+* ``size`` : Buffer size, in bytes (integer).  Undefined if MPI_BUFFER_AUTOMATIC was used when attaching.
+* ``ierror`` : Fortran only: Error status (integer).
+
+DESCRIPTION
+-----------
+
+Detach the buffer currently associated with the communicator. The call returns the
+address and the size of the detached buffer. This operation will block
+until all messages currently in the buffer have been transmitted. Upon
+return of this function, the user may reuse or deallocate the space
+taken by the buffer.
+
+Example: Calls to attach and detach buffers.
+
+.. code-block:: c
+
+   #define BUFFSIZE 10000
+
+   int size char *buff;
+   MPI_Comm_attach_buffer(MPI_COMM_WORLD, malloc(BUFFSIZE), BUFFSIZE);
+
+   // a buffer of 10000 bytes can now be used by MPI_Bsend
+
+   MPI_Comm_detach_buffer(MPI_COMM_WORLD,  &buff, &size); // Buffer size reduced to zero
+   MPI_Comm_attach_buffer(MPI_COMM_WORLD,  buff, size); // Buffer of 10000 bytes available again
+
+NOTES
+-----
+
+The reason that :ref:`MPI_Comm_detach_buffer` returns the address and size of the
+buffer being detached is to allow nested libraries to replace and
+restore the buffer. For example, consider
+
+.. code-block:: c
+
+   int size, mysize, idummy;
+   void *ptr, *myptr, *dummy;
+   MPI_Comm_detach_buffer(MPI_COMM_WORLD, &ptr, &size );
+   MPI_Comm_attach_buffer(MPI_COMM_WORLD,  myptr, mysize );
+
+   /* ... library code ... */
+
+   MPI_Comm_detach_buffer(MPI_COMM_WORLD,  &dummy, &idummy );
+   MPI_Comm_attach_buffer(MPI_COMM_WORLD,  ptr, size );
+
+This is much like the action of the UNIX signal routine and has the same
+strengths (it's simple) and weak‐nesses (it only works for nested
+usages).
+
+For Fortran: The Fortran binding for this routine is different. Because
+Fortran does not have pointers, it is impossible to provide a way to use
+the output of this routine to exchange buffers. In this case, only the
+size field is set.  Note this does not apply when using the mpi_f08 bindings.
+
+For C: Even though the buf argument is declared as void, it is really
+the address of a void pointer. See Rationale, below, for more details.
+
+Even though the C functions :ref:`MPI_Comm_attach_buffer` and :ref:`MPI_Comm_detach_buffer` both
+have an argument of type void*, these arguments are used
+differently: A pointer to the buffer is passed to :ref:`MPI_Comm_attach_buffer`; the
+address of the pointer is passed to :ref:`MPI_Comm_detach_buffer`, so that this call
+can return the pointer value.
+
+ERRORS
+------
+
+.. include:: ./ERRORS.rst
+
+.. seealso::
+   * :ref:`MPI_Comm_attach_buffer`

docs/man-openmpi/man3/MPI_Comm_flush_buffer.3.rst

@@ -0,0 +1,44 @@
+.. _mpi_comm_flush_buffer:
+
+MPI_Comm_flush_buffer
+======================
+
+.. include_body
+
+:ref:`MPI_Comm_flush_buffer`, :ref:`MPI_Comm_iflush_buffer` |mdash| Wait till all messages currently in 
+the communicator-specific buffer of the calling MPI process have been transmitted.
+
+.. The following directive tells the man page generation script to
+   generate multiple bindings for this file.
+.. mpi-bindings: MPI_Comm_flush_buffer, MPI_Comm_iflush_buffer
+
+.. The following file was automatically generated
+.. include:: ./bindings/mpi_comm_flush_buffer.rst
+
+INPUT PARAMETERS
+----------------
+
+* ``comm``: Communicator (handle).
+
+OUTPUT PARAMETER
+----------------
+
+* ``ierror`` : Fortran only: Error status (integer).
+
+DESCRIPTION
+-----------
+
+:ref:`MPI_Comm_flush_buffer`  will not return until all messages currently in the communicator-
+specific buffer of the calling MPI process have been transmitted.  The non-blocking variant
+:ref:`MPI_Comm_iflush_buffer` returns a MPI request that can be queried using MPI request
+status functions to determine when all messages in the communicator-specific buffer of the
+call MPI process have been transmitted.
+
+ERRORS
+------
+
+.. include:: ./ERRORS.rst
+
+.. seealso::
+   * :ref:`MPI_Comm_attach_buffer`
+   * :ref:`MPI_Comm_detach_buffer`

docs/man-openmpi/man3/MPI_Comm_iflush_buffer.3.rst

@@ -0,0 +1,8 @@
+.. _mpi_comm_iflush_buffer:
+
+MPI_Comm_iflush_buffer
+======================
+    .. include_body
+
+.. include:: ../man3/MPI_Comm_flush_buffer.3.rst
+    :start-after: .. include_body