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 atim::type_list<...>
oftim::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:The type-trait specification would look like this:foo = timemory.component.CaliperLoopMarker("example") foo.start() for i in range(10): foo.store(i) # store member function accepting integer # ... foo.stop()
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<U>::value && get_value<U>(), int> = 0)¶ GET specialization if component is available.
-
template<typename U = T>
static inline bool set(bool val, enable_if_t<is_available<U>::value && get_value<U>(), int> = 0)¶ SET specialization if component is available.
-
template<typename U = T>
static inline bool get(enable_if_t<!is_available<U>::value || !get_value<U>(), long> = 0)¶ GET specialization if component is NOT available.
-
template<typename U = T>
static inline bool set(bool, enable_if_t<!is_available<U>::value || !get_value<U>(), long> = 0)¶ SET specialization if component is NOT available.
-
using api_type_list = mpl::get_true_types_t<concepts::is_runtime_configurable, component_apis_t<T>>¶
-
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 Sharing¶
-
template<typename T>
struct cache¶ trait that specifies the intermediate data type that will hold the relevant data required by the component. This is useful for when multiple components read different parts of the same file (e.g. /proc/<PID>/io) or an API reports data in a larger data structure than the scope of the component (e.g. rusage) but multiple components require access to this data structure
-
template<typename T>
struct derivation_types : public false_type¶ trait that designates the type supports calling assemble and derive member functions with these types. Specializations MUST be structured as a tim::type_list<…> of tim::type_list<…> where each inner type_list entry is the list of component types required to perform a derivation.
template <> struct derivation_types<cpu_util> { // can derive its data when present alongside wall_clock + cpu_clock and/or // wall_clock + user_clock + system_clock using type = type_list< type_list<wall_clock, cpu_clock>, type_list<wall_clock, user_clock, system_clock> >; };
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.
See also: tim::trait::cache
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 instatistics<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).