5.0-trunk (revision 14702)
|
#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(* | undeclared [SCOREP_SUBSTRATE_PLUGIN_UNDEFINED_MANAGEMENT_FUNCTIONS])(void) |
void(* | write_data )(void) |
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.
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.
location | location which is activated |
parentLocation | parent of location. May be equal locationData. |
forkSequenceCount | an 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_id | a 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
location | the location that completes the task |
taskHandle | the 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
location | the location that created the task |
taskHandle | the 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:
location | location which is created |
parentLocation | location 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
location | location which is deactivated |
parentLocation | parent 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
location | location 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
mode | defines which function set should be returned either for disabled or enabled recording. |
functions | a 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. |
SCOREP_SubstrateEvents.h
) 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.
flag | the requirement flag that is queried |
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.
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.
handle | a handle to the newly created object |
type | the 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.
callbacks | the provided function callbacks |
sizeof(SCOREP_SubstrateCallbacks) | The plugin should care that its version of SCOREP_SubstrateCallbacks is smaller or equal size |
void( * SCOREP_SubstratePluginInfo::undeclared[ SCOREP_SUBSTRATE_PLUGIN_UNDEFINED_MANAGEMENT_FUNCTIONS ])(void) |
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.