/*D
   MPI_Bsend - Basic send with user-provided buffering

Synopsis:
.vb
int MPI_Bsend(const void *buf, int count, MPI_Datatype datatype, int dest,
              int tag, MPI_Comm comm)
.ve
.vb
int MPI_Bsend_c(const void *buf, MPI_Count count, MPI_Datatype datatype,
                int dest, int tag, MPI_Comm comm)
.ve

Input Parameters:
+ buf - initial address of send buffer (choice)
. count - number of elements in send buffer (non-negative integer)
. datatype - datatype of each send buffer element (handle)
. dest - rank of destination (integer)
. tag - message tag (integer)
- comm - communicator (handle)

Notes:
This send is provided as a convenience function; it allows the user to
send messages without worring about where they are buffered (because the
user `must` have provided buffer space with 'MPI_Buffer_attach').

In deciding how much buffer space to allocate, remember that the buffer space
is not available for reuse by subsequent 'MPI_Bsend's unless you are certain
that the message
has been received (not just that it should have been received).  For example,
this code does not allocate enough buffer space
.vb
    MPI_Buffer_attach(b, n*sizeof(double) + MPI_BSEND_OVERHEAD);
    for (i=0; i<m; i++) {
        MPI_Bsend(buf, n, MPI_DOUBLE, ...);
    }
.ve
because only enough buffer space is provided for a single send, and the
loop may start a second 'MPI_Bsend' before the first is done making use of the
buffer.

In C, you can
force the messages to be delivered by
.vb
    MPI_Buffer_detach(&b, &n);
    MPI_Buffer_attach(b, n);
.ve
(The 'MPI_Buffer_detach' will not complete until all buffered messages are
delivered.)

.N ThreadSafe

.N Fortran

.N Errors
.N MPI_SUCCESS
.N MPI_ERR_BUFFER
.N MPI_ERR_COMM
.N MPI_ERR_COUNT
.N MPI_ERR_RANK
.N MPI_ERR_TAG
.N MPI_ERR_TYPE
.N MPI_ERR_OTHER

.seealso: MPI_Buffer_attach, MPI_Ibsend, MPI_Bsend_init
D*/

