ASMalloc: Memory Allocation Tracking

This repository provides a safe and efficient means to track dynamic memory usage in programs using an implementation of the standard C library malloc(3) / free(3) interface and is useful for locating and eliminating memory leaks.

Build

To build for use with GLibC (PTMalloc2):

prompt% make

To build for use with JEMalloc:

prompt% make jem

Test

To test with GLibC:

prompt% make test

To test with JEMalloc:

prompt% make test.jem

Clean

To clean GLibC {JEMalloc} build products:

prompt% make clean{.jem}           -- Remove objects.

prompt% make cleaner{.jem}         -- Remove the above plus programs.

prompt% make cleanest{.jem}        -- Remove the above plus library.

Application Integration

ASMalloc can be used to a very basic level without any modifications to the application. Using more advanced features requires integration of the application with the ASMalloc API.

The output of ASMalloc will be logged to stderr.

To execute my_executable with ASMalloc, use the LD_PRELOAD environment variable:

[Note: Because they have slightly different needs, there are separate builds for the GLibC-compatible (lib/asmalloc.so) and JEMalloc-compatible (lib/asmalloc.jem.so) versions of the ASMalloc shared library.]

With GLibC (PTMalloc2):

Under TCSH:

prompt% env LD_PRELOAD=/path/to/asmalloc.so my_executable

Under BASH:

prompt$ export LD_PRELOAD=/path/to/asmalloc.so my_executable

With JEMalloc:

Under TCSH:

prompt% env LD_PRELOAD=/path/to/asmalloc.jem.so:/path/to/libjemalloc.so my_executable

Under BASH:

prompt$ export LD_PRELOAD=/path/to/asmalloc.jem.so:/path/to/libjemalloc.so my_executable

ASMalloc API:

The ASMalloc API, declared in the file include/asmalloc.h, is as follows:

/*
 *  Library-exported version of the hook function.
 */
int asm_hook(void *arg, asm_stats_t **asm_stats, vm_stats_t **vm_stats);

/*
 *  Library-exported version of the command function.
 */
int asm_cmd(asm_cmd_t cmd, va_list args);

/*
 *  Store the type and location of a mallocation in thread-specific storage.
 */
void asm_mallocation_set(uint16_t type, uint16_t loc, ssize_t delta_size);

/*
 *  Return the type and location of a mallocation in thread-specific storage.
 */
void asm_mallocation_get(uint16_t *type, uint16_t loc, ssize_t *total_size, ssize_t *delta_size, struct timespec *last_time);

The following commands are available to be sent via as_cmd():

ASM_CMD_SET_FEATURES   -- Set the bit vector of ASMalloc features.
ASM_CMD_SET_THRESHOLDS -- The the triplet of callback-triggering thresholds.
ASM_CMD_SET_CALLBACK   -- Set the user's callback.
ASM_CMD_PRINT_STATS    -- Print memory statistics.

The following independent features are available to be combined using the bitwise OR operator ("|") and sent as the argument to the ASM_CMD_SET_FEATURES command:

ASM_LOG_DATESTAMP       -- Log the current date and time.
ASM_LOG_THREAD_STATS    -- Log thread statistics.
ASM_LOG_MEM_COUNT_STATS -- Log memory count statistics.
ASM_LOG_MALLOCATIONS    -- Invoke callback on delta mallocations of sufficient size.
ASM_LOG_BLOCKS          -- Invoke callback on block allocations of sufficient size.
ASM_LOG_MALLOC_INFO     -- Log GLibC "malloc_info()" output.
ASM_LOG_MALLOC_STATS    -- Log GLibC "malloc_stats()" output.
ASM_LOG_MALLINFO        -- Log GLibC "mallinfo()" output.
ASM_LOG_VM_STATS        -- Log the process' Virtual Memory (VM) statistics.

Sample Application Integration:

Please see the src/test-asmalloc.c program for an example of how to integrate an application with ASMalloc.

Note that the the file include/test-mallocations.h is sample database of (fictitious) memory allocation function call locations in the application. This file defines types and a statically-initialized table giving the info. about each memory allocation-related function call in the application source code. Ideally, the actual table would be automatically re-generated whenever the application source code is modified.