openmpi/ompi/mpiext

Symbol conventions for Open MPI extensions

Last updated: January 2015

This README provides some rule-of-thumb guidance for how to name symbols in Open MPI extensions. Every case is different; we've had long discussions about what to name various functions, constants, etc. This document is an attempt to capture a few common rules-of-thumb that we've agreed upon for how to name symbols in new MPI extensions.

Generally speaking, there are usually three kinds of extensions:

1. Functionality that is solely intended for Open MPI.
2. Functionality which may spread to both other MPI implementations and/or, ultimately, the MPI standard.
3. Functionality that is strongly expected to be in an upcoming version of the MPI specification.

Case 1

The OMPI_Paffinity_str() extension is a good example of this type: it is solely intended to be for Open MPI. It will likely never be pushed to other MPI implementations, and it will likely never be pushed to the MPI Forum.

It's Open MPI-specific functionality, through and through.

Public symbols of this type of functionality should be named with an OMPI_ prefix to emphasize its Open MPI-specific nature. To be clear: the OMPI_ prefix clearly identifies parts of user code that are relying on Open MPI (and likely need to be surrounded with #if OPEN_MPI blocks, etc.).

Case 2

The MPI extensions mechanism in Open MPI was designed to help MPI Forum members prototype new functionality that is intended for the MPI specification itself. As such, the goal for this kind of functionality is not only to be included in the MPI spec, but possibly also be included in another MPI implementation.

As such, it seems reasonable to prefix public symbols in this type of functionality with MPIX_. This commonly-used prefix allows the same symbols to be available in multiple MPI implementations, and therefore allows user code to easily check for it. E.g., user apps can check for the presence of MPIX_Foo to know if both Open MPI and Other MPI support the proposed MPIX_Foo functionality.

Of course, when using the MPIX_ namespace, there is the possibility of symbol name collisions. E.g., what if Open MPI has an MPIX_Foo and Other MPI has a different MPIX_Foo?

While we technically can't prevent such collisions from happening, we encourage extension authors to avoid such symbol clashes whenever possible.

Case 3

It is well-known that the MPI specification (intentionally) takes a long time to publish. MPI implementers can typically know, with a high degree of confidence, about new functionality that almost certainly will be included in an upcoming MPI specification long before it is actually published.

For a variety of reasons, Open MPI has tried to implement such functionality early (i.e., before the actual publication of the corresponding MPI specification document).

Case in point: the non-blocking collective operations that were included in MPI-3.0 (e.g., MPI_Ibarrier()). It was known for a year or two before MPI-3.0 was published that these functions would be included in MPI-3.0.

There is a continual debate among the developer community: when implementing such functionality, should the symbols be in the MPIX_ namespace or in the MPI_ namespace? On one hand, the symbols are not yet officially standardized -- they could change before publication. On the other hand, developers who participate in the Forum typically have a good sense for whether symbols are going to change before publication or not. On the other hand (yes, we all have three hands), no one can predict the future -- things could unexpectedly change before the MPI specification is published. ...and so on.

After much debate: for functionality that has a high degree of confidence that it will be included in an upcoming spec (e.g., it has passed at least one vote in the MPI Forum), our conclusion is that it is OK to use the MPI_ namespace.

Case in point: Open MPI released non-blocking collectives with the MPI_ prefix (not the MPIX_ prefix) before the MPI-3.0 specification officially standardized these functions.

The rationale was threefold:

1. Let users use the functionality as soon as possible.
2. If OMPI initially creates MPIX_Foo, but eventually renames it to MPI_Foo when the MPI specification is published, then users will have to modify their codes to match. This is an artificial change inserted just to be "pure" to the MPI spec (i.e., it's a "lawyer's answer"). But since the MPIX_Foo -> MPI_Foo change is inevitable, it just ends up annoying users.
3. Once OMPI introduces MPIX_ symbols, if we want to not annoy users, we'll likely have weak symbols / aliased versions of both MPIX_Foo and MPI_Foo once the Foo functionality is included in a published MPI specification. However, when can we delete the MPIX_Foo symbol? It becomes a continuing annoyance of backwards compatibility that we have to keep carrying forward.

For all these reasons, we believe that it's better to put expected-upcoming official MPI functionality in the MPI_ namespace, not the MPIX_ namespace.

All that being said, these are rules of thumb. They are not an official mandate. There may well be cases where there are reasons to do something different than what is outlined above.