8.4. Removed MPI constructs

Error

TODO This section needs to be renamed/updated for the 5.0.0 behavior.

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

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.

8.4.1. Why on earth are you breaking the compilation of MPI applications?

Error

TODO This section needs to be renamed/updated (or deleted?) for the 5.0.0 behavior.

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. It’s time to start raising awareness for developers who are inadvertently 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!

8.4.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 $right_arrow 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)

8.4.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_functionMPI_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_CREATEMPI_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)

8.4.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_GETMPI_COMM_GET_ERRHANDLER.

All parameter types stayed the same.

8.4.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_SETMPI_COMM_SET_ERRHANDLER.

All parameter types stayed the same.

8.4.6. Stop using MPI_TYPE_HINDEXED

In both C and Fortran, effectively the only change is the name of the function: MPI_TYPE_HINDEXEDMPI_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);

8.4.7. Stop using MPI_TYPE_HVECTOR

In both C and Fortran, the only change is the name of the function: MPI_TYPE_HVECTORMPI_TYPE_CREATE_HVECTOR.

All parameter types stayed the same.

8.4.8. Stop using MPI_TYPE_STRUCT

In both C and Fortran, effectively the only change is the name of the function: MPI_TYPE_STRUCTMPI_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);

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

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

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

8.4.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

8.4.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_INTEGERMPI_COMBINER_HINDEXED

  • MPI_COMBINER_HVECTOR_INTEGERMPI_COMBINER_HVECTOR

  • MPI_COMBINER_STRUCT_INTEGERMPI_COMBINER_STRUCT

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

8.4.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.