From e855b19ba2177d83f5b457d644dc4b25573afec9 Mon Sep 17 00:00:00 2001 From: Jeff Squyres Date: Thu, 29 Jan 2015 06:39:44 -0600 Subject: [PATCH] MPI extensions: rules of thumb about symbol names This document is the result of a George Bosilca/Jeff Squyres discussion at the developer meeting in Dallas in January of 2015. It attempts to provide some rules of thumb / guidance for naming conventions of symbols in MPI extensions. --- ompi/mpiext/README.txt | 124 +++++++++++++++++++++++++++++++++++++++++ 1 file changed, 124 insertions(+) create mode 100644 ompi/mpiext/README.txt diff --git a/ompi/mpiext/README.txt b/ompi/mpiext/README.txt new file mode 100644 index 0000000000..ccfb63dfe1 --- /dev/null +++ b/ompi/mpiext/README.txt @@ -0,0 +1,124 @@ +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.