Developer information

This section gives an overview about the interfaces of different components of MPI-Start for developing new plugins.

Variables

All necessary information of the mpi-start program are provided via environment variables. See ../UserDocumentation and ../SiteConfiguration for a list of those variables.

Logging and debugging

The I2G_MPI_START_VERBOSE variable can be set to 1 to turn on the additional output. For debugging purpose the I2G_MPI_START_DEBUG variable can be set to 1 to enable the debugging output. The variable I2G_MPI_START_TRACE can be set to 1 to trace every operation that is performed by mpi-start (goes to stderr).

The functions for logging messages to output are the following:

• error_msg: always prints message

• debug_msg: prints message if both I2G_MPI_START_VERBOSE and I2G_MPI_START_DEBUG are set

• info_msg & warn_msg: print message if I2G_MPI_START_VERBOSE is set

The dump_vars function dumps the complete environment to the output.

Scheduler plugins

A scheduler plugin is responsible for detection of a runtime system and the definition of process distribution variables. A scheduler plugin must provide the following functions and variables:

• scheduler_available
  • This function is called to detect if the job is running in the supported environment or not. If the supported environment is found 0 must be returned, else -1.
• scheduler_get_machinefile
  • After the successfully detection of a scheduler environment this function is called to set the all process distribution variables.
• SCHEDULER_NAME
  • A variable containing the name of the scheduler, it may be used later by the execution environment plugins to select the best way for starting the application.

The process distribution variables that the scheduler plugin must set are:

Execution environment plugins

A Execution Environment plugin is responsible for setting up the environment for the specified execution environment (MPI) version. It has to provide the following functions:

• mpi_start
  • This function is called by the mpi-start core to start a parallel job. This function consists (at least) of the following steps:
    1. setup parallel environment if necessary (e.g. start daemons)
    2. activate the pre-run hooks (call mpi_start_pre_run_hook)
    3. call mpi_exec to start the parallel job
    4. activate the post-run hooks (call mpi_start_post_run_hook)
    5. shutdown parallel environment if necessary (e.g. shutdown daemons)

    A generic_mpistart.sh file contains this core functionality for development of new plugins.

• mpi_exec
  • This function actually perform the execution of the parallel job (mpirun/mpiexec). This functionality has been separated from the setup/shutdown phase to allow usage of the parallel environment in the pre-/post-run hooks.

Several internal variables may change the behavior of the execution environment:

In order to provide a different environment for the user application, MPI-Start uses a wrapper that is executed as a different process. In this wrapper, the variables defined in the MPI_START_ENV_VARIABLES are exported to the environment. The use of the wrapper can be controlled with the functions:

• mpi_start_export_variable var_name [value] Adds the variable var_name to MPI_START_ENV_VARIABLES and to the wrapper script, if value is defined, set it also in the wrapper.

• mpi_start_execute_wrapper cmd_line: Executes the specified command line in cmd_line. If MPI_START_DO_NOT_USE_WRAPPER is set to 1 it will not use a wrapper and therefore the environment variables may not be defined.

Clean up

When mpi-start finishes its execution the clean_up function is called. This will remove any temporary files created by MPI-Start by default (e.g. host files) and any other file appended to the MPI_START_CLEANUP_FILES variable.

Hooks

See Hooks Frameworkfor a complete description of the hooks mechanism and how to develop new hooks.