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