library.h File Reference

#include <stdbool.h>
#include <stddef.h>
#include <stdint.h>
#include <stdio.h>
#include <stdlib.h>
#include <string.h>
#include "timemory/compat/macros.h"
#include "timemory/enum.h"

Include dependency graph for library.h:

This graph shows which files directly or indirectly include this file:

Go to the source code of this file.

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 More...

Functions
uint64_t	timemory_get_unique_id (void)
	Returns a unique integer for a thread. More...
void	timemory_create_record (const char *name, uint64_t *id, int n, int *ct)
void	timemory_delete_record (uint64_t nid)
	Deletes the record created by timemory_create_record. More...
bool	timemory_library_is_initialized (void)
	Returns whether the library is initialized or not. More...
void	timemory_named_init_library (char *name)
void	timemory_init_library (int argc, char **argv)
	Initializes timemory. Not strictly necessary but highly recommended. More...
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. More...
void	timemory_pause (void)
	Turn off timemory collection. More...
void	timemory_resume (void)
	Turn on timemory collection. More...
void	timemory_set_default (const char *components)
	Pass in a default set of components to use. Will be overridden by TIMEMORY_COMPONENTS environment variable. More...
void	timemory_set_environ (const char *evar, const char *eval, int ovr, int up)
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. More...
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. More...
void	timemory_push_components (const char *components)
	Replace the current set of components with a new set of components. More...
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. More...
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. More...
void	timemory_begin_record (const char *name, uint64_t *id)
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. More...
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. More...
uint64_t	timemory_get_begin_record (const char *name)
	Variant to timemory_begin_record which returns a unique integer. More...
uint64_t	timemory_get_begin_record_enum (const char *name,...)
	Variant to timemory_begin_record_enum which returns a unique integer. More...
uint64_t	timemory_get_begin_record_types (const char *name, const char *ctypes)
	Variant to timemory_begin_record_types which returns a unique integer. More...
void	timemory_end_record (uint64_t id)
void	timemory_push_region (const char *name)
void	timemory_pop_region (const char *name)
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. More...
timemory_delete_func_t	timemory_delete_function
	The function pointer to set which deletes an entry created by timemory_create_function. More...

Typedef Documentation

timemory_create_func_t

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

Definition at line 334 of file library.h.

timemory_delete_func_t

void(* timemory_delete_func_t)(uint64_t)

function pointer type for timemory_delete_function

Definition at line 338 of file library.h.

Function Documentation

c_timemory_basic_label()

const char * c_timemory_basic_label	(	const char *	_func,
		const char *	_extra
	)

Definition at line 138 of file timemory_c.c.

    {
        return cxx_timemory_label(1, 0, _func, "", _extra);
    }

References cxx_timemory_label().

c_timemory_blank_label()

const char * c_timemory_blank_label

(

const char *

_extra

)

Definition at line 131 of file timemory_c.c.

    {
        return cxx_timemory_label(0, 0, "", "", _extra);
    }

References cxx_timemory_label().

c_timemory_create_auto_timer()

void * c_timemory_create_auto_timer

(

const char *

tag

)

Definition at line 73 of file timemory_c.c.

    {
        void* _ret = NULL;
        if(cxx_timemory_enabled())
            _ret = cxx_timemory_create_auto_timer(tag);
        return _ret;
    }

References cxx_timemory_create_auto_timer(), and cxx_timemory_enabled().

c_timemory_create_auto_tuple()

void * c_timemory_create_auto_tuple	(	const char *	tag,
			...
	)

Definition at line 83 of file timemory_c.c.

    {
        if(!cxx_timemory_enabled())
            return NULL;
 
        const int max_size       = (int) TIMEMORY_COMPONENTS_END;
        int       num_components = 0;
        int*      components     = (int*) malloc(max_size * sizeof(int));
        if(!components)
            return NULL;
        va_list args;
        va_start(args, tag);
        for(int i = 0; i < max_size; ++i)
        {
            int comp = va_arg(args, int);
            if(comp >= TIMEMORY_COMPONENTS_END)
                break;
            ++num_components;
            components[i] = comp;
        }
        va_end(args);
 
        void* ptr = NULL;
        if(num_components > 0)
            ptr = cxx_timemory_create_auto_tuple(tag, num_components, components);
        free(components);
 
        return ptr;
    }

References tim::components, cxx_timemory_create_auto_tuple(), cxx_timemory_enabled(), and TIMEMORY_COMPONENTS_END.

c_timemory_delete_auto_timer()

void c_timemory_delete_auto_timer

(

void *

ctimer

)

Definition at line 115 of file timemory_c.c.

    {
        ctimer = cxx_timemory_delete_auto_timer(ctimer);
        assert(ctimer == NULL);
    }

References cxx_timemory_delete_auto_timer().

c_timemory_delete_auto_tuple()

void c_timemory_delete_auto_tuple

(

void *

ctuple

)

Definition at line 123 of file timemory_c.c.

    {
        ctuple = cxx_timemory_delete_auto_tuple(ctuple);
        assert(ctuple == NULL);
    }

References cxx_timemory_delete_auto_tuple().

c_timemory_enabled()

int c_timemory_enabled

(

void

)

Definition at line 69 of file timemory_c.c.

{ return cxx_timemory_enabled(); }

References cxx_timemory_enabled().

c_timemory_finalize()

void c_timemory_finalize

(

void

)

Definition at line 65 of file timemory_c.c.

{ timemory_finalize_library(); }

References timemory_finalize_library().

c_timemory_init()

void c_timemory_init	(	int	argc,
		char **	argv,
		timemory_settings	_settings
	)

Definition at line 57 of file timemory_c.c.

    {
        cxx_timemory_init(argc, argv, _settings);
        timemory_init_library(argc, argv);
    }

References tim::_settings, tim::argv, cxx_timemory_init(), and timemory_init_library().

c_timemory_label()

const char * c_timemory_label	(	const char *	_func,
		const char *	_file,
		int	_line,
		const char *	_extra
	)

Definition at line 145 of file timemory_c.c.

    {
        return cxx_timemory_label(2, _line, _func, _file, _extra);
    }

References tim::plotting::_file, and cxx_timemory_label().

cxx_timemory_create_auto_timer()

void * cxx_timemory_create_auto_timer

(

const char *

)

Referenced by c_timemory_create_auto_timer().

cxx_timemory_create_auto_tuple()

void * cxx_timemory_create_auto_tuple	(	const char *	,
		int	,
		const int *
	)

Referenced by c_timemory_create_auto_tuple().

cxx_timemory_delete_auto_timer()

void * cxx_timemory_delete_auto_timer

(

void *

)

Referenced by c_timemory_delete_auto_timer().

cxx_timemory_delete_auto_tuple()

void * cxx_timemory_delete_auto_tuple

(

void *

)

Referenced by c_timemory_delete_auto_tuple().

cxx_timemory_enabled()

int cxx_timemory_enabled

(

void

)

Referenced by c_timemory_create_auto_timer(), c_timemory_create_auto_tuple(), and c_timemory_enabled().

cxx_timemory_init()

void cxx_timemory_init	(	int	,
		char **	,
		timemory_settings
	)

Referenced by c_timemory_init().

cxx_timemory_label()

const char * cxx_timemory_label	(	int	,
		int	,
		const char *	,
		const char *	,
		const char *
	)

Referenced by c_timemory_basic_label(), c_timemory_blank_label(), and c_timemory_label().

timemory_add_components()

void timemory_add_components

(

const char *

_component_string

)

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");

Definition at line 348 of file library.cpp.

    {
        tim::trace::lock<tim::trace::library> lk{};
        auto&                                 _stack = get_current_components();
        for(auto itr : tim::enumerate_components(_component_string))
            _stack.push_back(itr);
    }

References tim::enumerate_components(), and get_current_components().

timemory_add_hash_id()

void timemory_add_hash_id	(	uint64_t	id,
		const char *	name
	)

Definition at line 392 of file trace.cpp.

    {
        tim::trace::lock<tim::trace::library> lk{};
        if(!lk)
        {
            if(tim::settings::debug())
                fprintf(stderr,
                        "[timemory-trace]> timemory_add_hash_id failed: locked...\n");
            return;
        }
        if(tim::settings::debug())
            fprintf(stderr, "[timemory-trace]> adding '%s' with hash %lu...\n", name,
                    (unsigned long) id);
        auto _id = tim::add_hash_id(name);
        if(_id != id)
            tim::add_hash_id(_id, id);
 
        // master thread adds the ids
        if(tim::threading::get_id() == 0)
        {
            master_hash_ids[id] = name;
            if(_id != id)
                master_hash_ids[_id] = name;
        }
    }

References tim::debug.

Referenced by timemory_add_hash_ids().

timemory_add_hash_ids()

void timemory_add_hash_ids	(	uint64_t	nentries,
		uint64_t *	ids,
		const char **	names
	)

Definition at line 420 of file trace.cpp.

    {
        if(tim::settings::debug())
            fprintf(stderr, "[timemory-trace]> adding %lu hash ids...\n",
                    (unsigned long) nentries);
        for(uint64_t i = 0; i < nentries; ++i)
            timemory_add_hash_id(ids[i], names[i]);
    }

References tim::debug, and timemory_add_hash_id().

timemory_begin_record()

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

Parameters

[in]	name	Label for the record
[in,out]	id	identifier passed back to timemory_end_record

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

Definition at line 409 of file library.cpp.

    {
        tim::trace::lock<tim::trace::library> lk{};
        if(!lk || tim::settings::enabled() == false)
        {
            *id = std::numeric_limits<uint64_t>::max();
            return;
        }
        auto& comp = get_current_components();
        timemory_create_record(name, id, comp.size(), (int*) (comp.data()));
 
#if defined(DEBUG)
        if(tim::settings::verbose() > 2)
            printf("beginning record for '%s' (id = %lli)...\n", name,
                   (long long int) *id);
#endif
    }

References tim::enabled, get_current_components(), std::max(), timemory_create_record(), and tim::verbose.

Referenced by timemory_begin_record_().

timemory_begin_record_enum()

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

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);

Definition at line 450 of file library.cpp.

    {
        tim::trace::lock<tim::trace::library> lk{};
        if(!lk || tim::settings::enabled() == false)
        {
            *id = std::numeric_limits<uint64_t>::max();
            return;
        }
 
        component_enum_t comp;
        va_list          args;
        va_start(args, id);
        for(int i = 0; i < TIMEMORY_COMPONENTS_END; ++i)
        {
            auto enum_arg = va_arg(args, int);
            if(enum_arg >= TIMEMORY_COMPONENTS_END)
                break;
            comp.push_back(enum_arg);
        }
        va_end(args);
 
        timemory_create_record(name, id, comp.size(), (int*) (comp.data()));
 
#if defined(DEBUG)
        if(tim::settings::verbose() > 2)
            printf("beginning record for '%s' (id = %lli)...\n", name,
                   (long long int) *id);
#endif
    }

References tim::enabled, std::max(), TIMEMORY_COMPONENTS_END, timemory_create_record(), and tim::verbose.

timemory_begin_record_types()

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

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);

Definition at line 429 of file library.cpp.

    {
        tim::trace::lock<tim::trace::library> lk{};
        if(!lk || tim::settings::enabled() == false)
        {
            *id = std::numeric_limits<uint64_t>::max();
            return;
        }
 
        auto comp = tim::enumerate_components(std::string(ctypes));
        timemory_create_record(name, id, comp.size(), (int*) (comp.data()));
 
#if defined(DEBUG)
        if(tim::settings::verbose() > 2)
            printf("beginning record for '%s' (id = %lli)...\n", name,
                   (long long int) *id);
#endif
    }

References tim::enabled, tim::enumerate_components(), std::max(), timemory_create_record(), and tim::verbose.

Referenced by timemory_begin_record_types_().

timemory_create_record()

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

Parameters

[in]	name	label for the record
[in,out]	id	assigned a unique identifier for the record
[in]	n	number of components
[in]	ct	array of enumeration identifiers of size n

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.

Definition at line 156 of file library.cpp.

    {
        if(timemory_create_function)
        {
            (*timemory_create_function)(name, id, n, ctypes);
            return;
        }
        // else: provide default behavior
 
        static thread_local auto& _record_map = get_record_map();
        *id                                   = timemory_get_unique_id();
        _record_map.insert({ *id, toolset_t(name, true) });
        tim::initialize(_record_map[*id], n, ctypes);
        _record_map[*id].start();
        if(_record_map.bucket_count() > _record_map.size())
            _record_map.rehash(_record_map.size() + 10);
    }

References timemory_create_function.

Referenced by timemory_begin_record(), timemory_begin_record_enum(), timemory_begin_record_types(), timemory_create_record_(), timemory_get_begin_record(), timemory_get_begin_record_enum(), and timemory_get_begin_record_types().

timemory_delete_record()

void timemory_delete_record

(

uint64_t

nid

)

Deletes the record created by timemory_create_record.

Definition at line 177 of file library.cpp.

    {
        if(timemory_delete_function)
        {
            (*timemory_delete_function)(id);
        }
        else if(get_record_map().find(id) != get_record_map().end())
        {
            static thread_local auto& _record_map = get_record_map();
            // stop recording, destroy objects, and erase key from map
            _record_map[id].stop();
            _record_map.erase(id);
        }
    }

References timemory_delete_function.

Referenced by timemory_delete_record_(), and timemory_end_record().

timemory_end_record()

void timemory_end_record

(

uint64_t

id

)

Parameters

[in]

id

Identifier for the recording entry

Definition at line 557 of file library.cpp.

    {
        tim::trace::lock<tim::trace::library> lk{};
        if(!lk || id == std::numeric_limits<uint64_t>::max())
            return;
 
        timemory_delete_record(id);
 
#if defined(DEBUG)
        if(tim::settings::verbose() > 2)
            printf("ending record for %lli...\n", (long long int) id);
#endif
    }

References std::max(), timemory_delete_record(), and tim::verbose.

Referenced by timemory_end_record_().

timemory_finalize_library()

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.

Definition at line 253 of file library.cpp.

    {
        tim::trace::lock<tim::trace::library> lk{};
        get_library_state()[1] = true;
 
        auto  _manager  = tim::manager::master_instance();
        auto* _settings = tim::settings::instance();
        if(!_manager || !_settings)
            return;
 
        if(_settings->get_enabled() == false && get_record_map().empty())
            return;
 
        auto& _record_map = get_record_map();
 
        if(_settings->get_verbose() > 0)
        {
            printf("\n%s\n", spacer.c_str());
            printf("\tFinalization of timemory library...\n");
            printf("%s\n\n", spacer.c_str());
        }
 
        // put keys into a set so that a potential LD_PRELOAD for timemory_delete_record
        // is called and there is not a concern for the map iterator
        std::unordered_set<uint64_t> keys;
        for(auto& itr : _record_map)
            keys.insert(itr.first);
 
        // delete all the records
        for(const auto& itr : keys)
            timemory_delete_record(itr);
 
        // clear the map
        _record_map.clear();
 
        // have the manager finalize
        if(tim::manager::instance())
            tim::manager::instance()->finalize();
 
        // do the finalization
        tim::timemory_finalize();
 
        // just in case
        _settings->get_enabled() = false;
 
        // set the finalization state to true
        tim::dmp::set_finalized(true);
 
        // reset manager
        tim::manager::instance().reset();
 
        // PGI and Intel compilers don't respect destruction order
#if defined(__PGI) || defined(__INTEL_COMPILER)
        _settings->get_output() = false;
#endif
    }

References get_library_state().

Referenced by c_timemory_finalize(), and timemory_finalize_library_().

timemory_get_begin_record()

uint64_t timemory_get_begin_record

(

const char *

name

)

Variant to timemory_begin_record which returns a unique integer.

Definition at line 482 of file library.cpp.

    {
        tim::trace::lock<tim::trace::library> lk{};
        if(!lk || tim::settings::enabled() == false)
            return std::numeric_limits<uint64_t>::max();
 
        uint64_t id   = 0;
        auto&    comp = get_current_components();
        timemory_create_record(name, &id, comp.size(), (int*) (comp.data()));
 
#if defined(DEBUG)
        if(tim::settings::verbose() > 2)
            printf("beginning record for '%s' (id = %lli)...\n", name,
                   (long long int) id);
#endif
 
        return id;
    }

References tim::enabled, get_current_components(), std::max(), timemory_create_record(), and tim::verbose.

Referenced by timemory_get_begin_record_().

timemory_get_begin_record_enum()

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

Variant to timemory_begin_record_enum which returns a unique integer.

Definition at line 524 of file library.cpp.

    {
        tim::trace::lock<tim::trace::library> lk{};
        if(!lk || tim::settings::enabled() == false)
            return std::numeric_limits<uint64_t>::max();
 
        uint64_t id = 0;
 
        component_enum_t comp;
        va_list          args;
        va_start(args, name);
        for(int i = 0; i < TIMEMORY_COMPONENTS_END; ++i)
        {
            auto enum_arg = va_arg(args, int);
            if(enum_arg >= TIMEMORY_COMPONENTS_END)
                break;
            comp.push_back(enum_arg);
        }
        va_end(args);
 
        timemory_create_record(name, &id, comp.size(), (int*) (comp.data()));
 
#if defined(DEBUG)
        if(tim::settings::verbose() > 2)
            printf("beginning record for '%s' (id = %lli)...\n", name,
                   (long long int) id);
#endif
 
        return id;
    }

References tim::enabled, std::max(), TIMEMORY_COMPONENTS_END, timemory_create_record(), and tim::verbose.

timemory_get_begin_record_types()

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

Variant to timemory_begin_record_types which returns a unique integer.

Definition at line 503 of file library.cpp.

    {
        tim::trace::lock<tim::trace::library> lk{};
        if(!lk || tim::settings::enabled() == false)
            return std::numeric_limits<uint64_t>::max();
 
        uint64_t id   = 0;
        auto     comp = tim::enumerate_components(std::string(ctypes));
        timemory_create_record(name, &id, comp.size(), (int*) (comp.data()));
 
#if defined(DEBUG)
        if(tim::settings::verbose() > 2)
            printf("beginning record for '%s' (id = %lli)...\n", name,
                   (long long int) id);
#endif
 
        return id;
    }

References tim::enabled, tim::enumerate_components(), std::max(), timemory_create_record(), and tim::verbose.

Referenced by timemory_get_begin_record_types_().

timemory_get_unique_id()

uint64_t timemory_get_unique_id

(

void

)

Returns a unique integer for a thread.

Definition at line 144 of file library.cpp.

    {
        // the maps are thread-local so no concerns for data-race here since
        // two threads updating at once and subsequently losing once of the updates
        // still results in a unique id for that thread
        static uint64_t uniqID = 0;
        return uniqID++;
    }

timemory_init_library()

void timemory_init_library	(	int	argc,
		char **	argv
	)

Initializes timemory. Not strictly necessary but highly recommended.

Definition at line 212 of file library.cpp.

    {
        tim::trace::lock<tim::trace::library> lk{};
        if(get_library_state()[0])
            return;
        get_library_state()[0] = true;
 
        if(argc < 1 && argv)
            argc = 1;
        if(argv == nullptr)
        {
            argc = 0;
        }
        else
        {
            int i = 0;
            for(; i < argc; ++i)
            {
                if(argv[i] == nullptr)
                {
                    argc = i;
                    break;
                }
            }
        }
 
        if(tim::settings::verbose() > 0)
        {
            printf("%s\n", spacer.c_str());
            printf("\tInitialization of timemory library...\n");
            printf("%s\n\n", spacer.c_str());
        }
 
        if(argc > 0 && argv)
            tim::timemory_init(argc, argv);
        tim::manager::instance()->update_metadata_prefix();
        // tim::settings::parse();
    }

References tim::argv, get_library_state(), and tim::verbose.

Referenced by c_timemory_init(), timemory_init_library_(), timemory_named_init_library(), and timemory_trace_init().

timemory_is_throttled()

bool timemory_is_throttled

(

const char *

name

)

Definition at line 374 of file trace.cpp.

    {
        size_t _id = tim::get_hash_id(name);
        return (get_throttle()->count(_id) > 0);
    }

timemory_library_is_initialized()

bool timemory_library_is_initialized

(

void

)

Returns whether the library is initialized or not.

Definition at line 195 of file library.cpp.

{ return get_library_state()[0]; }

References get_library_state().

timemory_named_init_library()

void timemory_named_init_library

(

char *

name

)

Definition at line 200 of file library.cpp.

    {
        if(name)
        {
            char* _name[1] = { name };
            timemory_init_library(1, _name);
        }
    }

References timemory_init_library().

timemory_pause()

void timemory_pause

(

void

)

Turn off timemory collection.

Definition at line 313 of file library.cpp.

{ tim::settings::enabled() = false; }

References tim::enabled.

timemory_pop_components()

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.

Definition at line 399 of file library.cpp.

    {
        tim::trace::lock<tim::trace::library> lk{};
        static thread_local auto&             _stack = get_components_stack();
        if(_stack.size() > 1)
            _stack.pop_back();
    }

Referenced by timemory_pop_components_().

timemory_pop_region()

void timemory_pop_region

(

const char *

name

)

Parameters

[in]

name

label for region

Stops collection of components with label.

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

Definition at line 587 of file library.cpp.

    {
        tim::trace::lock<tim::trace::library> lk{};
        if(!lk)
            return;
        auto& region_map = get_region_map();
        auto  itr        = region_map.find(name);
        if(itr == region_map.end() || (itr != region_map.end() && itr->second.empty()))
            fprintf(stderr, "Warning! region '%s' does not exist!\n", name);
        else
        {
            uint64_t idx = itr->second.top();
            lk.release();
            timemory_end_record(idx);
            lk = tim::trace::lock<tim::trace::library>{};
            itr->second.pop();
        }
    }

Referenced by timemory_pop_region_().

timemory_pop_trace()

void timemory_pop_trace

(

const char *

name

)

Definition at line 632 of file trace.cpp.

    {
        uint64_t _hash = std::numeric_limits<uint64_t>::max();
        {
            tim::trace::lock<tim::trace::library> lk{};
            if(!get_library_state()[0] || get_library_state()[1])
                return;
            _hash = tim::get_hash_id(name);
        }
        timemory_pop_trace_hash(_hash);
    }

References get_library_state(), std::max(), and timemory_pop_trace_hash().

timemory_pop_trace_hash()

void timemory_pop_trace_hash

(

uint64_t

id

)

Definition at line 514 of file trace.cpp.

    {
        tim::trace::lock<tim::trace::library> lk{};
        if(!get_library_state()[0] || get_library_state()[1])
            return;
 
        auto& _trace_map = get_trace_map();
        if(!tim::settings::enabled() && _trace_map.empty())
        {
            if(tim::settings::debug() && _trace_map.empty())
                fprintf(stderr,
                        "[timemory-trace]> timemory_pop_trace_hash(%lu) failed. "
                        "trace_map empty...\n",
                        (unsigned long) id);
            return;
        }
 
        int64_t ntotal = _trace_map[id].size();
        int64_t offset = ntotal - 1;
 
        if(tim::settings::debug())
        {
            auto     itr  = tim::get_hash_ids()->find(id);
            string_t name = (itr != tim::get_hash_ids()->end()) ? itr->second : "unknown";
            fprintf(stderr,
                    "ending trace for '%s' (id = %llu, offset = %lli, rank = %i, pid = "
                    "%i, thread = %i)...\n",
                    name.c_str(), (long long unsigned) id, (long long int) offset,
                    tim::dmp::rank(), (int) tim::process::get_id(),
                    (int) tim::threading::get_id());
        }
 
        (*get_overhead())[id].first.stop();
 
        // if there were no entries, return (pop called without a push)
        if(offset < 0)
            return;
 
        if(offset >= 0 && ntotal > 0)
        {
            _trace_map[id].back().stop();
            _trace_map[id].pop_back();
        }
 
        if(get_throttle() && get_throttle()->count(id) > 0)
            return;
 
        auto _count = ++(get_overhead()->at(id).second);
 
        if(_count % tim::settings::throttle_count() == 0)
        {
            auto _accum = get_overhead()->at(id).first.get_accum() / _count;
            if(_accum < tim::settings::throttle_value())
            {
                if(tim::settings::debug() || tim::settings::verbose() > 0)
                {
                    auto name = tim::get_hash_ids()->find(id)->second;
                    fprintf(
                        stderr,
                        "[timemory-trace]> Throttling all future calls to '%s' on rank = "
                        "%i, pid = "
                        "%i, thread = %i. avg runtime = %lu ns from %lu invocations... "
                        "Consider eliminating from instrumentation...\n",
                        name.c_str(), tim::dmp::rank(), (int) tim::process::get_id(),
                        (int) tim::threading::get_id(), (unsigned long) _accum,
                        (unsigned long) _count);
                }
                get_throttle()->insert(id);
            }
            else
            {
                if(_accum < (10 * tim::settings::throttle_value()) &&
                   (tim::settings::debug() || tim::settings::verbose() > 1))
                {
                    auto name = tim::get_hash_ids()->find(id)->second;
                    fprintf(
                        stderr,
                        "[timemory-trace]> Warning! function call '%s' within an order "
                        "of magnitude of threshold for throttling value on rank = %i, "
                        "pid = "
                        "%i, thread = %i. avg runtime = %lu ns from %lu invocations... "
                        "Consider eliminating from instrumentation...\n",
                        name.c_str(), tim::dmp::rank(), (int) tim::process::get_id(),
                        (int) tim::threading::get_id(), (unsigned long) _accum,
                        (unsigned long) _count);
                }
            }
            get_overhead()->at(id).first.reset();
            get_overhead()->at(id).second = 0;
        }
    }

References get_library_state().

Referenced by timemory_pop_trace().

timemory_push_components()

void timemory_push_components

(

const char *

_component_string

)

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

timemory_push_components("priority_context_switch, read_bytes");

Definition at line 368 of file library.cpp.

    {
        tim::trace::lock<tim::trace::library> lk{};
        static thread_local auto&             _stack = get_components_stack();
        _stack.push_back(tim::enumerate_components(_component_string));
    }

Referenced by timemory_push_components_().

timemory_push_components_enum()

void timemory_push_components_enum	(	int	types,
			...
	)

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);

Definition at line 377 of file library.cpp.

    {
        tim::trace::lock<tim::trace::library> lk{};
        static thread_local auto&             _stack = get_components_stack();
 
        component_enum_t comp({ types });
        va_list          args;
        va_start(args, types);
        for(int i = 0; i < TIMEMORY_COMPONENTS_END; ++i)
        {
            auto enum_arg = va_arg(args, int);
            if(enum_arg >= TIMEMORY_COMPONENTS_END)
                break;
            comp.push_back(enum_arg);
        }
        va_end(args);
 
        _stack.push_back(comp);
    }

timemory_push_region()

void timemory_push_region

(

const char *

name

)

Parameters

[in]

name

label for region

Starts collection of components with label.

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

Definition at line 573 of file library.cpp.

    {
        tim::trace::lock<tim::trace::library> lk{};
        if(!lk)
            return;
        auto& region_map = get_region_map();
        lk.release();
        auto idx = timemory_get_begin_record(name);
        lk       = tim::trace::lock<tim::trace::library>{};
        region_map[name].push(idx);
    }

Referenced by timemory_push_region_().

timemory_push_trace()

void timemory_push_trace

(

const char *

name

)

Definition at line 608 of file trace.cpp.

    {
        if(!timemory_trace_is_initialized())
            timemory_trace_init("", true, "");
 
        uint64_t _hash = std::numeric_limits<uint64_t>::max();
        {
            tim::trace::lock<tim::trace::library> lk{};
            if(tim::settings::debug())
                PRINT_HERE("rank = %i, pid = %i, thread = %i, name = %s",
                           tim::dmp::rank(), (int) tim::process::get_id(),
                           (int) tim::threading::get_id(), name);
 
            if(!get_library_state()[0] || get_library_state()[1] ||
               !tim::settings::enabled())
                return;
 
            _hash = tim::add_hash_id(name);
        }
        timemory_push_trace_hash(_hash);
    }

References tim::debug, tim::enabled, get_library_state(), std::max(), PRINT_HERE, timemory_push_trace_hash(), timemory_trace_init(), and timemory_trace_is_initialized().

timemory_push_trace_hash()

void timemory_push_trace_hash

(

uint64_t

id

)

Definition at line 448 of file trace.cpp.

    {
        if(!timemory_trace_is_initialized())
            timemory_trace_init("", true, "");
 
        static thread_local auto _copied = (timemory_copy_hash_ids(), true);
        tim::consume_parameters(_copied);
 
        tim::trace::lock<tim::trace::library> lk{};
 
        if(!lk)
        {
#if defined(DEBUG) || !defined(NDEBUG)
            if(tim::settings::debug())
                PRINT_HERE("Tracing is locked: %s", (lk) ? "Y" : "N");
#endif
            return;
        }
 
        if(!get_library_state()[0] || get_library_state()[1] || !tim::settings::enabled())
        {
#if defined(DEBUG) || !defined(NDEBUG)
            if(tim::settings::debug())
                PRINT_HERE("Invalid library state: init = %s, fini = %s, enabled = %s",
                           (get_library_state()[0]) ? "Y" : "N",
                           (get_library_state()[1]) ? "Y" : "N",
                           (tim::settings::enabled()) ? "Y" : "N");
#endif
            return;
        }
 
        if(get_throttle()->count(id) > 0)
        {
#if defined(DEBUG) || !defined(NDEBUG)
            if(tim::settings::debug())
                PRINT_HERE("trace %llu is throttled", (unsigned long long) id);
#endif
            return;
        }
 
        auto& _trace_map = get_trace_map();
        auto& _overh_map = *get_overhead();
 
        if(tim::get_hash_ids()->find(id) == tim::get_hash_ids()->end())
            return;
 
        if(tim::settings::debug())
        {
            int64_t  n    = _trace_map[id].size();
            auto     itr  = tim::get_hash_ids()->find(id);
            string_t name = (itr != tim::get_hash_ids()->end()) ? itr->second : "unknown";
            fprintf(stderr,
                    "beginning trace for '%s' (id = %llu, offset = %lli, rank = %i, pid "
                    "= %i, thread = %i)...\n",
                    name.c_str(), (long long unsigned) id, (long long int) n,
                    tim::dmp::rank(), (int) tim::process::get_id(),
                    (int) tim::threading::get_id());
        }
 
        _trace_map[id].emplace_back(traceset_t{ id });
        _trace_map[id].back().start();
        _overh_map[id].first.start();
    }

References tim::consume_parameters(), tim::debug, tim::enabled, get_library_state(), PRINT_HERE, timemory_copy_hash_ids(), timemory_trace_init(), and timemory_trace_is_initialized().

Referenced by timemory_push_trace().

timemory_remove_components()

void timemory_remove_components

(

const char *

_component_string

)

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");

Definition at line 358 of file library.cpp.

    {
        tim::trace::lock<tim::trace::library> lk{};
        auto&                                 _stack = get_current_components();
        for(auto itr : tim::enumerate_components(_component_string))
            _stack.erase(std::remove(_stack.begin(), _stack.end(), itr), _stack.end());
    }

References tim::enumerate_components(), and get_current_components().

timemory_reset_throttle()

void timemory_reset_throttle

(

const char *

name

)

Definition at line 382 of file trace.cpp.

    {
        size_t _id = tim::get_hash_id(name);
        auto   itr = get_throttle()->find(_id);
        if(itr != get_throttle()->end())
            get_throttle()->erase(itr);
    }

timemory_resume()

void timemory_resume

(

void

)

Turn on timemory collection.

Definition at line 318 of file library.cpp.

{ tim::settings::enabled() = true; }

References tim::enabled.

timemory_set_default()

void timemory_set_default

(

const char *

_component_string

)

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");

Definition at line 322 of file library.cpp.

    {
        tim::trace::lock<tim::trace::library> lk{};
        get_default_components() =
            tim::get_env<std::string>("TIMEMORY_GLOBAL_COMPONENTS", _component_string);
        // tim::set_env("TIMEMORY_COMPONENTS", _component_string, 0);
        static thread_local auto& _stack = get_components_stack();
        if(_stack.empty())
            _stack.push_back(tim::enumerate_components(get_default_components()));
    }

References get_default_components().

Referenced by timemory_set_default_().

timemory_set_environ()

void timemory_set_environ	(	const char *	evar,
		const char *	eval,
		int	over,
		int	parse
	)

Parameters

[in]	evar	Environment variable name
[in]	eval	Environment variable value
[in]	ovr	Overwrite existing environment variable when > 0
[in]	up	Update settings when > 0

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);

Definition at line 335 of file library.cpp.

    {
        tim::trace::lock<tim::trace::library> lk{};
        if(evar && eval)
        {
            tim::set_env(evar, eval, over);
            if(parse > 0)
                tim::settings::parse();
        }
    }

References tim::settings::parse(), and tim::set_env().

timemory_trace_finalize()

void timemory_trace_finalize

(

void

)

Definition at line 808 of file trace.cpp.

    {
        tim::trace::lock<tim::trace::library> lk{};
        if(library_trace_count.load() == 0)
            return;
 
        auto  _manager  = tim::manager::master_instance();
        auto* _settings = tim::settings::instance();
        if(!_manager || !_settings)
            return;
 
        auto _debug = _settings->get_debug();
        if(_settings->get_verbose() > 1 || _settings->get_debug())
            PRINT_HERE("rank = %i, pid = %i, thread = %i", tim::dmp::rank(),
                       (int) tim::process::get_id(), (int) tim::threading::get_id());
 
        CONDITIONAL_PRINT_HERE(_debug, "%s", "getting count");
        // do the finalization
        auto _count = --library_trace_count;
 
        if(_count > 0)
        {
            CONDITIONAL_PRINT_HERE(_debug, "%s", "positive count");
            // have the manager finalize
            if(tim::manager::instance())
                tim::manager::instance()->finalize();
            CONDITIONAL_PRINT_HERE(_debug, "%s", "returning");
            return;
        }
 
        CONDITIONAL_PRINT_HERE(_debug, "%s", "secondary lock");
        tim::auto_lock_t lock(tim::type_mutex<TIMEMORY_API>());
 
        CONDITIONAL_PRINT_HERE(_debug, "%s", "setting state");
        // tim::settings::enabled() = false;
        get_library_state()[1] = true;
 
        CONDITIONAL_PRINT_HERE(_debug, "%s", "barrier");
        tim::mpi::barrier();
 
        CONDITIONAL_PRINT_HERE(_debug, "%s", "resetting");
        // reset traces just in case
        user_trace_bundle::reset();
 
        // if already finalized
        bool _skip_stop = false;
        if(!_manager || _manager->is_finalized())
            _skip_stop = true;
 
        // clean up any remaining entries
        if(!_skip_stop)
        {
            CONDITIONAL_PRINT_HERE(_debug, "%s", "cleaning trace map");
            for(auto& itr : get_trace_map())
            {
                for(auto& eitr : itr.second)
                    eitr.stop();
                // delete all the records
                itr.second.clear();
            }
            CONDITIONAL_PRINT_HERE(_debug, "%s", "clearing trace map");
            // delete all the records
            get_trace_map().clear();
        }
 
        CONDITIONAL_PRINT_HERE(_debug, "%s", "resetting mpi gotcha");
        // deactivate the gotcha wrappers
        if(use_mpi_gotcha)
            mpi_gotcha_handle.reset();
 
        CONDITIONAL_PRINT_HERE(_debug, "%s", "finalizing library");
        // finalize the library
        timemory_finalize_library();
 
        CONDITIONAL_PRINT_HERE(_debug, "%s", "finalized trace");
    }

timemory_trace_init()

void timemory_trace_init	(	const char *	comps,
		bool	read_command_line,
		const char *	cmd
	)

Definition at line 671 of file trace.cpp.

    {
        tim::trace::lock<tim::trace::library> lk{};
        if(!tim::manager::instance() || tim::manager::instance()->is_finalized())
            return;
 
        // configures the output path
        auto _configure_output_path = [&]() {
            static bool _performed_explicit = false;
            if(_performed_explicit || tim::settings::output_path() != "timemory-output")
                return;
            if(read_command_line)
            {
                auto _init = [](int _ac, char** _av) { timemory_init_library(_ac, _av); };
                tim::config::read_command_line(_init);
            }
            else
            {
                std::string exe_name = (cmd) ? cmd : "";
                if(!exe_name.empty())
                    _performed_explicit = true;
 
                while(exe_name.find('\\') != std::string::npos)
                    exe_name = exe_name.substr(exe_name.find_last_of('\\') + 1);
                while(exe_name.find('/') != std::string::npos)
                    exe_name = exe_name.substr(exe_name.find_last_of('/') + 1);
 
                static const std::vector<std::string> _exe_suffixes = { ".py", ".exe" };
                for(const auto& ext : _exe_suffixes)
                {
                    if(exe_name.find(ext) != std::string::npos)
                        exe_name.erase(exe_name.find(ext), ext.length() + 1);
                }
 
                exe_name = std::string("timemory-") + exe_name + "-output";
                for(auto& itr : exe_name)
                {
                    if(itr == '_')
                        itr = '-';
                }
 
                tim::settings::output_path() = exe_name;
            }
            if(tim::manager::instance())
                tim::manager::instance()->update_metadata_prefix();
        };
 
        // write the info about the rank/pid/thread/command
        auto _write_info = [&]() {
            std::stringstream _info;
            _info << "[timemory_trace_init]> ";
            if(tim::dmp::is_initialized())
                _info << "rank = " << tim::dmp::rank() << ", ";
            _info << "pid = " << tim::process::get_id() << ", ";
            _info << "tid = " << tim::threading::get_id();
            if(cmd && strlen(cmd) > 0)
                _info << ", command: " << cmd;
            if(comps && strlen(comps) > 0)
                _info << ", default components: " << comps;
            fprintf(stderr, "%s\n", _info.str().c_str());
        };
 
        // configures the tracing components
        auto _configure_components = [&]() {
            if(comps && strlen(comps) > 0)
            {
                _write_info();
                tim::set_env<std::string>("TIMEMORY_TRACE_COMPONENTS", comps, 0);
                if(tim::settings::trace_components().empty())
                    tim::settings::trace_components() = comps;
            }
 
            tim::settings::parse();
 
            // configure bundle
            user_trace_bundle::global_init(true);
            // tim::operation::init<user_trace_bundle>(
            //    tim::operation::mode_constant<tim::operation::init_mode::global>{});
        };
 
        if(!get_library_state()[0] && library_trace_count++ == 0)
        {
            _configure_components();
            _configure_output_path();
 
            tim::manager::use_exit_hook(false);
            get_library_state()[0] = true;
 
            auto _exit_action = [](int nsig) {
                auto _manager = tim::manager::master_instance();
                if(_manager && !_manager->is_finalized() && !_manager->is_finalizing())
                {
                    std::cout << "Finalizing after signal: " << nsig << " :: "
                              << tim::signal_settings::str(
                                     static_cast<tim::sys_signal>(nsig))
                              << std::endl;
                    timemory_trace_finalize();
                }
            };
            tim::signal_settings::set_exit_action(_exit_action);
            std::atexit(&timemory_trace_finalize);
#if !defined(TIMEMORY_MACOS)
            // Apple clang version 11.0.3 (clang-1103.0.32.62) doesn't seem to have this
            // function
            std::at_quick_exit(&tim::timemory_finalize);
#endif
 
#if defined(TIMEMORY_MPI_GOTCHA)
            if(!mpi_gotcha_handle.get())
            {
                mpi_gotcha_handle =
                    std::make_shared<mpi_trace_bundle_t>("timemory_trace_mpi_gotcha");
                mpi_trace_gotcha::get_trace_components() = comps;
                mpi_trace_gotcha::read_command_line()    = read_command_line;
                mpi_trace_gotcha::get_command()          = (cmd) ? cmd : "";
                if(mpi_is_attached)
                    mpi_trace_gotcha::set_attr();
                mpi_gotcha_handle->start();
            }
            else if(mpi_gotcha_handle.get())
            {
                tim::manager::instance()->update_metadata_prefix();
            }
#endif
        }
        else
        {
            if(tim::settings::debug())
                PRINT_HERE("trace already initialized: %s",
                           (get_library_state()[0]) ? "Y" : "N");
 
            _configure_components();
        }
    }

References tim::plotting::cmd, tim::exe_name, tim::manager::instance(), tim::output_path, tim::config::read_command_line(), and timemory_init_library().

Referenced by timemory_push_trace(), and timemory_push_trace_hash().

timemory_trace_is_initialized()

bool timemory_trace_is_initialized

(

void

)

Definition at line 366 of file trace.cpp.

    {
        return (get_library_state()[0] &&
                library_trace_count.load(std::memory_order_relaxed) > 0);
    }

References get_library_state().

Referenced by timemory_push_trace(), and timemory_push_trace_hash().

timemory_trace_set_env()

void timemory_trace_set_env	(	const char *	env_var,
		const char *	env_val
	)

Definition at line 658 of file trace.cpp.

    {
        tim::trace::lock<tim::trace::library> lk{};
        tim::set_env<std::string>(env_var, env_val, 0);
        if(get_library_state()[0])
        {
            tim::settings::parse();
            user_trace_bundle::global_init(true);
        }
    }

References get_library_state(), and tim::settings::parse().

Variable Documentation

timemory_create_function

timemory_create_func_t timemory_create_function

extern

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 ...
 
}

Definition at line 51 of file library.cpp.

Referenced by timemory_create_record().

timemory_delete_function

timemory_delete_func_t timemory_delete_function

extern

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 ...
 
}

Definition at line 52 of file library.cpp.

Referenced by timemory_delete_record().