C / C++ / Fortran Library

Interface

Typedefs

typedef void (*timemory_create_func_t)(const char*, uint64_t*, int, int*)
typedef void (*timemory_delete_func_t)(uint64_t)

function pointer type for timemory_delete_function

Functions

uint64_t timemory_get_unique_id(void)

Returns a unique integer for a thread.

void timemory_create_record(const char *name, uint64_t *id, int n, int *ct)

Function called by timemory_begin_record, timemory_begin_record_enum, timemory_begin_record_types, timemory_get_begin_record, timemory_get_begin_record_enum, timemory_get_begin_record_types, timemory_push_region for creating and starting the current collection of components.

Parameters
  • name[in] label for the record

  • id[inout] assigned a unique identifier for the record

  • n[in] number of components

  • ct[in] array of enumeration identifiers of size n

void timemory_delete_record(uint64_t nid)

Deletes the record created by timemory_create_record.

bool timemory_library_is_initialized(void)

Returns whether the library is initialized or not.

void timemory_named_init_library(char *name)
void timemory_init_library(int argc, char **argv)

Initializes timemory. Not strictly necessary but highly recommended.

void timemory_finalize_library(void)

Finalizes timemory. Output will be generated. Any attempt to store data within timemory storage is undefined after this point and will likely cause errors.

void timemory_pause(void)

Turn off timemory collection.

void timemory_resume(void)

Turn on timemory collection.

void timemory_set_default(const char *components)

Pass in a default set of components to use. Will be overridden by TIMEMORY_COMPONENTS environment variable.

timemory_set_default("wall_clock, cpu_clock, cpu_util");

void timemory_set_environ(const char *evar, const char *eval, int ovr, int up)

Set an environment variable and (potentially) update settings with new value.

// overwrites the TIMEMORY_GLOBAL_COMPONENTS environment variable and updates
// settings
timemory_set_environ("TIIMEMORY_GLOBAL_COMPONENTS,
                     "wall_clock, cpu_clock, cpu_util", 1, 1);

Parameters
  • evar[in] Environment variable name

  • eval[in] Environment variable value

  • ovr[in] Overwrite existing environment variable when > 0

  • up[in] Update settings when > 0

void timemory_add_components(const char *components)

Add some components to the current set of components being collected Any components which are currently being collected are ignored.

timemory_add_components("peak_rss, priority_context_switch");

void timemory_remove_components(const char *components)

Remove some components to the current set of components being collected. Any components which are not currently being collected are ignored.

timemory_add_components("priority_context_switch, read_bytes");

void timemory_push_components(const char *components)

Replace the current set of components with a new set of components.

timemory_push_components("priority_context_switch, read_bytes");

void timemory_push_components_enum(int args, ...)

Replace the current set of components with a new set of components with the set of enumerations provided to the function. First argument should be the number of new components.

timemory_push_components(2, WALL_CLOCK, CPU_CLOCK);

void timemory_pop_components(void)

Inverse of the last timemory_push_components or timemory_push_components_enum call. Popping all components will restore to set the configured as the default.

void timemory_begin_record(const char *name, uint64_t *id)

uint64_t idx = 0;
timemory_begin_record("foo", &idx);
// ...
timemory_end_record(idx);

Parameters
  • name[in] Label for the record

  • id[inout] identifier passed back to timemory_end_record

void timemory_begin_record_enum(const char *name, uint64_t*, ...)

Similar to timemory_begin_record but accepts a specific enumerated set of components, which is terminated by TIMEMORY_COMPONENTS_END.

uint64_t idx = 0;
timemory_begin_record("foo", &idx, WALL_CLOCK, CPU_UTIL, TIMEMORY_COMPONENTS_END);
// ...
timemory_end_record(idx);

void timemory_begin_record_types(const char *name, uint64_t*, const char*)

Similar to timemory_begin_record but accepts a specific set of components as a string.

uint64_t idx = 0;
timemory_begin_record_types("foo", &idx, "wall_clock, cpu_util");
// ...
timemory_end_record(idx);

uint64_t timemory_get_begin_record(const char *name)

Variant to timemory_begin_record which returns a unique integer.

uint64_t timemory_get_begin_record_enum(const char *name, ...)

Variant to timemory_begin_record_enum which returns a unique integer.

uint64_t timemory_get_begin_record_types(const char *name, const char *ctypes)

Variant to timemory_begin_record_types which returns a unique integer.

void timemory_end_record(uint64_t id)
Parameters

id[in] Identifier for the recording entry

void timemory_push_region(const char *name)

Starts collection of components with label.

void foo()
{
    timemory_push_region("foo");
    // ...
    timemory_pop_region("foo");
}

Parameters

name[in] label for region

void timemory_pop_region(const char *name)

Stops collection of components with label.

void foo()
{
    timemory_push_region("foo");
    // ...
    timemory_pop_region("foo");
}

Parameters

name[in] label for region

void c_timemory_init(int argc, char **argv, timemory_settings)
void c_timemory_finalize(void)
int c_timemory_enabled(void)
void *c_timemory_create_auto_timer(const char*)
void c_timemory_delete_auto_timer(void*)
void *c_timemory_create_auto_tuple(const char*, ...)
void c_timemory_delete_auto_tuple(void*)
const char *c_timemory_blank_label(const char*)
const char *c_timemory_basic_label(const char*, const char*)
const char *c_timemory_label(const char*, const char*, int, const char*)
int cxx_timemory_enabled(void)
void cxx_timemory_init(int, char**, timemory_settings)
void *cxx_timemory_create_auto_timer(const char*)
void *cxx_timemory_create_auto_tuple(const char*, int, const int*)
void *cxx_timemory_delete_auto_timer(void*)
void *cxx_timemory_delete_auto_tuple(void*)
const char *cxx_timemory_label(int, int, const char*, const char*, const char*)
bool timemory_trace_is_initialized(void)
void timemory_reset_throttle(const char *name)
bool timemory_is_throttled(const char *name)
void timemory_add_hash_id(uint64_t id, const char *name)
void timemory_add_hash_ids(uint64_t nentries, uint64_t *ids, const char **names)
void timemory_push_trace_hash(uint64_t id)
void timemory_pop_trace_hash(uint64_t id)
void timemory_push_trace(const char *name)
void timemory_pop_trace(const char *name)
void timemory_trace_init(const char*, bool, const char*)
void timemory_trace_finalize(void)
void timemory_trace_set_env(const char*, const char*)

Variables

timemory_create_func_t timemory_create_function

The function pointer to set to customize which components are used by library interface.

using namespace tim::component;
using test_list_t =
    tim::component_list<wall_clock, cpu_util, cpu_clock, peak_rss>;

static std::map<uint64_t, std::shared_ptr<test_list_t>> test_map;

void
custom_create_record(const char* name, uint64_t* id, int n, int* ct)
{
    uint64_t idx = timemory_get_unique_id();
    auto     tmp = std::make_shared<test_list_t>(name);
    tim::initialize(*tmp, n, ct);
    tmp->initialize<cpu_util, cpu_clock>();
    test_map[idx] = tmp;
    test_map[idx]->start();
    *id = idx;
}

void
main()
{
    // ... using default create/delete functions ...

    timemory_create_function = &custom_create_record;
    timemory_delete_function = ...;

    // ... using custom create/delete functions ...

    timemory_create_function = nullptr;
    timemory_delete_function = ...;

    // ... using default create/delete functions ...

}

timemory_delete_func_t timemory_delete_function

The function pointer to set which deletes an entry created by timemory_create_function.

static std::map<uint64_t, std::shared_ptr<test_list_t>> test_map;

void
custom_delete_record(uint64_t id)
{
    auto itr = test_map.find(id);
    if(itr != test_map.end())
    {
        itr->second->stop();
        test_map.erase(itr);
    }
}

void
main()
{
    // ... using default create/delete functions ...

    timemory_create_function = &custom_create_record;
    timemory_delete_function = &custom_delete_record;

    // ... using custom create/delete functions ...

    timemory_create_function = nullptr;
    timemory_delete_function = nullptr;

    // ... using default create/delete functions ...

}

Enumerations

enum TIMEMORY_NATIVE_COMPONENT

Enumerated identifiers for timemory-provided components.

Values:

enumerator TIMEMORY_ALLINEA_MAP_idx
enumerator TIMEMORY_CALIPER_MARKER_idx
enumerator TIMEMORY_CALIPER_CONFIG_idx
enumerator TIMEMORY_CALIPER_LOOP_MARKER_idx
enumerator TIMEMORY_CPU_CLOCK_idx
enumerator TIMEMORY_CPU_ROOFLINE_DP_FLOPS_idx
enumerator TIMEMORY_CPU_ROOFLINE_FLOPS_idx
enumerator TIMEMORY_CPU_ROOFLINE_SP_FLOPS_idx
enumerator TIMEMORY_CPU_UTIL_idx
enumerator TIMEMORY_CRAYPAT_COUNTERS_idx
enumerator TIMEMORY_CRAYPAT_FLUSH_BUFFER_idx
enumerator TIMEMORY_CRAYPAT_HEAP_STATS_idx
enumerator TIMEMORY_CRAYPAT_RECORD_idx
enumerator TIMEMORY_CRAYPAT_REGION_idx
enumerator TIMEMORY_CUDA_EVENT_idx
enumerator TIMEMORY_CUDA_PROFILER_idx
enumerator TIMEMORY_CUPTI_ACTIVITY_idx
enumerator TIMEMORY_CUPTI_COUNTERS_idx
enumerator TIMEMORY_CUPTI_PCSAMPLING_idx
enumerator TIMEMORY_CURRENT_PEAK_RSS_idx
enumerator TIMEMORY_DATA_TRACKER_INTEGER_idx
enumerator TIMEMORY_DATA_TRACKER_UNSIGNED_idx
enumerator TIMEMORY_DATA_TRACKER_FLOATING_idx
enumerator TIMEMORY_GPERFTOOLS_CPU_PROFILER_idx
enumerator TIMEMORY_GPERFTOOLS_HEAP_PROFILER_idx
enumerator TIMEMORY_GPU_ROOFLINE_DP_FLOPS_idx
enumerator TIMEMORY_GPU_ROOFLINE_FLOPS_idx
enumerator TIMEMORY_GPU_ROOFLINE_HP_FLOPS_idx
enumerator TIMEMORY_GPU_ROOFLINE_SP_FLOPS_idx
enumerator TIMEMORY_HIP_EVENT_idx
enumerator TIMEMORY_KERNEL_MODE_TIME_idx
enumerator TIMEMORY_LIKWID_MARKER_idx
enumerator TIMEMORY_LIKWID_NVMARKER_idx
enumerator TIMEMORY_MALLOC_GOTCHA_idx
enumerator TIMEMORY_MEMORY_ALLOCATIONS_idx
enumerator TIMEMORY_MONOTONIC_CLOCK_idx
enumerator TIMEMORY_MONOTONIC_RAW_CLOCK_idx
enumerator TIMEMORY_NETWORK_STATS_idx
enumerator TIMEMORY_NUM_IO_IN_idx
enumerator TIMEMORY_NUM_IO_OUT_idx
enumerator TIMEMORY_NUM_MAJOR_PAGE_FAULTS_idx
enumerator TIMEMORY_NUM_MINOR_PAGE_FAULTS_idx
enumerator TIMEMORY_NVTX_MARKER_idx
enumerator TIMEMORY_OMPT_HANDLE_idx
enumerator TIMEMORY_PAGE_RSS_idx
enumerator TIMEMORY_PAPI_ARRAY_idx
enumerator TIMEMORY_PAPI_VECTOR_idx
enumerator TIMEMORY_PEAK_RSS_idx
enumerator TIMEMORY_PERFETTO_TRACE_idx
enumerator TIMEMORY_PRINTER_idx
enumerator TIMEMORY_PRIORITY_CONTEXT_SWITCH_idx
enumerator TIMEMORY_PROCESS_CPU_CLOCK_idx
enumerator TIMEMORY_PROCESS_CPU_UTIL_idx
enumerator TIMEMORY_READ_BYTES_idx
enumerator TIMEMORY_READ_CHAR_idx
enumerator TIMEMORY_ROCTX_MARKER_idx
enumerator TIMEMORY_SYS_CLOCK_idx
enumerator TIMEMORY_TAU_MARKER_idx
enumerator TIMEMORY_THREAD_CPU_CLOCK_idx
enumerator TIMEMORY_THREAD_CPU_UTIL_idx
enumerator TIMEMORY_TIMESTAMP_idx
enumerator TIMEMORY_TRIP_COUNT_idx
enumerator TIMEMORY_USER_CLOCK_idx
enumerator TIMEMORY_USER_MODE_TIME_idx
enumerator TIMEMORY_USER_GLOBAL_BUNDLE_idx
enumerator TIMEMORY_USER_KOKKOSP_BUNDLE_idx
enumerator TIMEMORY_USER_LIST_BUNDLE_idx
enumerator TIMEMORY_USER_MPIP_BUNDLE_idx
enumerator TIMEMORY_USER_NCCLP_BUNDLE_idx
enumerator TIMEMORY_USER_OMPT_BUNDLE_idx
enumerator TIMEMORY_USER_TUPLE_BUNDLE_idx
enumerator TIMEMORY_USER_PROFILER_BUNDLE_idx
enumerator TIMEMORY_USER_TRACE_BUNDLE_idx
enumerator TIMEMORY_VIRTUAL_MEMORY_idx
enumerator TIMEMORY_VOLUNTARY_CONTEXT_SWITCH_idx
enumerator TIMEMORY_VTUNE_EVENT_idx
enumerator TIMEMORY_VTUNE_FRAME_idx
enumerator TIMEMORY_VTUNE_PROFILER_idx
enumerator TIMEMORY_WALL_CLOCK_idx
enumerator TIMEMORY_WRITTEN_BYTES_idx
enumerator TIMEMORY_WRITTEN_CHAR_idx
enumerator TIMEMORY_NATIVE_COMPONENTS_END_idx
enumerator TIMEMORY_COMPONENTS_END_idx
enum TIMEMORY_OPERATION

Enumerated identifiers for subset of common operations for usage in C code and specializations of tim::trait::python_args.

Values:

enumerator TIMEMORY_CONSTRUCT
enumerator TIMEMORY_GET
enumerator TIMEMORY_AUDIT
enumerator TIMEMORY_START
enumerator TIMEMORY_STOP
enumerator TIMEMORY_STORE
enumerator TIMEMORY_RECORD
enumerator TIMEMORY_SAMPLE
enumerator TIMEMORY_MEASURE
enumerator TIMEMORY_MARK_BEGIN
enumerator TIMEMORY_MARK_END
enumerator TIMEMORY_OPERATION_END