UT_MemoryTable.h

Go to the documentation of this file.

/*
 * PROPRIETARY INFORMATION.  This software is proprietary to
 * Side Effects Software Inc., and is not to be reproduced,
 * transmitted, or disclosed in any way without written permission.
 *
 * NAME:        UT_MemoryTable.h ( UT Library, C++)
 *
 * COMMENTS:    Memory tracking utilities
 */

#ifndef __UT_MemoryTable__
#define __UT_MemoryTable__

#include "UT_API.h"
#include <SYS/SYS_Types.h>
#include <SYS/SYS_Math.h>
#include <SYS/SYS_AtomicInt.h>
#include "UT_NonCopyable.h"
#include "UT_ThreadSpecificValue.h"

#include <cstddef>

/// Memory Tracking
///
/// This class provides a mechanism for tracking memory usage.  If all
/// memory allocation and freeing is registered with this class, then
/// the memory footprint and resource usage can be tracked.
///
/// There is a companion class at UT which allows for printing of the memory
/// statistics.
///
/// An example of how to use this might be:
///
/// enum {
///     MEM_DEBUG = 0,
///     MEM_TASK1,
///     MEM_TASK2,
///     MEM_MAX_TASKS
/// };
///
/// static UT_MemoryUser theMemoryUsers[MEM_MAX_TASKS] = {
///     UT_MemoryUser("Debug),
///     UT_MemoryUser("Task One"),
///     UT_MemoryUser("Task Two"),
/// };
///
/// static UT_MemoryTable       theMemoryTable(theMemoryUsers,
///                            sizeof(theMemoryUsers)/sizeof(UT_MemoryTable));
///
/// int
/// main(int argc, char *argv[])
///    {
///     UT_WorkBuffer    stats;
///     void            *mem;
///     mem = UT_Memory::Malloc(theMemoryTable, MEM_TASK1, 128);
///     mem = UT_Memory::Realloc(theMemoryTable, MEM_TASK1, mem, 128, 256);
///     UT_Memory::Free(theMemoryTable, MEM_TASK1, mem, 256);
///     UT_Memory::printTable(stats, theMemoryTable);
///     cout << stats.buffer();
///     return 0;
/// }
///

class UT_API UT_MemoryUser
    : public UT_NonCopyable
{
    struct Counter
    {
        Counter(bool atomic)
            : myUseAtomic(atomic)
        {
            set(0);
        }
        void            set(size_t amount)
        {
            if (myUseAtomic)
                myAtomic.exchange(amount);
            else
            {
                for (auto &val : myValue)
                {
                    val = amount;
                    amount = 0; // Clear all other values
                }
            }
        }
        size_t          get() const
        {
            if (myUseAtomic)
                return myAtomic.relaxedLoad();

            size_t  sum = 0;
            for (auto &val : myValue)
                sum += val;
            return sum;
        }
        size_t  add(size_t amount)
        {
            if (myUseAtomic)
                return myAtomic.add(amount);
            auto &val = myValue.get();
            val += amount;
            return val;
        }
        size_t  sub(size_t amount)
        {
            if (myUseAtomic)
                return myAtomic.add(-amount);
            auto &val = myValue.get();
            val -= amount;
            return val;
        }
        size_t  max(size_t amount)
        {
            if (myUseAtomic)
                return myAtomic.maximum(amount);
            auto &val = myValue.get();
            val = SYSmax(val, amount);
            return val;
        }
    private:
        SYS_AtomicCounter               myAtomic;
        UT_ThreadSpecificValue<size_t>  myValue;
        bool                            myUseAtomic;
    };

public:
    UT_MemoryUser(const char *label, bool use_atomics = false)
        : myUsed(use_atomics)
        , myPeak(use_atomics)
    {
        // WARNING:  The label is a reference to the string.  It's not hardened
        myLabel = label;
    }

    const char          *getLabel() const       { return myLabel; }

    /// Note that getUsed() and getPeak() may not be thread-safe unless
    /// initialized with @c use_atomics = true
    size_t               getUsed() const        { return myUsed.get(); }
    size_t               getPeak() const        { return myPeak.get(); }
    void                 inc(size_t amount)     { myPeak.max(myUsed.add(amount)); }
    void                 dec(size_t amount)     { myUsed.sub(amount); }

    /// Forcibly set values - not typical usage, but required in some cases
    void                 setUsedPeak(size_t used, size_t peak)
    {
        myUsed.set(used);
        myPeak.set(peak);
    }

private:
    const char  *myLabel;
    Counter      myUsed;
    Counter      myPeak;
};

class UT_API UT_MemoryTable
{
public:
    UT_MemoryTable(UT_MemoryUser *user_list, int number_of_users)
    {
        myTable = user_list;
        mySize = number_of_users;
    }

    UT_MemoryUser        &getUser(int index)       { return myTable[index]; }
    const UT_MemoryUser &getUser(int index) const { return myTable[index]; }

    int                  entries() const        { return mySize; }
    size_t               getUsed() const;
    size_t               getPeak() const;

    void                 inc(int user, size_t amount)
                         {
                             myTable[user].inc(amount);
                         }
    void                 dec(int user, size_t amount)
                         {
                             myTable[user].dec(amount);
                         }

private:
    UT_MemoryUser       *myTable;
    int                  mySize;
};

class UT_API UT_MemoryAPI
{
public:
    /// Allocate memory and track the usage.
    /// This method will return a null pointer if the size requested is equal
    /// to 0.
    static void *Malloc(UT_MemoryTable &table,
                        int which_entry,
                        size_t amount)
                 {
                     if (amount)
                     {
                         table.inc(which_entry, amount);
                         return malloc(amount);
                     }
                     return 0;
                 }
    /// Allocate memory and track the usage.  The memory will filled with zero.
    /// This method will return a null pointer if the size requested is equal
    /// to 0.
    static void *Calloc(UT_MemoryTable &table,
                        int which_entry,
                        size_t amount)
                 {
                     if (amount)
                     {
                         table.inc(which_entry, amount);
                         return calloc(1, amount);
                     }
                     return 0;
                 }
    /// Re-allocate a previously allocated block.  This method handles
    /// the case where the initial block has not been allocated (i.e. is a
    /// null pointer).
    /// This method will return a null pointer if the new_amount size requested
    /// is equal to 0.
    static void *Realloc(UT_MemoryTable &table,
                        int which_entry,
                        void *original_memory,
                        size_t old_amount,
                        size_t new_amount)
                {
                    void        *mem;
                    if (new_amount)
                    {
                        if (original_memory)
                        {
                            // Do it as two separate operations since size_t
                            // may be an unsigned and taking the delta may
                            // cause an overflow.
                            table.dec(which_entry, old_amount);
                            table.inc(which_entry, new_amount);
                            mem = realloc(original_memory, new_amount);
                        }
                        else
                        {
                            table.inc(which_entry, new_amount);
                            mem = malloc(new_amount);
                        }
                    }
                    else
                    {
                        mem = 0;
                        if (original_memory)
                        {
                            table.dec(which_entry, old_amount);
                            free(original_memory);
                        }
                    }
                    return mem;
                }

    /// Free an allocated block (tracking the memory usage).
    /// If a null pointer is passed in, no tracking will be done.  Thus, it's
    /// safe to pass in a non-zero size without a valid pointer (and not
    /// destroy the tracking process).
    static void  Free(UT_MemoryTable &table,
                        int which_entry,
                        void *memory,
                        size_t amount)
                 {
                     if (memory)
                     {
                         table.dec(which_entry, amount);
                         free(memory);
                     }
                 }

    /// Track a memory acquisition that wasn't performed by this class.
    static void  acquire(UT_MemoryTable &table,
                        int which_entry,
                        size_t amount)
                 {
                     table.inc(which_entry, amount);
                 }
    /// Track a memory free that wasn't performed by this class.
    static void  release(UT_MemoryTable &table,
                        int which_entry,
                        size_t amount)
                 {
                     table.dec(which_entry, amount);
                 }
};

/// When implementing in a different library, the following macro can be used
/// to implement a localized interface.  For example, we might have
///     UT_MEMORY_SUBCLASS(, GU, theGUMemoryTable)
/// or
///     class GU_Memory {
///     public:
///         UT_MEMORY_SUBCLASS(static, GU, myMemoryTable)
///     private:
///         static UT_MemoryTable       myMemoryTable;
///     };
///
#define UT_MEMORY_SUBCLASS(STATIC, prefix, table)               \
            STATIC void *prefix##Malloc(int i, size_t amount) \
                         { return UT_MemoryAPI::Malloc(table, i, amount); } \
            STATIC void *prefix##Calloc(int i, size_t amount) \
                         { return UT_MemoryAPI::Calloc(table, i, amount); } \
            STATIC void *prefix##Realloc(int i, void *m, size_t o, size_t n) \
                         { return UT_MemoryAPI::Realloc(table, i, m, o, n); } \
            STATIC void  prefix##Free(int i, void *m, size_t amount) \
                         { UT_MemoryAPI::Free(table, i, m, amount); } \
            STATIC void  prefix##acquire(int i, size_t amount) \
                         { UT_MemoryAPI::acquire(table, i, amount); } \
            STATIC void  prefix##release(int i, size_t amount) \
                         { UT_MemoryAPI::release(table, i, amount); } \
            static inline UT_MemoryTable &prefix##getTable() { return table; }

/// Convenience function to print memory in a consistent format (i.e. 12.3 KB).
/// To print "18446744073709551616.00 MB" requires 27 characters.  There are 5
/// extra characters for good measure in UT_MEMPRINTSIZE
#define UT_MEMPRINTSIZE 32
UT_API void     UTprintMemory(char buf[UT_MEMPRINTSIZE], int64 memory,
                                int field_width=-1);

#endif