7.0 (revision 7784de1c)
Data Fields
SCOREP_Metric_Plugin_Info Struct Reference

#include <SCOREP_MetricPlugins.h>

Data Fields

int32_t(* add_counter )(char *metric_name)
 
uint64_t delta_t
 
void(* finalize )(void)
 
uint64_t(* get_all_values )(int32_t id, SCOREP_MetricTimeValuePair **time_value_list)
 
uint64_t(* get_current_value )(int32_t id)
 
SCOREP_Metric_Plugin_MetricProperties *(* get_event_info )(char *token)
 
bool(* get_optional_value )(int32_t id, uint64_t *value)
 
int32_t(* initialize )(void)
 
uint32_t plugin_version
 
uint64_t reserved [92]
 
SCOREP_MetricPer run_per
 
void(* set_clock_function )(uint64_t(*clock_time)(void))
 
SCOREP_MetricSynchronicity sync
 
void(* synchronize )(bool is_responsible, SCOREP_MetricSynchronizationMode sync_mode)
 

Detailed Description

Information on that defines the plugin. All values that are not explicitly defined should be set to 0

Examples:
hello_world.c.

Field Documentation

int32_t( * SCOREP_Metric_Plugin_Info::add_counter) (char *metric_name)

Depending on run_per, this function is called per thread, per process, per host, or only on a single thread. Further it is called for each metric as returned by the calls to get_event_info.

The function sets up the measurement for the requested metric and returns a non-negative unique ID which is from now on used to refer to this metric.

Parameters
metric_nameName of an individual metric
Returns
non-negative ID of requested metric or negative value in cased of failure
Examples:
hello_world.c.
uint64_t SCOREP_Metric_Plugin_Info::delta_t

Set a specific interval for reading metric values. Score-P will request metric values of a plugin, at the earliest, after delta_t ticks after it was last read. NOTE: This is only a lower limit for the time between two reads

void( * SCOREP_Metric_Plugin_Info::finalize) (void)

This functions is called once per process to clean up all resources used by the metric plugin.

Examples:
hello_world.c.
uint64_t( * SCOREP_Metric_Plugin_Info::get_all_values) (int32_t id, SCOREP_MetricTimeValuePair **time_value_list)

This function provides the recorded value of the selected metric. It must be implemented by asynchronous metric plugins. The timestamps in the returned list should correspond to the clock provided by set_clock_function. Further, all values (timestamps) should lie within within the following interval: synchronize(SCOREP_METRIC_SYNCHRONIZATION_MODE_BEGIN|SCOREP_METRIC_SYNCHRONIZATION_MODE_BEGIN_MPP), synchronize(SCOREP_METRIC_SYNCHRONIZATION_MODE_END). Score-P takes ownership of the *time_value_list memory. Make sure the memory remains valid and is never modified by the plugin. Score-P will release the memory using free. The pointer must be created directly by malloc/calloc etc. directly. Do not use a memory pool / pointer with offset into a larger memory etc.

Parameters
idMetric id (see add_counter).
[out]time_value_listPointer to list with return values (pairs of timestamp and value).
See also
SCOREP_MetricSynchronizationMode
Returns
Number of elements within *time_value_list
uint64_t( * SCOREP_Metric_Plugin_Info::get_current_value) (int32_t id)

This function shall provide the current value of a metric. It must be implemented by strictly synchronous metric plugins. It is called according to the run_per specification.

Parameters
idMetric id (see add_counter).
Returns
Current value of requested metric. For metrics of value_type other than UINT64, the data should be reinterpreted to a UINT64 using a union.
SCOREP_Metric_Plugin_MetricProperties*( * SCOREP_Metric_Plugin_Info::get_event_info) (char *token)

A user specifies a SCOREP_METRIC_EXAMPLE_PLUGIN=token1,token2,... This function is called once per process and token. Each token can result in any number of metrics (wildcards). The function shall provide the properties of the metrics for this token.

The total list of metrics returned by the calls for all tokens comprises the metrics that will be recorded by the plugin.

Note: The properties-array must contain an additional end entry with name = NULL.

Note: The properties-array memory and all indirect pointers are managed by Score-P now. Make sure the memory remains valid and unmodified. All memory may be released with free by Score-P. Make sure that all provided pointers are created by malloc/strdup/....

Parameters
tokenString that describes one or multiple metrics.
Returns
properties Meta data about the metrics available for this token.
Examples:
hello_world.c.
bool( * SCOREP_Metric_Plugin_Info::get_optional_value) (int32_t id, uint64_t *value)

This function provides the current value of a metric if available. It must be implemented by synchronous metric plugins. It is called according to the run_per specification.

Parameters
idMetric id (see add_counter).
[out]valueCurrent value of requested metric. For metrics of value_type other than UINT64, the data should be reinterpreted to a UINT64 using a union.
Returns
True if value of requested metric was written, otherwise false.
Examples:
hello_world.c.
int32_t( * SCOREP_Metric_Plugin_Info::initialize) (void)

This function is called once per process. It should check that all requirements are met (e.g., are special libraries needed and available, has the user appropriate rights to access implemented metrics). If all requirements are met, data structures used by the plugin can be initialized within this function.

Returns
0 if successful, error code if failure
Examples:
hello_world.c.
uint32_t SCOREP_Metric_Plugin_Info::plugin_version

Should be set to SCOREP_METRIC_PLUGIN_VERSION (needed for back- and forward compatibility)

Examples:
hello_world.c.
uint64_t SCOREP_Metric_Plugin_Info::reserved[92]

Reserved space for future features, should be zeroed

SCOREP_MetricPer SCOREP_Metric_Plugin_Info::run_per

Defines how many threads should record the metrics of a plugin. For the available options see SCOREP_MetricPer.

Examples:
hello_world.c.
void( * SCOREP_Metric_Plugin_Info::set_clock_function) (uint64_t(*clock_time)(void))

When this callback is implemented, Score-P calls it once to provide a clock function that allows the plugin to read the current time in Score-P ticks. This should be used by asynchronous metric plugins.

Note: This function is called before initialize.

Parameters
clock_timeFunction pointer to Score-P's clock function.
SCOREP_MetricSynchronicity SCOREP_Metric_Plugin_Info::sync

Defines how metrics are measured over time and how they are collected by Score-P. This setting influences when and which callback functions are called by Score-P. For the available options see SCOREP_MetricSynchronicity.

Examples:
hello_world.c.
void( * SCOREP_Metric_Plugin_Info::synchronize) (bool is_responsible, SCOREP_MetricSynchronizationMode sync_mode)

This callback is used for stating and stopping the measurement of asynchronous metrics and can also be used for time synchronization purposes. This function is called for all threads in the application, but the threads that handle the metric plugin according to run_per will be marked as is_responsible. The function will be called approximately at the same time for all threads:


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