hpx/performance_counters/manage_counter_type.hpp#

See Public API for a list of names and headers that are part of the public HPX API.

namespace hpx
namespace performance_counters

Functions

counter_status install_counter_type(std::string const &name, hpx::function<std::int64_t(bool)> const &counter_value, std::string const &helptext = "", std::string const &uom = "", counter_type type = counter_type::raw, error_code &ec = throws)#

Install a new generic performance counter type in a way, which will uninstall it automatically during shutdown.

The function install_counter_type will register a new generic counter type based on the provided function. The counter type will be automatically unregistered during system shutdown. Any consumer querying any instance of this this counter type will cause the provided function to be called and the returned value to be exposed as the counter value.

The counter type is registered such that there can be one counter instance per locality. The expected naming scheme for the counter instances is: '/objectname{locality#<*>/total}/countername' where ‘<*>’ is a zero based integer identifying the locality the counter is created on.

Note

As long as ec is not pre-initialized to hpx::throws this function doesn’t throw but returns the result code using the parameter ec. Otherwise it throws an instance of hpx::exception.

Note

The counter type registry is a locality based service. You will have to register each counter type on every locality where a corresponding performance counter will be created.

Parameters
  • name – [in] The global virtual name of the counter type. This name is expected to have the format /objectname/countername.

  • counter_value – [in] The function to call whenever the counter value is requested by a consumer.

  • helptext – [in, optional] A longer descriptive text shown to the user to explain the nature of the counters created from this type.

  • uom – [in] The unit of measure for the new performance counter type.

  • type – [in] Type for the new performance counter type.

  • ec – [in,out] this represents the error status on exit, if this is pre-initialized to hpx::throws the function will throw on error instead.

Returns

If successful, this function returns valid_data, otherwise it will either throw an exception or return an error_code from the enum counter_status (also, see note related to parameter ec).

counter_status install_counter_type(std::string const &name, hpx::function<std::vector<std::int64_t>(bool)> const &counter_value, std::string const &helptext = "", std::string const &uom = "", error_code &ec = throws)#

Install a new generic performance counter type returning an array of values in a way, that will uninstall it automatically during shutdown.

The function install_counter_type will register a new generic counter type that returns an array of values based on the provided function. The counter type will be automatically unregistered during system shutdown. Any consumer querying any instance of this this counter type will cause the provided function to be called and the returned array value to be exposed as the counter value.

The counter type is registered such that there can be one counter instance per locality. The expected naming scheme for the counter instances is: '/objectname{locality#<*>/total}/countername' where ‘<*>’ is a zero based integer identifying the locality the counter is created on.

Note

As long as ec is not pre-initialized to hpx::throws this function doesn’t throw but returns the result code using the parameter ec. Otherwise it throws an instance of hpx::exception.

Note

The counter type registry is a locality based service. You will have to register each counter type on every locality where a corresponding performance counter will be created.

Parameters
  • name – [in] The global virtual name of the counter type. This name is expected to have the format /objectname/countername.

  • counter_value – [in] The function to call whenever the counter value (array of values) is requested by a consumer.

  • helptext – [in, optional] A longer descriptive text shown to the user to explain the nature of the counters created from this type.

  • uom – [in] The unit of measure for the new performance counter type.

  • ec – [in,out] this represents the error status on exit, if this is pre-initialized to hpx::throws the function will throw on error instead.

Returns

If successful, this function returns valid_data, otherwise it will either throw an exception or return an error_code from the enum counter_status (also, see note related to parameter ec).

void install_counter_type(std::string const &name, counter_type type, error_code &ec = throws)#

Install a new performance counter type in a way, which will uninstall it automatically during shutdown.

The function install_counter_type will register a new counter type based on the provided counter_type_info. The counter type will be automatically unregistered during system shutdown.

Note

The counter type registry is a locality based service. You will have to register each counter type on every locality where a corresponding performance counter will be created.

Note

As long as ec is not pre-initialized to hpx::throws this function doesn’t throw but returns the result code using the parameter ec. Otherwise it throws an instance of hpx::exception.

Parameters
  • name – [in] The global virtual name of the counter type. This name is expected to have the format /objectname/countername.

  • type – [in] The type of the counters of this counter_type.

  • ec – [in,out] this represents the error status on exit, if this is pre-initialized to hpx::throws the function will throw on error instead.

Returns

If successful, this function returns valid_data, otherwise it will either throw an exception or return an error_code from the enum counter_status (also, see note related to parameter ec).

counter_status install_counter_type(std::string const &name, counter_type type, std::string const &helptext, std::string const &uom = "", std::uint32_t version = HPX_PERFORMANCE_COUNTER_V1, error_code &ec = throws)#

Install a new performance counter type in a way, which will uninstall it automatically during shutdown.

The function install_counter_type will register a new counter type based on the provided counter_type_info. The counter type will be automatically unregistered during system shutdown.

Note

The counter type registry is a locality based service. You will have to register each counter type on every locality where a corresponding performance counter will be created.

Note

As long as ec is not pre-initialized to hpx::throws this function doesn’t throw but returns the result code using the parameter ec. Otherwise it throws an instance of hpx::exception.

Parameters
  • name – [in] The global virtual name of the counter type. This name is expected to have the format /objectname/countername.

  • type – [in] The type of the counters of this counter_type.

  • helptext – [in] A longer descriptive text shown to the user to explain the nature of the counters created from this type.

  • uom – [in] The unit of measure for the new performance counter type.

  • version – [in] The version of the counter type. This is currently expected to be set to HPX_PERFORMANCE_COUNTER_V1.

  • ec – [in,out] this represents the error status on exit, if this is pre-initialized to hpx::throws the function will throw on error instead.

Returns

If successful, this function returns valid_data, otherwise it will either throw an exception or return an error_code from the enum counter_status (also, see note related to parameter ec).

counter_status install_counter_type(std::string const &name, counter_type type, std::string const &helptext, create_counter_func const &create_counter, discover_counters_func const &discover_counters, std::uint32_t version = HPX_PERFORMANCE_COUNTER_V1, std::string const &uom = "", error_code &ec = throws)#

Install a new generic performance counter type in a way, which will uninstall it automatically during shutdown.

The function install_counter_type will register a new generic counter type based on the provided counter_type_info. The counter type will be automatically unregistered during system shutdown.

Note

As long as ec is not pre-initialized to hpx::throws this function doesn’t throw but returns the result code using the parameter ec. Otherwise it throws an instance of hpx::exception.

Note

The counter type registry is a locality based service. You will have to register each counter type on every locality where a corresponding performance counter will be created.

Parameters
  • name – [in] The global virtual name of the counter type. This name is expected to have the format /objectname/countername.

  • type – [in] The type of the counters of this counter_type.

  • helptext – [in] A longer descriptive text shown to the user to explain the nature of the counters created from this type.

  • version – [in] The version of the counter type. This is currently expected to be set to HPX_PERFORMANCE_COUNTER_V1.

  • create_counter – [in] The function which will be called to create a new instance of this counter type.

  • discover_counters – [in] The function will be called to discover counter instances which can be created.

  • uom – [in] The unit of measure of the counter type (default: “”)

  • ec – [in,out] this represents the error status on exit, if this is pre-initialized to hpx::throws the function will throw on error instead.

Returns

If successful, this function returns valid_data, otherwise it will either throw an exception or return an error_code from the enum counter_status (also, see note related to parameter ec).