Side document for semi-standardized pcontrol/pcontrol_x values

[jprotze]

Based on #26, a new side document should define some common practice for level values and how the void* arg should be interpreted for the specific level.

A first use case is user-defined region marker (with a tool implementation for Score-P):

std::unordered_map <std::string, SCOREP_User_RegionHandle> regions;
MPI_Pcontrol_tool
MPI_Pcontrol_x
MPI_Pinstrument(int level, void* arg){
  if(level == 9093){
    std::string name{(const char*)arg};
    const auto [it, success] = regions.insert(std::pair{name, SCOREP_USER_INVALID_REGION});
    if(success){
      SCOREP_USER_REGION_INIT( it->second, arg, SCOREP_USER_REGION_TYPE_COMMON );
    }
    SCOREP_USER_REGION_ENTER( it->second )
  }
  if(level == 9094){
    std::string name{(const char*)arg};
    const it = regions.find(name);
    assert(it != regions.end())
    SCOREP_USER_REGION_END( it->second )
  }
}


#define USER_BEGIN(name) MPI_Pcontrol(9093, name)
#define USER_END(name)   MPI_Pcontrol(9094, name)

In this case, for levels 9093 and 9094, the void* arg must be a null-byte terminated char array. The level value 9093 marks the begin of a user-defined region with the name passed to arg and the level value 9094 marks the end of a user-defined region with the same name.
Some tools might have strict nesting requirements for regions. For portable use, begin and end of a user-defined region must be at the same nesting level, in the same function/procedure context.