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
>
structis_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
, typenameT
>
structpython_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
>
structdefault_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
>
structtim::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 boolget
(enable_if_t<is_available<U>::value && get_value<U>(), int> = 0)¶ GET specialization if component is available.
-
template<typename
U
= T>
static inline boolset
(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 boolget
(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 boolset
(bool, enable_if_t<!is_available<U>::value || !get_value<U>(), long> = 0)¶ SET specialization if component is NOT available.
-
using
-
template<typename
T
, typenameTag
>
structapi_components
¶ trait that designates components in an API (tim::api)
Base Class Modifications¶
-
template<typename
T
>
structbase_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
>
structbase_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
>
structdynamic_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
>
structstart_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
>
structstop_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
>
structfini_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
>
structcache
¶ 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
>
structderivation_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
>
structsampler
: public false_type¶ trait that signifies the component supports sampling.
-
template<typename
T
>
structfile_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
>
structsupports_custom_record
: public false_type¶ trait that designates the type supports changing the record() static function per-instance
-
template<typename
T
>
structsupports_flamegraph
: public false_type¶ trait that designates a type supports flamegraph output
Archive Serialization¶
-
template<typename
Api
>
structapi_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
>
structapi_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
, typenameApi
>
structinput_archive
¶ trait that configures output archive type
-
template<typename
T
, typenameApi
>
structoutput_archive
¶ trait that configures output archive type
-
template<typename
T
>
structpretty_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
>
structrequires_json
: public false_type¶ trait that designates a type should always print a JSON output
Units and Formatting¶
-
template<typename
T
>
structis_memory_category
: public false_type¶ trait that designates the width and precision should follow formatting settings related to memory measurements
-
template<typename
T
>
structis_timing_category
: public false_type¶ trait that designates the width and precision should follow formatting settings related to timing measurements
-
template<typename
T
>
structuses_memory_units
: public false_type¶ trait that designates the units should follow unit settings related to memory measurements
-
template<typename
T
>
structuses_timing_units
: public false_type¶ trait that designates the units should follow unit settings related to timing measurements
-
template<typename
T
>
structuses_percent_units
: public false_type¶ trait that designates the units are a percentage
-
template<typename
T
>
structunits
¶ trait that specifies the units
Output Reporting¶
-
template<typename
T
>
structreport
¶ 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
>
structreport_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
>
structreport_depth
: public true_type¶
-
template<typename
T
>
structreport_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
>
structreport_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
>
structreport_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
>
structreport_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
>
structreport_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
>
structreport_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
>
structcustom_label_printing
: public false_type¶ trait that signifies that a component will handle printing the label(s)
-
template<typename
T
>
structcustom_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
>
structcustom_unit_printing
: public false_type¶ trait that signifies that a component will handle printing the units(s)
-
template<typename
T
>
structecho_enabled
: public true_type¶ trait that configures echo_measurement usage
-
template<typename
T
>
structiterable_measurement
: public false_type¶ trait that signifies that get() returns an iterable type
Statistics¶
-
template<typename
T
>
structstatistics
¶ trait that specifies the data type of the statistics
-
template<typename
T
>
structrecord_statistics
: public default_record_statistics_type¶ trait that signifies the component will calculate min/max/stddev
-
template<typename
T
>
structpermissive_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
>
structuses_storage
: public tim::trait::is_available<T>¶ trait that designates that a component will instantiate tim::storage
-
template<typename
T
, typenameV
, typenameA
>
structuses_value_storage
¶ This trait is used to determine whether the (expensive) instantiation of the storage class happens.
-
template<typename
T
>
structtree_storage
: public false_type¶ trait that configures type to always use hierarchical call-stack storage
-
template<typename
T
>
structflat_storage
: public false_type¶ trait that configures type to always use flat call-stack storage
-
template<typename
T
>
structtimeline_storage
: public false_type¶ trait that configures type to always use timeline call-stack storage
-
template<typename
T
>
structthread_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
>
structdata
¶ trait to specify the value type of a component before the definition of the component
-
template<typename
T
>
structsecondary_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
>
structcollects_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
, typenameV
>
structgenerates_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
>
structis_component
: public false_type¶ trait that designates the type is a timemory component
-
template<typename
T
>
structis_gotcha
: public false_type¶ trait that designates the type is a gotcha
-
template<typename
T
>
structis_user_bundle
: public false_type¶ trait that designates the type is a user-bundle
-
template<typename
T
>
structrecord_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
>
structarray_serialization
: public false_type¶ trait that signifies that data is an array type
-
template<typename
T
>
structrequires_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
, typenameTuple
>
structsupports_args
: public false_type¶ trait that designates the type supports calling a function with a certain set of argument types (passed via a tuple).