9.5. Removed MPI constructs

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:

Note

You may need to scroll right in the following table.

Removed symbol (click for more details, below)	Replaced with (click to go to the corresponding man page)	Deprecated	Removed
MPI_ADDRESS	MPI_GET_ADDRESS	MPI-2.0 (1996)	MPI-3.0 (2012)
MPI_ERRHANDLER_CREATE	MPI_COMM_CREATE_ERRHANDLER	MPI-2.0 (1996)	MPI-3.0 (2012)
MPI_ERRHANDLER_GET	MPI_COMM_GET_ERRHANDLER	MPI-2.0 (1996)	MPI-3.0 (2012)
MPI_ERRHANDLER_SET	MPI_COMM_SET_ERRHANDLER	MPI-2.0 (1996)	MPI-3.0 (2012)
MPI_TYPE_EXTENT	MPI_TYPE_GET_EXTENT	MPI-2.0 (1996)	MPI-3.0 (2012)
MPI_TYPE_HINDEXED	MPI_TYPE_CREATE_HINDEXED	MPI-2.0 (1996)	MPI-3.0 (2012)
MPI_TYPE_HVECTOR	MPI_TYPE_CREATE_HVECTOR	MPI-2.0 (1996)	MPI-3.0 (2012)
MPI_TYPE_LB	MPI_TYPE_GET_EXTENT	MPI-2.0 (1996)	MPI-3.0 (2012)
MPI_TYPE_STRUCT	MPI_TYPE_CREATE_STRUCT	MPI-2.0 (1996)	MPI-3.0 (2012)
MPI_TYPE_UB	MPI_TYPE_GET_EXTENT	MPI-2.0 (1996)	MPI-3.0 (2012)
MPI_LB	MPI_TYPE_CREATE_RESIZED	MPI-2.0 (1996)	MPI-3.0 (2012)
MPI_UB	MPI_TYPE_CREATE_RESIZED	MPI-2.0 (1996)	MPI-3.0 (2012)
MPI_COMBINED_HINDEXED_INTEGER	MPI_COMBINER_HINDEXED	MPI-2.0 (1996)	MPI-3.0 (2012)
MPI_COMBINED_HVECTOR_INTEGER	MPI_COMBINER_HVECTOR	MPI-2.0 (1996)	MPI-3.0 (2012)
MPI_COMBINED_STRUCT_INTEGER	MPI_COMBINER_STRUCT	MPI-2.0 (1996)	MPI-3.0 (2012)
MPI_HANDLER_FUNCTION	MPI_COMM_ERRHANDLER_FUNCTION	MPI-2.0 (1996)	MPI-3.0 (2012)

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

Furthermore, the MPI C++ interfaces were deprecated in version 2.2, and then were removed in MPI-3.0. Starting from v5.0.0, Open MPI does not support the C++ interfaces any more. Users who would like to continue using the C++ interfaces of MPI will need to use an older release of Open MPI.

Warning

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 may remove these symbols altogether.

9.5.1. Why is Open MPI breaking the compilation of MPI applications?

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

The first set of symbols have been deprecated since 1996. It’s time to start raising awareness for developers who are inadvertently still using these removed symbols.
The MPI Forum removed a substantial set of 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.
More functions have been deprecated in MPI 2.2 and MPI 4.0, and additional functions are expected to be deprecated and removed in future MPI versions. It is in the interest of both, developers and end-users, to minimize confusion as much as possible, and stick closely to the MPI specification.
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!

9.5.2. Stop using MPI_ADDRESS

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

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)

9.5.3. Stop using MPI_ERRHANDLER_CREATE

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.

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)

! New way
CALL MPI_COMM_CREATE_ERRHANDLER(my_errhandler_function, my_handler, ierror)

9.5.4. Stop using MPI_ERRHANDLER_GET

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.

9.5.5. Stop using MPI_ERRHANDLER_SET

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.

9.5.6. Stop using MPI_TYPE_HINDEXED

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.

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);

9.5.7. Stop using MPI_TYPE_HVECTOR

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.

9.5.8. Stop using MPI_TYPE_STRUCT

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.

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);

9.5.9. Stop using MPI_TYPE_EXTENT

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.

MPI_Aint lb;
MPI_Aint extent;

// Old way
MPI_Type_extent(MPI_INT, &extent);

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

9.5.10. Stop using MPI_TYPE_LB

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.

MPI_Aint lb;
MPI_Aint extent;

// Old way
MPI_Type_lb(MPI_INT, &lb);

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

9.5.11. Stop using MPI_TYPE_UB

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.

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().

9.5.12. Stop using MPI_LB / MPI_UB

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:

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:

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 the MPI_TYPE_UB section for a mapping of MPI_TYPE_UB to MPI_TYPE_GET_EXTENT):

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:

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

9.5.13. Stop using MPI_COMBINER_HINDEXED_INTEGER, MPI_COMBINER_HVECTOR_INTEGER, and MPI_COMBINER_STRUCT_INTEGER

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:

MPI_COMBINER_HINDEXED_INTEGER → MPI_COMBINER_HINDEXED
MPI_COMBINER_HVECTOR_INTEGER → MPI_COMBINER_HVECTOR
MPI_COMBINER_STRUCT_INTEGER → MPI_COMBINER_STRUCT

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

9.5.14. Stop using MPI_Handler_function

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

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.

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.