FAQ:
Removed MPI constructs

Table of contents:

1. Why does my MPI application fail to compile, complaining that various MPI APIs/symbols are undefined?
2. Why on earth are you breaking the compilation of MPI applications?
3. Why am I getting deprecation warnings when compiling my MPI application?
4. How do I update my MPI application to stop using MPI_ADDRESS?
5. How do I update my MPI application to stop using MPI_ERRHANDLER_CREATE?
6. How do I update my MPI application to stop using MPI_ERRHANDLER_GET?
7. How do I update my MPI application to stop using MPI_ERRHANDLER_SET?
8. How do I update my MPI application to stop using MPI_TYPE_HINDEXED?
9. How do I update my MPI application to stop using MPI_TYPE_HVECTOR?
10. How do I update my MPI application to stop using MPI_TYPE_STRUCT?
11. How do I update my MPI application to stop using MPI_TYPE_EXTENT?
12. How do I update my MPI application to stop using MPI_TYPE_LB?
13. How do I update my MPI application to stop using MPI_TYPE_UB?
14. How do I update my MPI application to stop using MPI_LB / MPI_UB?
15. How do I update my MPI application to stop using MPI_COMBINER_HINDEXED_INTEGER, MPI_COMBINER_HVECTOR_INTEGER, and MPI_COMBINER_STRUCT_INTEGER?
16. How do I update my MPI application to stop using MPI_Handler_function?

Starting with v4.0.0, Open MPI — by default — removes the prototypes from mpi.h for MPI symbols that were deprecated in 1996 in the MPI-2.0 standard, and finally removed from the MPI-3.0 standard (2012).

Specifically, the following symbols (specified in the MPI language-neutral names) are no longer prototyped in mpi.h by default:

Although these symbols are no longer prototyped in mpi.h, _they are still present in the MPI library in Open MPI v4.0.x._ This enables legacy MPI applications to link and run successfully with Open MPI v4.0.x, even though they will fail to compile.

*The Open MPI team strongly encourages all MPI application developers to stop using these constructs that were first deprecated over 20 years ago, and finally removed from the MPI specification in MPI-3.0 (in 2012).* The FAQ items in this category show how to update your application to stop using these removed symbols.

All that being said, if you are unable to immediately update your application to stop using these removed MPI-1 symbols, you can re-enable them in mpi.h by configuring Open MPI with the --enable-mpi1-compatibility flag.

NOTE: Future releases of Open MPI beyond the v4.0.x series may remove these symbols altogether.

The Open MPI developer community decided to take a first step of removing the prototypes for these symbols from mpi.h starting with the Open MPI v4.0.x series for the following reasons:

1. These symbols have been deprecated since 1996. That's 28 years ago! It's time to start raising awareness for developers who are inadvertantly still using these removed symbols.
2. The MPI Forum removed these symbols from the MPI-3.0 specification in 2012. This is a sign that the Forum itself recognizes that these removed symbols are no longer needed.
3. Note that Open MPI did not fully remove these removed symbols: we just made it slightly more painful to get to them. This is an attempt to raise awareness so that MPI application developers can update their applications (it's easy!).

In short: the only way to finally be able to remove these removed symbols from Open MPI someday is to have a "grace period" where the MPI application developers are a) made aware that they are using removed symbols, and b) educated how to update their applications.

We, the Open MPI developers, recognize that your MPI application failing to compile with Open MPI may be a nasty surprise. We apologize for that.

Our intent is simply to use this minor shock to raise awareness and use it as an educational opportunity to show you how to update your application (or direct your friendly neighborhood MPI application developer to this FAQ) to stop using these removed MPI symbols.

Thank you!

You are getting deprecation warnings because you are using symbols / functions that are deprecated in MPI. For example:

1
2
3
4
5
6
7
8
9

shell$ mpicc deprecated-example.c -c
deprecated-example.c: In function 'foo':
deprecated-example.c:6:5: warning: 'MPI_Attr_delete' is deprecated: MPI_Attr_delete was deprecated in MPI-2.0; use MPI_Comm_delete_attr instead [-Wdeprecated-declarations]
     MPI_Attr_delete(MPI_COMM_WORLD, 2);
     ^~~~~~~~~~~~~~~
In file included from deprecated-example.c:2:
/usr/local/openmpi/include/mpi.h:2601:20: note: declared here
 OMPI_DECLSPEC  int MPI_Attr_delete(MPI_Comm comm, int keyval)
                    ^~~~~~~~~~~~~~~

Note that the deprecation compiler warnings tells you how to upgrade your code to avoid the deprecation warnings. In this example, it advises you to use MPI_Comm_delete_attr() instead of MPI_Attr_delete().

Also, note that when using --enable-mpi1-compatibility to re-enable removed MPI-1 symbols you will still get compiler warnings when you use the removed symbols. For example:

1
2
3
4
5
6
7
8
9

shell$ mpicc deleted-example.c -c
deleted-example.c: In function 'foo':
deleted-example.c:8:5: warning: 'MPI_Address' is deprecated: MPI_Address was removed in MPI-3.0; use MPI_Get_address instead. [-Wdeleted-declarations]
     MPI_Address(buffer, &address);
     ^~~~~~~~~~~
In file included from deleted-example.c:2:
/usr/local/openmpi/include/mpi.h:2689:20: note: declared here
 OMPI_DECLSPEC  int MPI_Address(void *location, MPI_Aint *address)
                    ^~~~~~~~~~~

In C, the only thing that changed was the function name: MPI_Address() → MPI_Get_address(). Nothing else needs to change:

1
2
3
4
5
6
7
8

char buffer[30];
MPI_Aint address;
 
// Old way
MPI_Address(buffer, &address);
 
// New way
MPI_Get_address(buffer, &address);

In Fortran, the type of the parameter changed from INTEGER → INTEGER(KIND=MPI_ADDRESS_KIND) so that it can hold larger values (e.g., 64 bit pointers):

 USE mpi
 REAL buffer
 INTEGER ierror
 INTEGER old_address
 INTEGER(KIND = MPI_ADDRESS_KIND) new_address
 
 ! Old way
 CALL MPI_ADDRESS(buffer, old_address, ierror)
 
 ! New way
 CALL MPI_GET_ADDRESS(buffer, new_address, ierror)

In C, effectively the only thing that changed was the name of the function: MPI_Errhandler_create() → MPI_Comm_create_errhandler().

Technically, the type of the first parameter also changed ( MPI_Handler_function → MPI_Comm_errhandler_function), but most applications do not use this type directly and may not even notice the change.

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15

void my_errhandler_function(MPI_Comm *comm, int *code, ...)
{
    // Do something useful to handle the error
}
 
void some_function(void)
{
    MPI_Errhandler my_handler;
 
    // Old way
    MPI_Errhandler_create(my_errhandler_function, &my_handler);
 
    // New way
    MPI_Comm_create_errhandler(my_errhandler_function, &my_handler);
}

In Fortran, only the subroutine name changed: MPI_ERRHANDLER_CREATE → MPI_COMM_CREATE_ERRHANDLER.

 USE mpi
 EXTERNAL my_errhandler_function
 INTEGER ierror
 INTEGER my_handler
 
 ! Old way
 CALL MPI_ERRHANDLER_CREATE(my_errhandler_function, my_handler, ierror)
 
 ! Old way
 CALL MPI_COMM_CREATE_ERRHANDLER(my_errhandler_function, my_handler, ierror)

In both C and Fortran, the only thing that changed with regards to MPI_ERRHANDLER_GET is the name: MPI_ERRHANDLER_GET → MPI_COMM_GET_ERRHANDLER.

All parameter types stayed the same.

In both C and Fortran, the only thing that changed with regards to MPI_ERRHANDLER_SET is the name: MPI_ERRHANDLER_SET → MPI_COMM_SET_ERRHANDLER.

All parameter types stayed the same.

In both C and Fortran, effectively the only change is the name of the function: MPI_TYPE_HINDEXED → MPI_TYPE_CREATE_HINDEXED.

In C, the new function also has a const attribute on the two array parameters, but most applications won't notice the difference.

All other parameter types stayed the same.

1
2
3
4
5
6
7
8
9
10

int count = 2;
int block_lengths[] = { 1, 2 };
MPI_Aint displacements[] = { 0, sizeof(int) };
MPI_Datatype newtype;
 
// Old way
MPI_Type_hindexed(count, block_lengths, displacements, MPI_INT, &newtype);
 
// New way
MPI_Type_create_hindexed(count, block_lengths, displacements, MPI_INT, &newtype);

In both C and Fortran, the only change is the name of the function: MPI_TYPE_HVECTOR → MPI_TYPE_CREATE_HVECTOR.

All parameter types stayed the same.

In both C and Fortran, effectively the only change is the name of the function: MPI_TYPE_STRUCT → MPI_TYPE_CREATE_STRUCT.

In C, the new function also has a const attribute on the three array parameters, but most applications won't notice the difference.

All other parameter types stayed the same.

1
2
3
4
5
6
7
8
9
10
11

int count = 2;
int block_lengths[] = { 1, 2 };
MPI_Aint displacements[] = { 0, sizeof(int) };
MPI_Datatype datatypes[] = { MPI_INT, MPI_DOUBLE };
MPI_Datatype newtype;
 
// Old way
MPI_Type_struct(count, block_lengths, displacements, datatypes, &newtype);
 
// New way
MPI_Type_create_struct(count, block_lengths, displacements, datatypes, &newtype);

In both C and Fortran, the MPI_TYPE_EXTENT function is superseded by the slightly-different MPI_TYPE_GET_EXTENT function: the new function also returns the lower bound.

1
2
3
4
5
6
7
8

MPI_Aint lb;
MPI_Aint extent;
 
// Old way
MPI_Type_extent(MPI_INT, &extent);
 
// New way
MPI_Type_get_extent(MPI_INT, &lb, &extent);

In both C and Fortran, the MPI_TYPE_LB function is superseded by the slightly-different MPI_TYPE_GET_EXTENT function: the new function also returns the extent.

1
2
3
4
5
6
7
8

MPI_Aint lb;
MPI_Aint extent;
 
// Old way
MPI_Type_lb(MPI_INT, &lb);
 
// New way
MPI_Type_get_extent(MPI_INT, &lb, &extent);

In both C and Fortran, the MPI_TYPE_UB function is superseded by the slightly-different MPI_TYPE_GET_EXTENT function: the new function returns the lower bound and the extent, which can be used to compute the upper bound.

1
2
3
4
5
6
7
8
9

MPI_Aint lb, ub;
MPI_Aint extent;
 
// Old way
MPI_Type_ub(MPI_INT, &ub);
 
// New way
MPI_Type_get_extent(MPI_INT, &lb, &extent);
ub = lb + extent

Note the ub calculation after calling MPI_Type_get_extent().

The MPI_LB and MPI_UB positional markers were fully replaced with MPI_TYPE_CREATE_RESIZED in MPI-2.0.

Prior to MPI-2.0, MPI_UB and MPI_LB were intended to be used as input to MPI_TYPE_STRUCT (which, itself, has been deprecated and renamed to MPI_TYPE_CREATE_STRUCT). The same end effect can now be achieved with MPI_TYPE_CREATE_RESIZED. For example, using the old method:

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15

int count = 3;
int block_lengths[] = { 1, 1, 1 };
MPI_Aint displacements[] = { -2, 0, 10 };
MPI_Datatype datatypes[] = { MPI_LB, MPI_INT, MPI_UB };
MPI_Datatype newtype;
 
MPI_Type_struct(count, block_lengths, displacements, datatypes, &newtype);
MPI_Type_commit(&newtype);
 
MPI_Aint ub, lb, extent;
MPI_Type_lb(newtype, &lb);
MPI_Type_ub(newtype, &ub);
MPI_Type_extent(newtype, &extent);
printf("OLD: LB=%d, UB=%d, extent=%d\n",
       lb, ub, extent);

If we run the above, we get an output of:

1

OLD: LB=-2, UB=10, extent=12

The MPI_TYPE_RESIZED function allows us to take any arbitrary datatype and set the lower bound and extent directly (which indirectly sets the upper bound), without needing to setup the arrays and computing the displacements necessary to invoke MPI_TYPE_CREATE_STRUCT.

Aside from the printf statement, the following example is exactly equivalent to the prior example (see this FAQ entry for a mapping of MPI_TYPE_UB to MPI_TYPE_GET_EXTENT):

1
2
3
4
5
6
7
8
9
10

MPI_Datatype newtype;
 
MPI_Type_create_resized(MPI_INT, -2, 12, &newtype);
MPI_Type_commit(&newtype);
 
MPI_Aint ub, lb, extent;
MPI_Type_get_extent(newtype, &lb, &extent);
ub = lb + extent;
printf("NEW: LB=%d, UB=%d, extent=%d\n",
       lb, ub, extent);

If we run the above, we get an output of:

1

NEW: LB=-2, UB=10, extent=12

The MPI_COMBINER_HINDEXED_INTEGER, MPI_COMBINER_HVECTOR_INTEGER, and MPI_COMBINER_STRUCT_INTEGER constants could previously be returned from MPI_TYPE_GET_ENVELOPE.

Starting with MPI-3.0, these values will never be returned. Instead, they will just return the same names, but without the _INTEGER suffix. Specifically:

If your Fortran code is using any of the _INTEGER-suffixed names, you can just delete the _INTEGER suffix.

The MPI_Handler_function C type is only used in the deprecated/removed function MPI_Errhandler_create(), as described in this FAQ entry.

Most MPI applications likely won't use this type at all. But if they do, they can simply use the new, exactly-equivalent type name (i.e., the return type, number, and type of parameters didn't change): MPI_Comm_errhandler_function.

1
2
3
4
5
6
7
8
9
10
11
12
13

void my_errhandler_function(MPI_Comm *comm, int *code, ...)
{
    // Do something useful to handle the error
}
 
void some_function(void)
{
    // Old way
    MPI_Handler_function *old_ptr = my_errhandler_function;
 
    // New way
    MPI_Comm_errhandler_function *new_ptr = my_errhandler_function;
}

The MPI_Handler_function type isn't used at all in the Fortran bindings.