#include <SCOREP_SubstratePlugins.h>

Data Fields
SCOREP_CallingContextHandle(*	SCOREP_CallingContextHandle_GetParent )(SCOREP_CallingContextHandle handle)

SCOREP_RegionHandle(*	SCOREP_CallingContextHandle_GetRegion )(SCOREP_CallingContextHandle handle)

void(*	SCOREP_ConfigManifestSectionEntry )(FILE out, const char fileName, const char *descriptionFormatString,...)
	Create formated entry in the manifest file consisting out of a name and a description, the latter in printf style and terminated with a period.

void(*	SCOREP_ConfigManifestSectionHeader )(FILE out, const char section)
	Create formated header in the manifest file.

const char (	SCOREP_GetExperimentDirName )(void)

int(*	SCOREP_Ipc_Allgather )(const void sendbuf, void recvbuf, int count, SCOREP_Ipc_Datatype datatype)

int(*	SCOREP_Ipc_Allreduce )(const void sendbuf, void recvbuf, int count, SCOREP_Ipc_Datatype datatype, SCOREP_Ipc_Operation operation)

int(*	SCOREP_Ipc_Barrier )(void)

int(*	SCOREP_Ipc_Bcast )(void *buf, int count, SCOREP_Ipc_Datatype datatype, int root)

int(*	SCOREP_Ipc_Gather )(const void sendbuf, void recvbuf, int count, SCOREP_Ipc_Datatype datatype, int root)

int(*	SCOREP_Ipc_Gatherv )(const void sendbuf, int sendcount, void recvbuf, const int *recvcnts, SCOREP_Ipc_Datatype datatype, int root)

int(*	SCOREP_Ipc_GetRank )(void)

int(*	SCOREP_Ipc_GetSize )(void)

int(*	SCOREP_Ipc_Recv )(void *buf, int count, SCOREP_Ipc_Datatype datatype, int source)

int(*	SCOREP_Ipc_Reduce )(const void sendbuf, void recvbuf, int count, SCOREP_Ipc_Datatype datatype, SCOREP_Ipc_Operation operation, int root)

int(*	SCOREP_Ipc_Scatter )(const void sendbuf, void recvbuf, int count, SCOREP_Ipc_Datatype datatype, int root)

int(*	SCOREP_Ipc_Scatterv )(const void sendbuf, const int sendcounts, void *recvbuf, int recvcount, SCOREP_Ipc_Datatype datatype, int root)

int(*	SCOREP_Ipc_Send )(const void *buf, int count, SCOREP_Ipc_Datatype datatype, int dest)

void (	SCOREP_Location_GetData )(const struct SCOREP_Location *locationData, size_t plugin_id)

uint64_t(*	SCOREP_Location_GetGlobalId )(const struct SCOREP_Location *locationData)

uint32_t(*	SCOREP_Location_GetId )(const struct SCOREP_Location *locationData)

const char (	SCOREP_Location_GetName )(const struct SCOREP_Location *locationData)

SCOREP_LocationType(*	SCOREP_Location_GetType )(const struct SCOREP_Location *locationData)

void(*	SCOREP_Location_SetData )(const struct SCOREP_Location locationData, size_t plugin_id, void data)

void(*	SCOREP_Metric_WriteAsynchronousMetrics )(struct SCOREP_Location *location, SCOREP_Substrates_WriteMetricsCb cb)
	Tell Score-P to write the current asynchronous metrics to cb. More...

void(*	SCOREP_Metric_WriteStrictlySynchronousMetrics )(struct SCOREP_Location *location, uint64_t timestamp, SCOREP_Substrates_WriteMetricsCb cb)
	Tell Score-P to write the current strictly synchronous metrics to cb. More...

void(*	SCOREP_Metric_WriteSynchronousMetrics )(struct SCOREP_Location *location, uint64_t timestamp, SCOREP_Substrates_WriteMetricsCb cb)
	Tell Score-P to write the current synchronous metrics to cb. More...

SCOREP_MetricMode(*	SCOREP_MetricHandle_GetMode )(SCOREP_MetricHandle handle)

const char (	SCOREP_MetricHandle_GetName )(SCOREP_MetricHandle handle)

SCOREP_MetricProfilingType(*	SCOREP_MetricHandle_GetProfilingType )(SCOREP_MetricHandle handle)

SCOREP_MetricSourceType(*	SCOREP_MetricHandle_GetSourceType )(SCOREP_MetricHandle handle)

SCOREP_MetricValueType(*	SCOREP_MetricHandle_GetValueType )(SCOREP_MetricHandle handle)

SCOREP_ParadigmClass(*	SCOREP_ParadigmHandle_GetClass )(SCOREP_ParadigmHandle handle)

const char (	SCOREP_ParadigmHandle_GetName )(SCOREP_ParadigmHandle handle)

SCOREP_ParadigmType(*	SCOREP_ParadigmHandle_GetType )(SCOREP_ParadigmHandle handle)

const char (	SCOREP_ParameterHandle_GetName )(SCOREP_ParameterHandle handle)

SCOREP_ParameterType(*	SCOREP_ParameterHandle_GetType )(SCOREP_ParameterHandle handle)

SCOREP_LineNo(*	SCOREP_RegionHandle_GetBeginLine )(SCOREP_RegionHandle handle)

const char (	SCOREP_RegionHandle_GetCanonicalName )(SCOREP_RegionHandle handle)

SCOREP_LineNo(*	SCOREP_RegionHandle_GetEndLine )(SCOREP_RegionHandle handle)

const char (	SCOREP_RegionHandle_GetFileName )(SCOREP_RegionHandle handle)

uint32_t(*	SCOREP_RegionHandle_GetId )(SCOREP_RegionHandle handle)

const char (	SCOREP_RegionHandle_GetName )(SCOREP_RegionHandle handle)

SCOREP_ParadigmType(*	SCOREP_RegionHandle_GetParadigmType )(SCOREP_RegionHandle handle)

SCOREP_RegionType(*	SCOREP_RegionHandle_GetType )(SCOREP_RegionHandle handle)

const SCOREP_MetricHandle (	SCOREP_SamplingSetHandle_GetMetricHandles )(SCOREP_SamplingSetHandle handle)

SCOREP_MetricOccurrence(*	SCOREP_SamplingSetHandle_GetMetricOccurrence )(SCOREP_SamplingSetHandle handle)

uint8_t(*	SCOREP_SamplingSetHandle_GetNumberOfMetrics )(SCOREP_SamplingSetHandle handle)

SCOREP_SamplingSetClass(*	SCOREP_SamplingSetHandle_GetSamplingSetClass )(SCOREP_SamplingSetHandle handle)

SCOREP_MetricScope(*	SCOREP_SamplingSetHandle_GetScope )(SCOREP_SamplingSetHandle handle)

bool(*	SCOREP_SamplingSetHandle_IsScoped )(SCOREP_SamplingSetHandle handle)

const char (	SCOREP_SourceFileHandle_GetName )(SCOREP_SourceFileHandle handle)

const char (	SCOREP_StringHandle_Get )(SCOREP_StringHandle handle)

Detailed Description

Callbacks that are passed to Substrate plugins via the set_callbacks(...) call. These callbacks can be used by the plugins to access Score-P internal data and functionality.

Developer notice: New functions should be appended at the end of this struct. When extending this list, increase SCOREP_SUBSTRATE_PLUGIN_VERSION

Examples:: print_regions.c.

Field Documentation

SCOREP_CallingContextHandle( * SCOREP_SubstratePluginCallbacks::SCOREP_CallingContextHandle_GetParent) (SCOREP_CallingContextHandle handle)

Returns the parent of a calling context node.

Parameters

handle handle of the calling context node

Returns: parent handle

SCOREP_RegionHandle( * SCOREP_SubstratePluginCallbacks::SCOREP_CallingContextHandle_GetRegion) (SCOREP_CallingContextHandle handle)

Returns the region of a calling context node. (see SCOREP_PublicTypes.h)

Parameters

handle handle of the calling context node

Returns: handle to the region that holds the node

const char*( * SCOREP_SubstratePluginCallbacks::SCOREP_GetExperimentDirName) (void)

Returns the Score-P experiment directory. This should be used to write debug/performance data and is available at and after init_mpp is called. Data should be placed under SCOREP_GetExperimentDirName()/(plugin-name)/. Per location data should be placed under SCOREP_GetExperimentDirName()/(plugin-name)/(prefix)(SCOREP_Location_GetGlobalId(location))(suffix). If you want to use the experiment directory, you have to set the SCOREP_SUBSTRATES_REQUIREMENT_EXPERIMENT_DIRECTORY flag in the requirements, see SCOREP_SubstratePluginInfo.get_requirement The name is temporary and the directory might be renamed in the finalization stage.

int( * SCOREP_SubstratePluginCallbacks::SCOREP_Ipc_Allgather) (const void *sendbuf, void *recvbuf, int count, SCOREP_Ipc_Datatype datatype)

Gathers data from every process with an equal amount of sent and received data from each process and distributes it to all processes. Can be called after Plugin receives init_mpp() call.

Parameters

sendbuf	pointer to the buffer of the data that should be sent
recvbuf	pointer to buffer there the received data should be stored data is stored in rank order size of the buffer should be big enough for the data of all processes
count	number of elements in buffer
datatype	type of data

Returns: return zero on success and something else if an error occurred

int( * SCOREP_SubstratePluginCallbacks::SCOREP_Ipc_Allreduce) (const void *sendbuf, void *recvbuf, int count, SCOREP_Ipc_Datatype datatype, SCOREP_Ipc_Operation operation)

Perform a reduce operation (such as sum, max, logical AND, etc.) with the combined data from every process and distributes the result to all processes. Can be called after Plugin receives init_mpp() call.

Parameters

sendbuf	pointer to the buffer of the data that should be sent
recvbuf	pointer to buffer there the evaluated data should be stored
count	number of elements in buffer
datatype	type of data
operation	operation that should be performed

Returns: return zero on success and something else if an error occurred

int( * SCOREP_SubstratePluginCallbacks::SCOREP_Ipc_Barrier) (void)

Wait until every process that is part of the MPP paradigm entered the barrier, otherwise return. Can be called after Plugin receives init_mpp() call.

Returns: return zero on success and something else if an error occurred

int( * SCOREP_SubstratePluginCallbacks::SCOREP_Ipc_Bcast) (void *buf, int count, SCOREP_Ipc_Datatype datatype, int root)

Send data to every process within the MPP paradigm (if MPP paradigm is used), including self. Can be called after Plugin receives init_mpp() call.

Parameters

buf	pointer to the buffer of the data that should be sent
count	number of elements in buffer
datatype	type of data
root	rank of the source process

Returns: return zero on success and something else if an error occurred

int( * SCOREP_SubstratePluginCallbacks::SCOREP_Ipc_Gather) (const void *sendbuf, void *recvbuf, int count, SCOREP_Ipc_Datatype datatype, int root)

Gathers data from every process within the MPP paradigm (if MPP paradigm is used), root included, with an equal amount of sent for each process.

Can be called after Plugin receives init_mpp() call.

Parameters

sendbuf	pointer to the buffer of the data that should be sent
recvbuf	pointer to buffer there the received data should be stored data is stored in rank order size of the buffer should be big enough for the data of all processes (SCOREP_Ipc_GetSize()*sizeof(type(datatype)))
count	number of elements in buffer
datatype	type of data
root	rank of the process, that should receive all the data

Returns: return zero on success and something else if an error occurred

int( * SCOREP_SubstratePluginCallbacks::SCOREP_Ipc_Gatherv) (const void *sendbuf, int sendcount, void *recvbuf, const int *recvcnts, SCOREP_Ipc_Datatype datatype, int root)

Gathers data from every process, root included, with varying amount of sent data from each process. Can be called after Plugin receives init_mpp() call.

Parameters

sendbuf	pointer to the buffer of the data that should be sent
sendcount	number of elements in sent buffer
recvbuf	pointer to buffer there the received data should be stored data is stored in rank order size of the buffer should be big enough for the data of all processes
recvcnts	array with the number of elements that should be received from each process length should be the number of process
datatype	type of data
root	rank of the process, that should receive all the data

Returns: return zero on success and something else if an error occurred

int( * SCOREP_SubstratePluginCallbacks::SCOREP_Ipc_GetRank) (void)

Get the rank of the process. Can be called after Plugin receives init_mpp() call.

Returns: If MPP paradigm is used get an identifier within the MPP paradigm (e.g., an MPI rank). If no MPP paradigm is used return 0

int( * SCOREP_SubstratePluginCallbacks::SCOREP_Ipc_GetSize) (void)

Get the number of processes in this parallel program. Can be called after Plugin receives init_mpp() call.

Returns: If MPP paradigm is used we get the total number of processes that participate in the MPP paradigm, if no MPP paradigm is used return 1

int( * SCOREP_SubstratePluginCallbacks::SCOREP_Ipc_Recv) (void *buf, int count, SCOREP_Ipc_Datatype datatype, int source)

Receive data from a specific process (blocking) Can be called after Plugin receives init_mpp() call. Should not be called if no MPP paradigm is used.

Parameters

buf	pointer to buffer there the received data should be stored
count	number of elements in buffer
datatype	type of data
source	rank of the source process (must be smaller than SCOREP_Ipc_GetSize() and different from SCOREP_Ipc_GetRank() )

Returns: return zero on success and something else if an error occurred

int( * SCOREP_SubstratePluginCallbacks::SCOREP_Ipc_Reduce) (const void *sendbuf, void *recvbuf, int count, SCOREP_Ipc_Datatype datatype, SCOREP_Ipc_Operation operation, int root)

Perform a reduce operation (such as sum, max, logical AND, etc.) with the combined data from every process. Can be called after Plugin receives init_mpp() call.

Parameters

sendbuf	pointer to the buffer of the data that should be sent
recvbuf	pointer to buffer there the evaluated data should be stored
count	number of elements in buffer
datatype	type of data
operation	operation that should be performed
root	rank of the process, that should receive the evaluated data

Returns: return zero on success and something else if an error occurred

int( * SCOREP_SubstratePluginCallbacks::SCOREP_Ipc_Scatter) (const void *sendbuf, void *recvbuf, int count, SCOREP_Ipc_Datatype datatype, int root)

Send data to each process, root included with an equal amount of received data for each process. Can be called after Plugin receives init_mpp() call.

Parameters

sendbuf	pointer to the buffer of the data that should be sent
recvbuf	pointer to buffer there the received data should be stored
count	number of elements in buffer
datatype	type of data
root	rank of the source process

Returns: return zero on success and something else if an error occurred

int( * SCOREP_SubstratePluginCallbacks::SCOREP_Ipc_Scatterv) (const void *sendbuf, const int *sendcounts, void *recvbuf, int recvcount, SCOREP_Ipc_Datatype datatype, int root)

Send data in parts to each process, root included with a varying amount of received data for each process. Can be called after Plugin receives init_mpp() call.

Parameters

sendbuf	pointer to the buffer of the data that should be sent
sendcounts	array with the number of elements that should be sent to each process length should be the number of process
recvbuf	pointer to buffer there the received data should be stored
recvcount	number of elements in received buffer
datatype	type of data
root	rank of the source process

Returns: return zero on success and something else if an error occurred

int( * SCOREP_SubstratePluginCallbacks::SCOREP_Ipc_Send) (const void *buf, int count, SCOREP_Ipc_Datatype datatype, int dest)

Send data do a specific process (blocking) within the MPP paradigm. Can be called after Plugin receives init_mpp() call. Should not be called if no MPP paradigm is used.

Parameters

bufpointer	to the buffer of the data that should be sent
count	number of elements in buffer
datatype	type of data
dest	rank of the receiver process (must be smaller than SCOREP_Ipc_GetSize() and different from SCOREP_Ipc_GetRank() )

Returns: return zero on success and something else if an error occurred

void*( * SCOREP_SubstratePluginCallbacks::SCOREP_Location_GetData) (const struct SCOREP_Location *locationData, size_t plugin_id)

Get location private data for a specific location (see SCOREP_Location_SetData) It is save to use it after the location is created (SCOREP_SubstratePluginInfo.create_location) and before the location is deleted (SCOREP_SubstratePluginInfo.delete_location)

Parameters

location	handle of the location
plugin_id	the id assigned by assign_id

Returns: the data for this location and this plugin

Examples:: print_regions.c.

uint64_t( * SCOREP_SubstratePluginCallbacks::SCOREP_Location_GetGlobalId) (const struct SCOREP_Location *locationData)

Get a unique global id of a location This is only to be used after init_mpp() is called.

Parameters

location location given from an event

Returns: global location id

uint32_t( * SCOREP_SubstratePluginCallbacks::SCOREP_Location_GetId) (const struct SCOREP_Location *locationData)

Returns the LOCAL id of the location. (see also SCOREP_Location_GetGlobalId)

Parameters

location location given from an event, or a location function from SCOREP_SubstratePluginInfo

Returns: ID that is unique within the process

const char*( * SCOREP_SubstratePluginCallbacks::SCOREP_Location_GetName) (const struct SCOREP_Location *locationData)

Get the name of a location

Parameters

location handle

Returns: location name

Examples:: print_regions.c.

SCOREP_LocationType( * SCOREP_SubstratePluginCallbacks::SCOREP_Location_GetType) (const struct SCOREP_Location *locationData)

Returns the type of the location.

Returns

void( * SCOREP_SubstratePluginCallbacks::SCOREP_Location_SetData) (const struct SCOREP_Location *locationData, size_t plugin_id, void *data)

Set location private data for a specific location (see SCOREP_Location_GetData) It is save to use it after the location is created (SCOREP_SubstratePluginInfo.create_location) and before the location is deleted (SCOREP_SubstratePluginInfo.delete_location)

Parameters

location	handle of the location
plugin_id	the id assigned by assign_id
the	data for this location and this plugin

Examples:: print_regions.c.

void( * SCOREP_SubstratePluginCallbacks::SCOREP_Metric_WriteAsynchronousMetrics) (struct SCOREP_Location *location, SCOREP_Substrates_WriteMetricsCb cb)

Tell Score-P to write the current asynchronous metrics to cb.

This function shall only be called while processing enters, exits, and samples. The callback might be called multiple times if multiple asynchronous sampling sets are present.

Parameters

location	the location of the runtime event, this is reported back via cb
cb	a callback that processes the asynchronous metrics.

void( * SCOREP_SubstratePluginCallbacks::SCOREP_Metric_WriteStrictlySynchronousMetrics) (struct SCOREP_Location *location, uint64_t timestamp, SCOREP_Substrates_WriteMetricsCb cb)

Tell Score-P to write the current strictly synchronous metrics to cb.

This function shall only be called while processing enters, exits, and samples.

Parameters

location	the location of the runtime event, this is reported back via cb
timestamp	the timestamp of the runtime event, this is reported back via cb
cb	a callback that processes the strictly synchronous metrics.

void( * SCOREP_SubstratePluginCallbacks::SCOREP_Metric_WriteSynchronousMetrics) (struct SCOREP_Location *location, uint64_t timestamp, SCOREP_Substrates_WriteMetricsCb cb)

Tell Score-P to write the current synchronous metrics to cb.

This function shall only be called while processing enters, exits, and samples. The callback might be called multiple times if multiple synchronous sampling sets are present.

Parameters

location	the location of the runtime event, this is reported back via cb
timestamp	the timestamp of the runtime event, this is reported back via cb
cb	a callback that processes the synchronous metrics.

SCOREP_MetricMode( * SCOREP_SubstratePluginCallbacks::SCOREP_MetricHandle_GetMode) (SCOREP_MetricHandle handle)

Returns the mode of a metric.

Parameters