object_id

The object_id policy is used to improve the handling of id and event names.

Note:

While the object_id policy is really useful in some cases, it can't cover all cases. Thus you may have to resort to manual ID handling.

Usage

This policy requires a special treatment compared to other policies. Additionally to define the below listed member methods, you have to do two steps. First you have to create a class representing a handle to a channel. And second you have to adapt the implementation of the method get_metric_properties.

Preparation

The object_id policy requires the type of the handle as a template parameter. But, every policy is already a class template. Therefore, you need to do some sort of partial instantiation. This is done with a using declaration.

class my_handle_type {
    // ...
};

template <typename T, typename Policies>
using my_object_id_policy = scorep::plugin::policy::object_id<my_handle_type, T, Policies>;

The new class template my_object_id_policy can now be used just like a normal policy.

Note:

The handle type shall not be convertible to std::string and int32_t

Adapting get_metric_properties method

During the call to get_metric_properties, you have to make an handle for each metric you like to use in addition to return them as a metric_property. To do this, you call the method make_handle with the name followed by the constructor arguments for your handle class.

Methods

template <typename ...Args> Handle& make_handle(const std::string& name, Args&&... args)

Creates a new handle object using the provided args and registers it under the given name.

Arguments:

• name - the name for the channel as std::string
• args - the list of constructor arguments to create a new Handle instance

Returns:

• Handle - a reference to the newly created handle

Note:

The name has to be unique within one process.

Required methods

void add_metric(Handle& h)

Signifies that the metric represented by the given handle, should be recorded on the executing thread.

Arguments:

• h - the handle defined

template <class Cursor> void get_all_values(Handle& h, Cursor& c)

This function gets called in async plugins after the measurement was stopped, or after delta_t ticks.

Arguments:

• h - the handle defined
• c - the Cursor used to write data

template <class Proxy> void get_optional_value(Handle& h, Proxy& p)

This function gets called for sync plugins at every enter and leave event.

Arguments:

• h - the handle defined
• p - the Proxy used to write data

Returns:

• bool - signifies, whether a value was written or not

template <class Proxy> void get_current_value(Handle& h, Proxy& p)

This function gets called for sync_strict plugins at every enter and leave event.

Arguments:

• h - the handle defined
• p - the Proxy used to write data

Provided methods

Besides other policies tell to implement the following functions, you must not implement them when using this policy. They are provided for you by this policy.

• int32_t add_metric(const std::string&)
• void get_all_values(std::int32_t id, Cursor& c)
• void get_current_value(std::int32_t id, Proxy& p)
• bool get_optional_value(std::int32_t id, Proxy& p)

See also

• base
• async
• sync
• sync_strict