C++ Type-Traits¶

Type-traits are used to specialize behavior at compile-time. In general, timemory tries to avoid specialization in the core library (when possible) so that users are not restricted for specializing downstream. Please note, specializations may be ignored or cause compilation errors if extern templates are used. Ignoring specializations commonly happen in output routines like tim::operation::print<T> where the value of the specialization is used at runtime and the body of the output routine is not actually instantiated in the user code.

Component Implementation¶

template<typename T> struct is_available : public TIMEMORY_DEFAULT_AVAILABLE¶

trait that signifies that an implementation for the component is available. When this is set to false, the variadic component bundlers like component_tuple will silently filter out this type from the template parameters, e.g.

TIMEMORY_DECLARE_COMPONENT(foo)
TIMEMORY_DECLARE_COMPONENT(bar)

namespace tim {
namespace trait {
template <>
struct is_available<component::bar> : false_type {};
}
}

will cause these two template instantiations to become identical:

using A_t = component_tuple<foo>;
using B_t = component_tuple<foo, bar>;

and a definition of ‘bar’ will not be required for compilation.

Subclassed by tim::trait::uses_storage< T >

template<int OpT, typename T> struct python_args¶

trait that designates the type supports these arguments from python. Specializations MUST be structured as either one tim::type_list<...> or a tim::type_list<...> of tim::type_list<...>. The first argument is a TIMEMORY_OPERATION enumerated type and for each inner tim::type_list, a python member function for the stand-alone component will be generated with those arguments. E.g. to create a custom store member function accepting integer:

foo = timemory.component.CaliperLoopMarker("example")
foo.start()
for i in range(10):
    foo.store(i)    # store member function accepting integer
    # ...
foo.stop()

The type-trait specification would look like this:

template <>
struct python_args<TIMEMORY_STORE, component::caliper_loop_marker>
{
    using type = type_list<size_t>;
};

template<typename T> struct default_runtime_enabled : public true_type¶: trait whose compile-time constant field value designates the default runtime value of tim::trait::runtime_enabled. Standard setting is true.

template<typename T> struct tim::trait::runtime_enabled¶

trait that signifies that an implementation is enabled at runtime. The value returned from get() is for the specific setting for the type, the global settings (type: void) and the specific settings for it’s APIs

Public Types

using api_type_list = mpl::get_true_types_t<concepts::is_runtime_configurable, component_apis_t<T>>¶: type-list of APIs that are runtime configurable

Public Static Functions

template<typename U = T> static inline bool get(enable_if_t<is_available::value && get_value(), int> = 0)¶: GET specialization if component is available.

template<typename U = T> static inline bool set(bool val, enable_if_t<is_available::value && get_value(), int> = 0)¶: SET specialization if component is available.

template<typename U = T> static inline bool get(enable_if_t<!is_available::value || !get_value(), long> = 0)¶: GET specialization if component is NOT available.

template<typename U = T> static inline bool set(bool, enable_if_t<!is_available::value || !get_value(), long> = 0)¶: SET specialization if component is NOT available.

template<typename T, typename Tag> struct api_components¶: trait that designates components in an API (tim::api)

Base Class Modifications¶

template<typename T> struct base_has_accum : public true_type¶: trait that signifies that a component has an accumulation value. In general, most components implement ‘value’ and ‘accum’ data members of ‘value_type’. Where ‘value’ is generally used as intermediate storage between start/stop and after stop have been called, ‘value’ is assigned as the difference between start/stop and added to ‘accum’. However, in the case where ‘accum’ is not a valid metric for the component, this trait can be used to save memory bc it results in the ‘accum’ data member to be implemented as a data-type of std::tuple<>, which only requires 1 byte of memory.

template<typename T> struct base_has_last : public false_type¶: trait that signifies that a component has an “last” value which may be different than the “value” value. In general, most components implement ‘value’ and ‘accum’ data members of ‘value_type’. Where ‘value’ is generally used as intermediate storage between start/stop and after stop have been called, ‘value’ is assigned as the difference between start/stop and added to ‘accum’. However, in the case where ‘value’ is valid as an individual measurement, this trait can be used to store ‘value’ as the individual measurement and ‘last’ as the difference or vice-versa.

template<typename Tp> struct dynamic_base : public std::false_type¶: trait that designates the type the static polymorphic base class (tim::component::base) inherit from.

Priority Ordering¶

template<typename T> struct start_priority : public std::integral_constant<int, 0>¶: trait that designates whether there is a priority when starting the type w.r.t. other types. Lower values indicate higher priority.

template<typename T> struct stop_priority : public std::integral_constant<int, 0>¶: trait that designates whether there is a priority when stopping the type w.r.t. other types. Lower values indicate higher priority.

template<typename T> struct fini_priority : public std::integral_constant<int, 0>¶: trait that designates whether there is a priority when finalizing the type w.r.t. other types. Recommended for component which hold instances of other components. Lower values indicate higher priority.

Data Collection¶

template<typename T> struct sampler : public false_type¶: trait that signifies the component supports sampling.

template<typename T> struct file_sampler : public false_type¶

trait that signifies the component samples a measurement from a file. If multiple components sample from the same file, it is recommended to create a cache type which performs a single read of the file and caches the values such that when these components are bundled together, they can just read their data from the cache structure.

Feature Support¶

template<typename T> struct supports_custom_record : public false_type¶: trait that designates the type supports changing the record() static function per-instance

template<typename T> struct supports_flamegraph : public false_type¶: trait that designates a type supports flamegraph output

Archive Serialization¶

template<typename Api> struct api_input_archive¶: trait that configures the default input archive type for an entire API specification, e.g. TIMEMORY_API (which is struct tim::project::timemory). The input archive format of individual components is determined from the derived tim::trait::input_archive

template<typename Api> struct api_output_archive¶: trait that configures the default output archive type for an entire API specification, e.g. TIMEMORY_API (which is struct tim::project::timemory). The output archive format of individual components is determined from the derived tim::trait::output_archive

template<typename T, typename Api> struct input_archive¶: trait that configures output archive type

template<typename T, typename Api> struct output_archive¶: trait that configures output archive type

template<typename T> struct pretty_archive : public std::false_type¶: trait that configures whether output archive uses pretty formmatting. If set to false_type then the JSON/XML/etc. will be compact (if supported)

template<typename T> struct requires_json : public false_type¶: trait that designates a type should always print a JSON output

Units and Formatting¶

template<typename T> struct is_memory_category : public false_type¶: trait that designates the width and precision should follow formatting settings related to memory measurements

template<typename T> struct is_timing_category : public false_type¶: trait that designates the width and precision should follow formatting settings related to timing measurements

template<typename T> struct uses_memory_units : public false_type¶: trait that designates the units should follow unit settings related to memory measurements

template<typename T> struct uses_timing_units : public false_type¶: trait that designates the units should follow unit settings related to timing measurements

template<typename T> struct uses_percent_units : public false_type¶: trait that designates the units are a percentage

template<typename T> struct units¶: trait that specifies the units

Output Reporting¶

template<typename T> struct report¶: trait that allows runtime configuration of reporting certain types of values. Only applies to text output. This will allows modifying the value set by the specific “report_*” type-trait.

template<typename T> struct report_count : public true_type¶: trait that configures type to not report the number of lap count (useful if meaningless). Only applies to text output.

template<typename T> struct report_depth : public true_type¶

template<typename T> struct report_metric_name : public true_type¶: trait that configures type to not report the “METRIC” column, useful if redundant). Only applies to text output.

template<typename T> struct report_units : public true_type¶: trait that configures type to not report the “UNITS” column (useful if always empty). Only applies to text output.

template<typename T> struct report_sum : public true_type¶: trait that configures type to not report the accumulated value (useful if meaningless). Only applies to text output.

template<typename T> struct report_mean : public true_type¶: trait that configures type to not report the mean value (useful if meaningless). Only applies to text output.

template<typename T> struct report_statistics : public true_type¶: trait that configures type to not report the “UNITS” column (useful if always empty). Only applies to text output and does NOT affect whether statistics are accumulated. For disabling statistics completely, see tim::trait::record_statistics and tim::policy::record_statistics.

template<typename T> struct report_self : public true_type¶: trait that configures type to not report the % self field (useful if meaningless). Only applies to text output.

template<typename T> struct custom_label_printing : public false_type¶: trait that signifies that a component will handle printing the label(s)

template<typename T> struct custom_serialization : public false_type¶: trait that signifies the component will be providing it’s own split load(…) and store(…) for serialization so do not provide one in the base class

template<typename T> struct custom_unit_printing : public false_type¶: trait that signifies that a component will handle printing the units(s)

template<typename T> struct echo_enabled : public true_type¶: trait that configures echo_measurement usage

template<typename T> struct iterable_measurement : public false_type¶: trait that signifies that get() returns an iterable type

Statistics¶

template<typename T> struct statistics¶: trait that specifies the data type of the statistics

template<typename T> struct record_statistics : public default_record_statistics_type¶: trait that signifies the component will calculate min/max/stddev

template<typename T> struct permissive_statistics : public false_type¶: trait that will suppress compilation error in operation::add_statistics<Component> if the data type passed is implicitly convertible to the data type in statistics<Component>::type but avoids converting integers to floating points and vice-versa.

Storage¶

template<typename T> struct uses_storage : public tim::trait::is_available<T>¶: trait that designates that a component will instantiate tim::storage

template<typename T, typename V, typename A> struct uses_value_storage¶: This trait is used to determine whether the (expensive) instantiation of the storage class happens.

template<typename T> struct tree_storage : public false_type¶: trait that configures type to always use hierarchical call-stack storage

template<typename T> struct flat_storage : public false_type¶: trait that configures type to always use flat call-stack storage

template<typename T> struct timeline_storage : public false_type¶: trait that configures type to always use timeline call-stack storage

template<typename T> struct thread_scope_only : public false_type¶: trait that signifies the component only has relevant values if it is not collapsed into the master thread

template<typename T> struct data¶: trait to specify the value type of a component before the definition of the component

template<typename T> struct secondary_data : public false_type¶

trait that signifies that secondary data resembling the original data exists but should be another node entry in the graph. These types must provide a get_secondary() member function and that member function must return a pair-wise iterable container, e.g. std::map, of types:

std::string
value_type

template<typename T> struct collects_data¶: trait that specifies or determines if a component collects any data. Default behavior is to check if the component is available and extract the type and value fields from tim::trait::component_value_type. When a component is available, the ‘type’ of this trait will return the ‘value type’ for a component regardless of whether it was specified within the component definition or if it was declared via a type-trait. The constexpr ‘value’ boolean indicates whether the ‘type’ is not a null type.

template<typename T, typename V> struct generates_output¶: trait used to evaluate whether a component value type produces a useable value

Deprecated¶

These type-traits are either:

Removed from the source code entirely
Automatically detected
Migrated to concepts

template<typename T> struct is_component : public false_type¶: trait that designates the type is a timemory component

template<typename T> struct is_gotcha : public false_type¶: trait that designates the type is a gotcha

template<typename T> struct is_user_bundle : public false_type¶: trait that designates the type is a user-bundle

template<typename T> struct record_max : public false_type¶: trait that signifies that updating w.r.t. another instance should be a max of the two instances

template<typename T> struct array_serialization : public false_type¶: trait that signifies that data is an array type

template<typename T> struct requires_prefix : public false_type¶: trait that signifies that a component requires the prefix to be set right after construction. Types with this trait must contain a member string variable named prefix

template<typename T, typename Tuple> struct supports_args : public false_type¶: trait that designates the type supports calling a function with a certain set of argument types (passed via a tuple).