MPI_bufcopy_set(3)

NAME
MPI_bufcopy_set - Set the local buffer copy size limit

SYNOPSIS
#include <mpi.h>
int MPI_bufcopy_set(MPI_Aint size);

#include <pmpi.h>
int PMPI_bufcopy_set(MPI_Aint size);

#include <mpi.h>
void MPI::bufcopy_set(MPI::Aint size);

INCLUDE 'mpif.h'
MPI_BUFCOPY_SET(size, ierr)
INTEGER ierr
INTEGER(KIND=MPI_ADDRESS_KIND) size

INPUT PARAMETER
size
    - size of the local buffer copy limit in bytes (integer)

DESCRIPTION
The MPI_bufcopy_set() function is used to set the default buffering maximum size of local (same machine inter-thread) sends for this rank. If the size of a send is below this limit, then this MPI implementation may attempt to allocate a temporary buffer to store the send's information. By copying into such buffers it is possible for sends to complete more rapidly. However, this uses up memory. If too many sends are outstanding, then memory could be exhausted. If a send is too large then MPI will wait until a matching receive is posted. This requires only the amount of memory required to post an envelope to the destination rank, which at only 64 bytes, is trivially small. By tuning this limit, it may be possible to improve performance at the cost of extra memory usage. The default size for this limit is 1 MiB. Note that it is also possible to change this limit by using the MPI_BUFCOPY_SIZE environment variable. If set on process startup, this will set the default limit (in bytes) for all ranks on this machine. This function is a non-portable extension of the MPI interface. It may not exist in other MPI implementations. PMPI_bufcopy_set() is the profiling version of this function.

ERRORS
All MPI routines except for MPI_Wtime and MPI_Wtick return an error code. The the current MPI error handler is invoked if the return value is not MPI_SUCCESS. The default error handler aborts, but this may be changed with by using the MPI_Errhandler_set() function. The predefined error handler MPI_ERRORS_RETURN may be used to cause error values to be returned instead. Note that MPI does not guarentee that an MPI program can continue past an error. In this implementation, all errors except MPI_ERR_INTERN or MPI_ERR_OTHER should always be recoverable. In C, the error code is passed as the return value. In FORTRAN, all functions have an parameter ierr which returns the error code. MPI C++ functions do not directly return an error code. However, C++ users may want to use the MPI::ERRORS_THROW_EXCEPTIONS handler. This will throw an MPI::Exception with the corresponding error code. To prevent exceptions from being raised from within C and Fortran code, they will see all error return values as MPI_ERR_PENDING when this handler is chosen. In this implementation, call MPI::throw_exception() to throw the correct exception if this occurs.
MPI_SUCCESS
    - No error;
MPI_ERR_PENDING
    - Pending exception.

SEE ALSO
MPI_bufcopy_get(3)