 |
9.0-rc1 (revision bed9cc26b)
|
#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) |
Information on that defines the plugin. All values that are not explicitly defined should be set to 0
| 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.
| metric_name | Name of an individual metric |
| 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.
| 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.
| id | Metric id (see add_counter). | |
| [out] | time_value_list | Pointer to list with return values (pairs of timestamp and value). |
*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.
| id | Metric id (see add_counter). |
| 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/....
| token | String that describes one or multiple metrics. |
| 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.
| id | Metric id (see add_counter). | |
| [out] | value | Current value of requested metric. For metrics of value_type other than UINT64, the data should be reinterpreted to a UINT64 using a union. |
| 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.
| uint32_t SCOREP_Metric_Plugin_Info::plugin_version |
Should be set to SCOREP_METRIC_PLUGIN_VERSION (needed for back- and forward compatibility)
| 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.
| 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.
| clock_time | Function 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.
| 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:
Once at the end with SCOREP_METRIC_SYNCHRONIZATION_MODE_END For asynchronous metrics, starting and stopping a measurement should be done in this function, not in add_counter.
| is_responsible | Flag to mark responsibility as per run_per |
| sync_mode | Mode of synchronization point, e.g. SCOREP_METRIC_SYNCHRONIZATION_MODE_BEGIN, SCOREP_METRIC_SYNCHRONIZATION_MODE_BEGIN_MPP, SCOREP_METRIC_SYNCHRONIZATION_MODE_END |