/*D
   MPI_Buffer_attach - Attaches a user-provided buffer for sending

Synopsis:
.vb
int MPI_Buffer_attach(void *buffer, int size)
.ve
.vb
int MPI_Buffer_attach_c(void *buffer, MPI_Count size)
.ve

Input Parameters:
+ buffer - initial buffer address (choice)
- size - buffer size, in bytes (non-negative integer)

Notes:
The size given should be the sum of the sizes of all outstanding Bsends that
you intend to have, plus 'MPI_BSEND_OVERHEAD' for each Bsend that you do.
For the purposes of calculating size, you should use 'MPI_Pack_size'.
In other words, in the code
.vb
     MPI_Buffer_attach(buffer, size);
     MPI_Bsend(..., count=20, datatype=type1,  ...);
     ...
     MPI_Bsend(..., count=40, datatype=type2, ...);
.ve
the value of 'size' in the 'MPI_Buffer_attach' call should be greater than
the value computed by
.vb
     MPI_Pack_size(20, type1, comm, &s1);
     MPI_Pack_size(40, type2, comm, &s2);
     size = s1 + s2 + 2 * MPI_BSEND_OVERHEAD;
.ve
The 'MPI_BSEND_OVERHEAD' gives the maximum amount of space that may be used in
the buffer for use by the BSEND routines in using the buffer.  This value
is in 'mpi.h' (for C) and 'mpif.h' (for Fortran).

.N NotThreadSafe
Because the buffer for buffered sends (e.g., 'MPI_Bsend') is shared by all
threads in a process, the user is responsible for ensuring that only
one thread at a time calls this routine or 'MPI_Buffer_detach'.

.N Fortran

.N Errors
.N MPI_SUCCESS
.N MPI_ERR_ARG
.N MPI_ERR_OTHER

.seealso: MPI_Buffer_detach, MPI_Bsend
D*/

