Add new variant of MPI_Pcontrol that allows Fortran to pass more than just an integer value

[jprotze]

The C and Fortran bindings of MPI_Pcontrol are:

int MPI_Pcontrol(const int level, ...)

MPI_Pcontrol(level)
    INTEGER, INTENT(IN) :: level

Being a variadic function in C, there is no way to call the C function from Fortran, so the only option is to call the Fortran API function with the limitation of having only a single integer value.

The OMPT interface has a similar function defined as omp_control_tool(int command, int modifier, void* arg). Using bind-c, Fortran applications can use this function to pass information like a string to the tool.

The idea is to introduce a new MPI_P function to pass information to tools:

int MPI_Px(int level, void* arg)

Suggested names in the discussion: MPI_Pcontrol_tool, MPI_Pcontrol_x, MPI_Pinstrument

[mahermanns]

Meeting Notes 2026-03-30

• No special/extra versioning needed
  • A level always corresponds to a specific arg data structure
  • If arg needs to be adapted a new level should be introduced
• Need for a special return value (e.g., MPI_P_UNUSED_LEVEL) if level is not used by any of the attached tools
  • A tool using a level will always return MPI_SUCCESS, no matter what an inner call returned
  • A tool not using a level will return the return value from the inner call (if it was not MPI_P_NO_TOOL)
• Need for a special return value (e.g., MPI_P_NO_TOOL) if no tool was attached (to document that a tool was part of the measurement or not)
  • Implementation returns MPI_P_NO_TOOLS, a tool will return either MPI_SUCCESS or MPI_P_UNUSED_LEVEL
• Call & reserved highest level (ever) defined by the side document should be in the main document
• Sidedoc should specify for each level a specific arg
• Sidedoc will never define a level above the "threshold"