Plugin Base

The class template scorep::plugin::base is the parent class for all plugins written with the C++ wrapper.

The first template argument is the class of the written plugin itself. Every following argument is a policy.

Policies

The policies influence the type and behaviour of the plugin. See Policies.

Usage

The base class needs several template arguments. The first argument is your plugin class itself. The following template arguments are the used policies.

class my_first_plugin
  : public scorep::plugin::base<my_first_plugin, Policies...>
{};

You then proceed with defining all required methods.

Defining methods

The base class and most policies requires that the plugin class defines a specific set of methods with a certain signature. For details, see below and refer to the appropriate policy.

Note:

• All required methods will be checked with the help of several static_assert. This means, you get errors at compile time, if a method is missing.

Required methods

std::vector<scorep::plugin::metric_property> get_metric_properties(const std::string& metric_parse)

This method is used to expand possible metric. The method should return a list of metric properties. The idea here is, that metric_parse can contain wildcards or certain metrics imply the presence of other metrics. In such cases, you need to return more than one metric_property. You may find the class matcher helpful, when implementing this method.

Arguments:

• metric_parse - a string representing a possible set of metrics

Returns:

• vector<metric_property> - a list of all identified metrics

int32_t add_metric(const std::string& metric_name)

Signifies, that the metric represented by the given name should be recorded on the executing thread. The return value is an unique identifier for the given metric.

Arguments:

• metric_name - the name of the metric

Returns:

• int32 - the selected identifier

Lifetime handling

There must not be more than one instance of a plugin class.

It is guaranteed, that the wrapper will not create another instance, aside from the one accessible with the scorep::plugin::base::instance() method.

It is also guaranteed, that the wrapper will take care of the lifetime of the plugin instance, such that constructor and destructor of the sole instance are called at appropriate times.

Error handling

It is guaranteed, that exceptions inherited from std::exception won't leave the C++ wrapper.

If you encounter any errors in the your implemented methods, you're encouraged to throw exceptions. The wrapper will catch any exception - which inherit from std::exception - print them with the logging and report the error to Score-P, if applicable.

Note:

• Though, it's guaranteed, that an exception will never leave the C++ wrapper, not all plugin handler functions allow to propagate errors to Score-P. Thus, the instrumented application and therefore Score-P will still continue to make calls into the plugin. The plugin should always keep a defined state, in which it is okay, to handle further calls.

See also

• matcher