faux/lub/heap/context.h

/* 
 * context.h 
 */
/**********************************************************
 * CONTEXT CLASS DEFINITIONS
 ********************************************************** */
#define MAX_BACKTRACE (32)

typedef struct _lub_heap_stackframe lub_heap_context_key_t;
typedef void (function_t)(void);

struct _lub_heap_stackframe
{
    function_t * backtrace[MAX_BACKTRACE];
};

typedef struct _lub_heap_leak_stats lub_heap_leak_stats_t;
struct _lub_heap_leak_stats
{
    size_t contexts;
    size_t allocs;
    size_t alloc_bytes;
    size_t alloc_overhead;
    size_t leaks;
    size_t leaked_bytes;
    size_t leaked_overhead;
    size_t partials;
    size_t partial_bytes;
    size_t partial_overhead;
    size_t scanned;
};

struct _lub_heap_context
{
    /**
     * The heap to which this context belongs
     */
    lub_heap_t *heap;
    /**
     * This is needed to maintain a tree of contexts
     */
    lub_bintree_node_t bt_node;
    /**
     * The first node in this context
     */
     lub_heap_node_t *first_node;
    /**
     * current number of allocations made from this context
     */
    size_t allocs;
    /**
     * current number of bytes allocated from this context
     */
    size_t alloc_bytes;
    /**
     * current overhead in bytes allocated from this context
     */
    size_t alloc_overhead;
    /**
     * count of leaked allocations made from this context
     */
    size_t leaks;
    /**
     * number of leaked bytes from this context
     */
    size_t leaked_bytes;
    /**
     * current overhead in bytes leaked from this context
     */
    size_t leaked_overhead;
    /**
     * count of partially leaked allocations made from this context
     */
    size_t partials;
    /**
     * number of partially leaked bytes from this context
     */
    size_t partial_bytes;
    /**
     * current overhead in bytes partially leaked from this context
     */
    size_t partial_overhead;
    /**
     * a record of the memory partition associated with this context
     */
    lub_heap_context_key_t key;
};

extern unsigned long lub_heap_frame_count;

typedef struct _lub_heap_leak lub_heap_leak_t;
struct _lub_heap_leak
{
    lub_bintree_t         m_context_tree;
    lub_bintree_t         m_node_tree;
    lub_bintree_t         m_clear_node_tree;
    lub_bintree_t         m_segment_tree;
    lub_heap_leak_stats_t m_stats;
    lub_dblockpool_t      m_context_pool;
    lub_heap_t           *m_heap_list;
};

extern lub_heap_leak_t *
    lub_heap_leak_instance(void);

extern void
    lub_heap_leak_release(lub_heap_leak_t *instance);

extern bool_t
    lub_heap_leak_query_node_tree(void);

extern bool_t
    lub_heap_leak_query_clear_node_tree(void);
/*---------------------------------------------------------
 * PUBLIC META ATTRIBUTES
 *--------------------------------------------------------- */
/**
 * Obtains the number of bytes required to allocate a context instance.
 *
 * By default this is set to four.
 */
size_t
    lub_heap_context__get_instanceSize(void);

extern lub_bintree_compare_fn lub_heap_context_compare;
extern lub_bintree_getkey_fn  lub_heap_context_getkey;

/*---------------------------------------------------------
 * PUBLIC METHODS
 *--------------------------------------------------------- */
/**
 * This function finds or creates a context based on the
 * provided leak detector and stack specification.
 * 
 * A context is defined by a pre-configured number of stack frames
 * (see lub_heap_context__set_frameCount()) 
 * All memory allocations which occur with 
 * the same stack frames will be collected together in the same context.
 *
 * \return Pointer to a context object or NULL if one cannot be found or allocated.
 */ 
 const lub_heap_context_t *
    lub_heap_context_find_or_create(
        /** 
         * The heap in question
         */
        lub_heap_t *instance,
        /** 
         * The memory allocation function must allocate a
         * local variable, on it's stack, which is passed in 
         * to this call as a means of getting access to the current
         * thread's call stack.
         */
        const stackframe_t * stack
    );
/**
 * This function finds a context based on the
 * provided leak detector and stack specification.
 * 
 * A context is defined by a pre-configured number of stack frames
 * (see lub_heap_context__set_frameCount()) 
 * All memory allocations which occur with 
 * the same stack frames will be collected together in the same context.
 *
 * \return Pointer to a context object or NULL if one cannot be found.
 */ 
lub_heap_context_t *
    lub_heap_context_find(
        /** 
         * The memory allocation function must allocate a
         * local variable, on it's stack, which is passed in 
         * to this call as a means of getting access to the current
         * thread's call stack.
         */
        const stackframe_t * stack
    );
    
/*---------------------------------------------------------
 * PUBLIC METHODS
 *--------------------------------------------------------- */
/**
 * This function initialises an instance of a context.
 */
void
    lub_heap_context_init(
        /** 
         * Context instance on which to operate
         */
        lub_heap_context_t *instance,
        /** 
         * heap with with to associate this context
         */
        lub_heap_t *heap,
        /**
         * The memory allocation function must allocate a
         * local variable, on it's stack, which is passed in 
         * to this call as a means of getting access to the current
         * thread's call stack.
         */
        const stackframe_t * stack
    );
/**
 * This function finalises an instance of a context.
 * 
 * \return the memory partition from which this context was allocated.
 */
void
    lub_heap_context_fini(
        /** 
         * Context instance on which to operate
         */
        lub_heap_context_t *instance
    );
/**
 * This function deletes an instance of a context
 * 
 * \return BOOL_TRUE if deletion was sucessful
 */
bool_t
    lub_heap_context_delete(
        /** 
         * Context instance on which to operate
         */
        lub_heap_context_t *instance
    );
/**
 * This function adds the specified node to the context tree.
 *
 * \return BOOL_TRUE  if the node was added to the tree,
 *          BOOL_FALSE if node was already in the tree.
 */
bool_t
    lub_heap_context_add_node(
        /** 
         * Context instance on which to operate
         */
        lub_heap_context_t *instance,
        /**
         * The node to add to this context 
         */
         lub_heap_node_t *node,
        /**
         * The size in bytes of the allocation 
         */
         size_t size
    );
/**
 * This function removes the specified node from the context tree.
 *
 * \return BOOL_TRUE  if the node was found and removed,
 *          BOOL_FALSE if the node was not in the tree
 */ 
void
    lub_heap_context_remove_node(
        /** 
         * Context instance on which to operate
         */
        lub_heap_context_t *instance,
        /**
         * The node to add to this context 
         */
         lub_heap_node_t *node
    );
/**
 * This function dumps details of the specified context to stdout
 *
 * /return
 * - BOOL_TRUE if any details were dumped.
 * - BOOL_FALSE if no details were dumped.
 */ 
bool_t 
    lub_heap_context_show(
        /** 
         * Context instance on which to operate
         */
        lub_heap_context_t *instance,
        /** 
         * How to dump the information
         */
        lub_heap_show_e how
    );
/**
 * This function "clears" the currently allocated blocks so that lub_heap_context_dump
 * will not show them
 */ 
void 
    lub_heap_context_clear(
        /** 
         * Context instance on which to operate
         */
        lub_heap_context_t *instance
    );
/**
 * This places a node into the context's tree
 */
 void
    lub_heap_context_insert_node(
        lub_heap_context_t * instance,
        lub_heap_node_t * node
    );
/*---------------------------------------------------------
 * PUBLIC ATTRIBUTES
 *--------------------------------------------------------- */
/**
 * Identify whether this is a valid address within the heap
 */
 bool_t
    leaks_is_valid_heap_address(lub_heap_t *instance,
                                const void *ptr);

void
    lub_heap_leak_mutex_lock(void);
void
    lub_heap_leak_mutex_unlock(void);