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.
To build for use with GLibC (PTMalloc2):
prompt% make
To build for use with JEMalloc:
prompt% make jem
To test with GLibC:
prompt% make test
To test with JEMalloc:
prompt% make test.jem
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.
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.]
Under TCSH:
prompt% env LD_PRELOAD=/path/to/asmalloc.so my_executable
Under BASH:
prompt$ export LD_PRELOAD=/path/to/asmalloc.so my_executable
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
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.
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.