5.2. Open MPI extensions

Open MPI contains a framework for extending the MPI API that is available to applications. Each extension is usually a standalone set of functionality that is distinct from other extensions (similar to how Open MPI’s plugins are usually unrelated to each other). These extensions provide new functions and/or constants that are available to MPI applications.

Warning

These extensions are neither standard nor portable to other MPI implementations!

They are a mechanism for the Open MPI developer community to provide new functionality to users, typically before it becomes standardized by the MPI Forum.

5.2.1. Available extensions

The following extensions are included in this version of Open MPI:

  1. shortfloat: Provides MPI datatypes MPIX_C_FLOAT16, MPIX_SHORT_FLOAT, MPIX_SHORT_FLOAT, and MPIX_CXX_SHORT_FLOAT_COMPLEX if corresponding language types are available. See ompi/mpiext/shortfloat/README.txt for details.

  2. affinity: Provides the OMPI_Affinity_str() API, which returns a string indicating the resources which a process is bound. For more details, see its man page.

  3. cuda: When the library is compiled with CUDA-aware support, it provides two things. First, a macro MPIX_CUDA_AWARE_SUPPORT. Secondly, the function MPIX_Query_cuda_support() that can be used to query for support.

  4. example: A non-functional extension; its only purpose is to provide an example for how to create other extensions.

  5. ftmpi: An implementation of the User Level Fault Mitigation (ULFM) proposal. See its documentation section for more details.

5.2.2. Compiling the extensions

Open MPI extensions are all enabled by default; they can be disabled via the --disable-mpi-ext command line switch.

Since extensions are meant to be used by advanced users only, this file does not document which extensions are available or what they do. Look in the ompi/mpiext directory in a distribution Open MPI tarball to see the extensions; each subdirectory of that directory contains an extension. Each has a README file that describes what it does.

5.2.3. Using the extensions

To reinforce the fact that these extensions are non-standard, you must include a separate header file after <mpi.h> to obtain the function prototypes, constant declarations, etc. For example:

#include <mpi.h>
#if defined(OPEN_MPI) && OPEN_MPI
#include <mpi-ext.h>
#endif

int main() {
    MPI_Init(NULL, NULL);

#if defined(OPEN_MPI) && OPEN_MPI
    char ompi_bound[OMPI_AFFINITY_STRING_MAX];
    char current_binding[OMPI_AFFINITY_STRING_MAX];
    char exists[OMPI_AFFINITY_STRING_MAX];

    OMPI_Affinity_str(OMPI_AFFINITY_LAYOUT_FMT, ompi_bound,
                      current_bindings, exists);
#endif

    MPI_Finalize();
    return 0;
}

Notice that the Open MPI-specific code is surrounded by the #if statement to ensure that it is only ever compiled by Open MPI.

The Open MPI wrapper compilers (mpicc and friends) should automatically insert all relevant compiler and linker flags necessary to use the extensions. No special flags or steps should be necessary compared to “normal” MPI applications.