This document is for a version of USD that is under development. See this page for the current release.
All Classes Namespaces Files Functions Variables Typedefs Enumerations Enumerator Friends Macros Modules Pages
TfMallocTag Class Reference

Top-down memory tagging system. More...

#include <mallocTag.h>

Classes

class  Auto
 Scoped (i.e. More...
 
struct  CallStackInfo
 This struct is used to represent a call stack taken for an allocation that was billed under a specific malloc tag. More...
 
struct  CallTree
 Summary data structure for malloc statistics. More...
 

Public Types

using Auto2 = Auto
 

Static Public Member Functions

static TF_API bool Initialize (std::string *errMsg)
 Initialize the memory tagging system.
 
static bool IsInitialized ()
 Return true if the tagging system is active.
 
static TF_API size_t GetTotalBytes ()
 Return total number of allocated bytes.
 
static TF_API size_t GetMaxTotalBytes ()
 Return the maximum total number of bytes that have ever been allocated at one time.
 
static TF_API bool GetCallTree (CallTree *tree, bool skipRepeated=true)
 Return a snapshot of memory usage.
 
static void Push (const std::string &name)
 Manually push a tag onto the stack.
 
static void Push (const char *name)
 This is an overloaded member function, provided for convenience. It differs from the above function only in what argument(s) it accepts.
 
static void Pop ()
 Manually pop a tag from the stack.
 
static TF_API void SetDebugMatchList (const std::string &matchList)
 Sets the tags to trap in the debugger.
 
static TF_API void SetCapturedMallocStacksMatchList (const std::string &matchList)
 Sets the tags to trace.
 
static TF_API std::vector< std::vector< uintptr_t > > GetCapturedMallocStacks ()
 Returns the captured malloc stack traces for allocations billed to the malloc tags passed to SetCapturedMallocStacksMatchList().
 

Friends

struct _TemporaryDisabler
 
class TfMallocTag::Auto
 
class TfMallocTag::Tls
 

Detailed Description

Top-down memory tagging system.

See The TfMallocTag Memory Tagging System for a detailed description.

Definition at line 33 of file mallocTag.h.


Class Documentation

◆ TfMallocTag::CallStackInfo

struct TfMallocTag::CallStackInfo

This struct is used to represent a call stack taken for an allocation that was billed under a specific malloc tag.

Definition at line 157 of file mallocTag.h.

Class Members
size_t numAllocations The number of allocations (always one unless stack frames have been combined to create unique stacks).
size_t size The amount of allocated memory (accumulated over all allocations sharing this call stack).
vector< uintptr_t > stack The stack frame pointers.

Member Typedef Documentation

◆ Auto2

using Auto2 = Auto

Definition at line 324 of file mallocTag.h.

Member Function Documentation

◆ GetCallTree()

static TF_API bool GetCallTree ( CallTree tree,
bool  skipRepeated = true 
)
static

Return a snapshot of memory usage.

Returns a snapshot by writing into *tree. See the C *tree structure for documentation. If Initialize() has not been called, \ *tree is set to a rather blank structure (empty vectors, empty strings, zero in all integral fields) and false is returned; otherwise, *tree is set with the contents of the current memory snapshot and true is returned. It is fine to call this function on the same *tree instance; each call simply overwrites the data from the last call. If /p skipRepeated is true, then any repeated callsite is skipped. See the CallTree documentation for more details.

◆ GetCapturedMallocStacks()

static TF_API std::vector< std::vector< uintptr_t > > GetCapturedMallocStacks ( )
static

Returns the captured malloc stack traces for allocations billed to the malloc tags passed to SetCapturedMallocStacksMatchList().

Note
This method also clears the internally held set of captured stacks.

◆ GetMaxTotalBytes()

static TF_API size_t GetMaxTotalBytes ( )
static

Return the maximum total number of bytes that have ever been allocated at one time.

This is simply the maximum value of GetTotalBytes() since Initialize() was called.

◆ GetTotalBytes()

static TF_API size_t GetTotalBytes ( )
static

Return total number of allocated bytes.

The current total memory that has been allocated and not freed is returned. Memory allocated before calling Initialize() is not accounted for.

◆ Initialize()

static TF_API bool Initialize ( std::string *  errMsg)
static

Initialize the memory tagging system.

This function returns true if the memory tagging system can be successfully initialized or it has already been initialized. Otherwise, *errMsg is set with an explanation for the failure.

Until the system is initialized, the various memory reporting calls will indicate that no memory has been allocated. Note also that memory allocated prior to calling Initialize() is not tracked i.e. all data refers to allocations that happen subsequent to calling Initialize().

◆ IsInitialized()

static bool IsInitialized ( )
inlinestatic

Return true if the tagging system is active.

If Initialize() has been successfully called, this function returns true.

Definition at line 188 of file mallocTag.h.

◆ Pop()

static void Pop ( )
inlinestatic

Manually pop a tag from the stack.

This call has the same effect as the destructor for TfMallocTag::Auto; it must properly nest with a matching call to Push(), of course.

Definition at line 349 of file mallocTag.h.

◆ Push() [1/2]

static void Push ( const char *  name)
inlinestatic

This is an overloaded member function, provided for convenience. It differs from the above function only in what argument(s) it accepts.

Definition at line 340 of file mallocTag.h.

◆ Push() [2/2]

static void Push ( const std::string &  name)
inlinestatic

Manually push a tag onto the stack.

This call has the same effect as the constructor for TfMallocTag::Auto (aka TfAutoMallocTag), however a matching call to Pop() is required.

Note that initializing the tagging system between matching calls to Push() and Pop() is ill-advised, which is yet another reason to prefer using TfAutoMallocTag whenever possible.

Definition at line 335 of file mallocTag.h.

◆ SetCapturedMallocStacksMatchList()

static TF_API void SetCapturedMallocStacksMatchList ( const std::string &  matchList)
static

Sets the tags to trace.

When memory is allocated for any tag that matches matchList a stack trace is recorded. When that memory is released the stack trace is discarded. Clients can call GetCapturedMallocStacks() to get a list of all recorded stack traces. This is useful for finding leaks.

Traces recorded for any tag that will no longer be matched are discarded by this call. Traces recorded for tags that continue to be matched are retained.

matchList is a comma, tab or newline separated list of malloc tag names. The names can have internal spaces but leading and trailing spaces are stripped. If a name ends in '*' then the suffix is wildcarded. A name can have a leading '-' or '+' to prevent or allow a match. Each name is considered in order and later matches override earlier matches. For example, 'Csd*, -CsdScene::_Populate*, +CsdScene::_PopulatePrimCacheLocal' matches any malloc tag starting with 'Csd' but nothing starting with 'CsdScene::_Populate' except 'CsdScene::_PopulatePrimCacheLocal'. Use the empty string to disable stack capturing.

◆ SetDebugMatchList()

static TF_API void SetDebugMatchList ( const std::string &  matchList)
static

Sets the tags to trap in the debugger.

When memory is allocated or freed for any tag that matches matchList the debugger trap is invoked. If a debugger is attached the program will stop in the debugger, otherwise the program will continue to run. See ArchDebuggerTrap() and ArchDebuggerWait().

matchList is a comma, tab or newline separated list of malloc tag names. The names can have internal spaces but leading and trailing spaces are stripped. If a name ends in '*' then the suffix is wildcarded. A name can have a leading '-' or '+' to prevent or allow a match. Each name is considered in order and later matches override earlier matches. For example, 'Csd*, -CsdScene::_Populate*, +CsdScene::_PopulatePrimCacheLocal' matches any malloc tag starting with 'Csd' but nothing starting with 'CsdScene::_Populate' except 'CsdScene::_PopulatePrimCacheLocal'. Use the empty string to disable debugging traps.

Friends And Related Function Documentation

◆ _TemporaryDisabler

friend struct _TemporaryDisabler
friend

Definition at line 405 of file mallocTag.h.

◆ TfMallocTag::Auto

friend class TfMallocTag::Auto
friend

Definition at line 427 of file mallocTag.h.

◆ TfMallocTag::Tls

friend class TfMallocTag::Tls
friend

Definition at line 429 of file mallocTag.h.


The documentation for this class was generated from the following file: