Change Compatibility in MPI

1. Change Compatibility in MPI

2. Guiding Principles for API Changes • “New MPI Developer Friendly” • Keep the “best” name for the provided functionality • Avoid mangling names to produce new routines that are extensions or corrections to existing routines (e.g. MPI_Init  MPI_Init_thread  MPI_Init_thread_foo  MPI_Init_thread_foo_bar) • “Old Code Friendly” • Require that old codes work with MPI-3, with only a recompilation.

3. Caveat for API Changes • By necessity, some of these changes dictate some aspects of an implementation • But, no more so than standard saying “MPI_Send must …” • Just at a different abstraction level/dimension

4. Categories of Changes • New - E.g. Introduction of completely new routine, such as non-blocking collective operations. • Change - E.g. Modifying routines to use MPI_Count for counts could fall into this category [or it could be new if we added a new set of APIs] • No change - no additional analysis is necessary. • Deprecated - E.g. MPI_Attr_get and MPI_Attr_put (assuming we don't want to remove them completely) • Removed - E.g. assume we remove the C++ bindings completely

5. Managing Changes to Existing Names • Use symbol-specific version numbering, with macro (or weak symbol?) mapping the “best” name to most current name, by default. • Use a global preprocessor macro to map all versioned symbols to the version provided by a particular version of MPI standard. • Use symbol-specific macro to override version mapping for a particular symbol.

6. Managing Changes to Existing Names - Example • Move to using “MPI_Count” typedef for message counts (ticket #117) • Many routines would change, for example, MPI_Bsend() would change: • From: int MPI_Bsend(void *buf, int count, MPI_Datatype datatype, int dest, int tag, MPI_Comm comm); • To: int MPI_Bsend(void *buf, MPI_Count count, MPI_Datatype datatype, int dest, int tag, MPI_Comm comm);

7. Managing Changes to Existing Names – MPI_Bsend Example, cont. • Versioned names for MPI_Bsend: • int MPI_Bsend1(void *buf, int count, MPI_Datatype datatype, int dest, int tag, MPI_Comm comm); • int MPI_Bsend2(void *buf, MPI_Count count, MPI_Datatype datatype, int dest, int tag, MPI_Comm comm); • MPI_Bsend name maps to one version (MPI_Bsend2, by default)

8. Managing Changes to Existing Names – MPI_Bsend Example, cont. x2 • To choose earlier version of all symbols in MPI, developer could define global “MPI_API_VERSION=22” macro, in one of three places: • At MPI configure & install time • Changes default for all applications • As a compile option [“-D …”] • Inside a particular source code module: • #define MPI_API_VERSION 22 • #include “mpi.h” • <code>

9. Managing Changes to Existing Names – MPI_Bsend Example, cont. x3 • To choose earlier version of just MPI_Bsend symbol, developer could define global “MPI_BSEND_VERSION=22” macro, in one of three places: • At MPI configure & install time • Changes default for all applications • As a compile option [“-D …”] • Inside a particular source code module: • #define MPI_BSEND_VERSION 22 • #include “mpi.h” • <code>

10. Managing Deprecating Names • Want to allow developer to detect deprecated name use without changing their code • Want to remove symbol from application visibility at some level: • Compile-time – “remove” symbol from header • Link-time – remove symbol from library binary • In order to allow maximum flexibility, choosing compile-time, with macros to control

11. Managing Deprecating Names • Use a global preprocessor macro to remove all versioned symbols prior to the current version of an MPI standard. • E.g. define “MPI_LOWEST_API_VERSION=30” to remove all versioned symbols except those available in the 3.0 standard or later • Use symbol-specific macro to remove versions for a particular symbol. • E.g. define “MPI_LOWEST_BSEND_VERSION=30” to remove versions of MPI_Bsend name defined prior to the 3.0 standard

12. To Do List • Build consensus – Are we on the right track? • Define mechanism for versioning Fortran symbols • Create compatibility checklist for ticket authors