Application Performance Snapshot User Guide for Linux* OS

ID 772048
Date 11/07/2023

Region Control with MPI_Pcontrol

Application Performance Snapshot supports the region control with the MPI_Pcontrol() operation. This allows you to enable and disable statistics collection for specific application regions in the source code. Region control only affects MPI and OpenMP* metrics, while the other ones will still be collected for the entire application.

By default, the statistics collection is enabled for the entire application. To disable the collection starting from a certain point, insert the MPI_Pcontrol(0) call in your code. Similarly, insert the MPI_Pcontrol(1) call to enable collection again. For example:

MPI_Comm_size (MPI_COMM_WORLD, &size);
MPI_Comm_rank (MPI_COMM_WORLD, &rank);

MPI_Pcontrol() also allows you to mark specific code regions using unique numbers (5 and higher). Use a MPI_Pcontrol(<region>) call to mark the beginning of the region, and use MPI_Pcontrol(-<region>) to mark the end of the region. You can mark several non-contiguous code sections with the same region number to include them into the same region. MPI_Pcontrol(0) and MPI_Pcontrol(1) disable and enable statistics collection for all regions at once, respectively.

The following example demonstrates how to mark code regions with MPI_Pcontrol():

if (rank == 0) {
    for (i = 1; i < size; i++)
        MPI_Recv (&rank, 1, MPI_INT, i, 1, MPI_COMM_WORLD, &stat);
else {
    MPI_Send (&rank, 1, MPI_INT, 0, 1, MPI_COMM_WORLD);

If an application contains regions, the statistics will be collected for the entire application and for that region specifically. Region statistics data is saved in a separate folder aps_result_<date>_<region>, for example aps_result_20171231_6.

As it was mentioned above, region numbers from 0 to 4 are unavailable (0 and 1 have special meanings; 2, 3 and 4 are ignored), and regular regions start with the number 5. You can change this behavior and also make 1, 2, 3 and 4 regular regions, or make regular regions start with a greater number. To do so, set the MPS_PCONTROL_REGION_BEGIN environment variable to the desired value.


According to the MPI standard, MPI_Pcontrol() can have a variable number of arguments. For Application Performance Snapshot, only the first argument is relevant.