7.0 (revision 7784de1c)
Data Fields
SCOREP_SubstratePluginInfo Struct Reference

#include <SCOREP_SubstratePlugins.h>

Data Fields

void(* activate_cpu_location )(const struct SCOREP_Location *location, const struct SCOREP_Location *parentLocation, uint32_t forkSequenceCount)
void(* assign_id )(size_t pluginId)
void(* core_task_complete )(const struct SCOREP_Location *location, SCOREP_TaskHandle taskHandle)
void(* core_task_create )(const struct SCOREP_Location *location, SCOREP_TaskHandle taskHandle)
void(* create_location )(const struct SCOREP_Location *location, const struct SCOREP_Location *parentLocation)
void(* deactivate_cpu_location )(const struct SCOREP_Location *location, const struct SCOREP_Location *parentLocation)
void(* delete_location )(const struct SCOREP_Location *location)
void(* dump_manifest )(FILE *manifestFile, const char *relativeSourceDir, const char *targetDir)
void(* finalize )(void)
uint32_t(* get_event_functions )(SCOREP_Substrates_Mode mode, SCOREP_Substrates_Callback **functions)
bool(* get_requirement )(SCOREP_Substrates_RequirementFlag flag)
int(* init )(void)
void(* init_mpp )(void)
void(* new_definition_handle )(SCOREP_AnyHandle handle, SCOREP_HandleType type)
uint32_t plugin_version
void(* pre_unify )(void)
void(* set_callbacks )(const SCOREP_SubstratePluginCallbacks *callbacks, size_t size)
void(* write_data )(void)

Detailed Description

Describes a Substrate plugin. The plugin definition should be done using the SCOREP_SUBSTRATE_PLUGIN_ENTRY macro The call order of these functions is:

Not implemented functions MUST point to NULL, e.g., info.assign_id = NULL;

Developer notice: When a new function is necessary, append it after the functions, but before undeclared. For each new function, decrease SCOREP_SUBSTRATE_PLUGIN_UNDEFINED_MANAGEMENT_FUNCTIONS by one. If this happens, increase SCOREP_PLUGIN_VERSION.


Field Documentation

void( * SCOREP_SubstratePluginInfo::activate_cpu_location) (const struct SCOREP_Location *location, const struct SCOREP_Location *parentLocation, uint32_t forkSequenceCount)

This function is called whenever a location is activated.

See also
locationlocation which is activated
parentLocationparent of location. May be equal locationData.
forkSequenceCountan increasing number which defines the current fork from parentLocation. At each fork (or omp parallel) this increases by 1.
void( * SCOREP_SubstratePluginInfo::assign_id) (size_t pluginId)

This function assigns a specific ID to the plugin that can be used for accessing thread local storage. However, most of the internal functionality is not available at the time this function is called. Therefore, only the id should be stored for now.

The function might be called multiple times when the Online Access interface is used and re-initializes Score-P.

plugin_ida specific ID that is assigned to the plugin and can be used to access thread local storages. (see also SCOREP_Location_SetData and SCOREP_Location_GetData) This ID is only valid for the current Score-P run.
void( * SCOREP_SubstratePluginInfo::core_task_complete) (const struct SCOREP_Location *location, SCOREP_TaskHandle taskHandle)

Called when a task (e.g., an OpenMP task) is completed The taskHandle is not defined via define_handle and can not be converted to SCOREP_AnyHandle

locationthe location that completes the task
taskHandlethe completed created task
void( * SCOREP_SubstratePluginInfo::core_task_create) (const struct SCOREP_Location *location, SCOREP_TaskHandle taskHandle)

Called when a task (e.g., an OpenMP task) is creates The taskHandle is not defined via define_handle and can not be converted to SCOREP_AnyHandle

locationthe location that created the task
taskHandlethe newly created task
void( * SCOREP_SubstratePluginInfo::create_location) (const struct SCOREP_Location *location, const struct SCOREP_Location *parentLocation)

The location callbacks notify the subsystem about the lifetime of a location. For CPU locations:

For none-CPU locations:

  1. create_location
  2. delete_location This function is called whenever a new location is created, e.g. whenever a new OpenMP thread is created.
locationlocation which is created
parentLocationlocation that created this location
void( * SCOREP_SubstratePluginInfo::deactivate_cpu_location) (const struct SCOREP_Location *location, const struct SCOREP_Location *parentLocation)

This function is called whenever a location is deactivated

See also
locationlocation which is deactivated
parentLocationparent of location. May be equal locationData.
void( * SCOREP_SubstratePluginInfo::delete_location) (const struct SCOREP_Location *location)

This function is called whenever a location is deleted

See also
locationlocation which is deleted
void( * SCOREP_SubstratePluginInfo::dump_manifest) (FILE *manifestFile, const char *relativeSourceDir, const char *targetDir)

This function is called during experiment directory creation and allows to write information about involved files to the Manifest file and initiate file copies if needed.

void( * SCOREP_SubstratePluginInfo::finalize) (void)

This function is called when the Score-P run finished

uint32_t( * SCOREP_SubstratePluginInfo::get_event_functions) (SCOREP_Substrates_Mode mode, SCOREP_Substrates_Callback **functions)

Get all functions for events, attributed to their SCOREP_Substrates_EventType

modedefines which function set should be returned either for disabled or enabled recording.
functionsa pointer to the functions that are assigned to the types. The returned array MUST hold SCOREP_SUBSTRATES_NUM_EVENTS elements. Not-implemented functions should be set to NULL. The array will NOT be free'd by Score-P.
bool( * SCOREP_SubstratePluginInfo::get_requirement) (SCOREP_Substrates_RequirementFlag flag)

Provide Score-P with additional information about requirements, see SCOREP_SubstratesRequirementFlag for details. If this function is not implemented, the default is assumed (0). This can be called at any time by any thread depending on the flag that is queried. Plugins must take care that they return 0 if flag is greater than SCOREP_SUBSTRATES_NUM_REQUIREMENT Plugins must always return the same value for a given flag during one execution.

flagthe requirement flag that is queried
the setting for the requirement flag, which highly depends on the type of flag
int( * SCOREP_SubstratePluginInfo::init) (void)

This function is called before most internal Score-P data is initialized. The plugin should be initialized here and dependencies should be checked.

0 if initialization succeeded, otherwise !=0
void( * SCOREP_SubstratePluginInfo::init_mpp) (void)

This function is called after MPP paradigms are initialized. If the program does not use MPP paradigms this function is also called. To detect used paradigms check for calls to new_definition_handle with type == SCOREP_HANDLE_TYPE_PARADIGM.

void( * SCOREP_SubstratePluginInfo::new_definition_handle) (SCOREP_AnyHandle handle, SCOREP_HandleType type)

This function will be called whenever a new definition is created Plugins can filter the processing of definitions according to the given type. Plugins should use the callbacks passed by set_callbacks, SCOREP_PublicHandles.h, and SCOREP_PublicTypes.h to make sense from the handle, (e.g., to get the name of a region) The handles can be unique for every process and are not necessarily comparable. It might be that this is called within a locked region. Therefore your implementation should be as lightweight as possible.

handlea handle to the newly created object
typethe type of the handle
uint32_t SCOREP_SubstratePluginInfo::plugin_version

Must be set to SCOREP_SUBSTRATE_PLUGIN_VERSION (needed for back- and forward compatibility)

void( * SCOREP_SubstratePluginInfo::pre_unify) (void)

This function is called before the data about different threads and MPI processes is collected and unified, i.e. when definitions are synchronized.

void( * SCOREP_SubstratePluginInfo::set_callbacks) (const SCOREP_SubstratePluginCallbacks *callbacks, size_t size)

Provide plugins with pointers to functions that can be used to get meta data about handles.

callbacksthe provided function callbacks
sizeof(SCOREP_SubstrateCallbacks)The plugin should care that its version of SCOREP_SubstrateCallbacks is smaller or equal size

for future extensions Plugins must set all entries of this list to 0 (e.g., via memset)

When a new function is added in Score-P, SCOREP_SUBSTRATE_PLUGIN_UNDEFINED_MANAGEMENT_FUNCTIONS should be decreased by 1. Score-P should check for an appropriate plugin_version before calling the new function. Otherwise, Score-P is not able to check whether this is set to 0 but might use an invalid function. This can be avoided by enforcing a correct plugin_version.

void( * SCOREP_SubstratePluginInfo::write_data) (void)

This function is called after the unification process when traces/profiles are written - right before finalize. This should be used to flush recorded data.

The documentation for this struct was generated from the following file: