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(*	undeclared [SCOREP_SUBSTRATE_PLUGIN_UNDEFINED_MANAGEMENT_FUNCTIONS])(void)
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:

• Called per process
  1. (...Score-P initialization part 1, e.g. environment variables...)
  2. resolving of SCOREP_SUBSTRATE_PLUGIN_ENTRY, e.g., for SCOREP_SUBSTRATE_PLUGINS=foo check whether there is a library called libscorep_substrate_foo.so that provides a SCOREP_SUBSTRATE_PLUGIN_ENTRY(foo) / holds the function SCOREP_SubstratePlugin_foo_get_info
  3. init()
  4. set_callbacks()
  5. get_event_functions( ) with mode == SCOREP_SUBSTRATES_RECORDING_ENABLED
  6. get_event_functions( ) with mode == SCOREP_SUBSTRATES_RECORDING_DISABLED
  7. From now on at any point in time there can be new definitions created via new_definition_handle(). Definitions are unique in a process context. Thus, two different locations within a process can use the same definitions and there are no handles that are only valid for a specific location. Plugins should care for thread safeness when registering handles in internal data structures.
  8. From now on at any point in time there can be calls to get_requirement( )
  9. (...Score-P initialization part 2...)
  10. assign_id()
  11. create_location() for the main thread
  12. As soon as the MPP paradigm is initialized, init_mpp() is called. If the program does not use MPP paradigms, init_mpp() will also be called
  13. (...Score-P initialization part 3...)
  14. Called for each location (e.g., thread)
      1. create_location() (Only new locations, remember that the main thread location is already created earlier!)
      2. if it is a CPU location: activate_cpu_location()
      3. Now there is a sequence of these events
         • if it is a CPU location:
           • (optional) calls to deactivate_cpu_location() followed by calls to activate_cpu_location()
           • (optional) core_task_create(), possibly followed by runtime events, followed by core_task_complete()
         • (optional) runtime events
      4. if it is a CPU location: deactivate_cpu_location()
      5. delete_location()
  15. pre_unify()
  16. write_data()
  17. finalize()

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.

Examples:

print_regions.c.

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

create_location

deactivate_cpu_location

delete_location

Parameters

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.

Parameters

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.

Examples:

print_regions.c.

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

Parameters

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

Parameters

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:

• create_location
  • initial activate_cpu_location()
  • (optional) interim deactivate_cpu_location(), followed by activate_cpu_location()
  • final deactivate_cpu_location()
• delete_location

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.

Parameters

location	location which is created
parentLocation	location that created this location

Examples:

print_regions.c.

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

create_location

activate_cpu_location

Parameters

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

See also

create_location

Parameters

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

Parameters

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.

Returns

MUST return SCOREP_SUBSTRATES_NUM_EVENTS (see SCOREP_SubstrateEvents.h)

Examples:

print_regions.c.

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.

Parameters

flag	the requirement flag that is queried

Returns

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.

Returns

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.

Parameters

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)

Examples:

print_regions.c.

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.

Parameters

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

Examples:

print_regions.c.

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.

---

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

• SCOREP_SubstratePlugins.h