memtracker.h revision 2d1ce39e8bc6e75cadfc0a48ada30c52bc3eae0e
/** @file
* IPRT - Memory Tracker.
*/
/*
* Copyright (C) 2010 Oracle Corporation
*
* This file is part of VirtualBox Open Source Edition (OSE), as
* available from http://www.virtualbox.org. This file is free software;
* you can redistribute it and/or modify it under the terms of the GNU
* General Public License (GPL) as published by the Free Software
* Foundation, in version 2 as it comes in the "COPYING" file of the
* VirtualBox OSE distribution. VirtualBox OSE is distributed in the
* hope that it will be useful, but WITHOUT ANY WARRANTY of any kind.
*
* The contents of this file may alternatively be used under the terms
* of the Common Development and Distribution License Version 1.0
* (CDDL) only, as it comes in the "COPYING.CDDL" file of the
* VirtualBox OSE distribution, in which case the provisions of the
* CDDL are applicable instead of those of the GPL.
*
* You may elect to license modified versions of this file under the
* terms and conditions of either the GPL or the CDDL or both.
*/
#ifndef ___iprt_memtracker_h
#define ___iprt_memtracker_h
#include <iprt/cdefs.h>
#include <iprt/types.h>
#include <iprt/list.h>
RT_C_DECLS_BEGIN
/** @defgroup grp_rt_memtracker RTMemTracker - Memory Allocation Tracker.
* @ingroup grp_rt
* @{
*/
/**
* The allocation/free method.
*/
typedef enum RTMEMTRACKERMETHOD
{
RTMEMTRACKERMETHOD_INVALID = 0,
RTMEMTRACKERMETHOD_ALLOC,
RTMEMTRACKERMETHOD_ALLOCZ,
RTMEMTRACKERMETHOD_REALLOC,
RTMEMTRACKERMETHOD_FREE,
RTMEMTRACKERMETHOD_NEW,
RTMEMTRACKERMETHOD_NEW_ARRAY,
RTMEMTRACKERMETHOD_DELETE,
RTMEMTRACKERMETHOD_DELETE_ARRAY,
RTMEMTRACKERMETHOD_END,
RTMEMTRACKERMETHOD_32BIT_HACK = 0x7fffffff
} RTMEMTRACKERMETHOD;
/** Pointer to a tag structure. */
typedef struct RTMEMTRACKERTAG *PRTMEMTRACKERTAG;
/**
* Memory Tracking Header for use with RTMemTrackerHdrAlloc,
* RTMemTrackerHdrReallocPrep, RTMemTrackerHdrReallocDone and
* RTMemTrackerHdrFree.
*/
typedef struct RTMEMTRACKERHDR
{
/** Magic value / eye catcher (RTMEMTRACKERHDR_MAGIC). */
size_t uMagic;
/** The allocation size. */
size_t cbSize;
/** The list entry. */
RTLISTNODE ListEntry;
/** The tag string. */
const char *pszTag;
/** Pointer to the per-tag structure. */
PRTMEMTRACKERTAG pTag;
/** Alignmnet padding. */
void *pvAlignment[2];
} RTMEMTRACKERHDR;
/** Magic value for RTMEMTRACKERHDR::uMagic (Kelly Link). */
#if ARCH_BITS == 64
# define RTMEMTRACKERHDR_MAGIC UINT64_C(0x1907691919690719)
#else
# define RTMEMTRACKERHDR_MAGIC UINT32_C(0x19690719)
#endif
/**
* Initializes the allocation header and links it to the relevant tag.
*
* @returns Pointer to the user data part.
* @param pv The header + user data block. This must be at
* least @a cb + sizeof(RTMEMTRACKERHDR).
* @param cb The user data size (bytes).
* @param pszTag The tag string.
* @param enmMethod The method that the user called.
*/
RTDECL(void *) RTMemTrackerHdrAlloc(void *pv, size_t cb, const char *pszTag, RTMEMTRACKERMETHOD enmMethod);
/**
* Prepares for a realloc, i.e. invalidates the header.
*
* @returns Pointer to the user data part.
* @param pvOld Pointer to the old user data.
* @param cbOld The size of the old user data, 0 if not known.
* @param pszTag The tag string.
* @param enmMethod The method that the user called.
*/
RTDECL(void *) RTMemTrackerHdrReallocPrep(void *pvOld, size_t cbOld, const char *pszTag, RTMEMTRACKERMETHOD enmMethod);
/**
* Initializes the allocation header and links it to the relevant tag.
*
* @returns Pointer to the user data part.
* @param pvNew The new header + user data block. This must be
* at least @a cb + sizeof(RTMEMTRACKERHDR). If
* this is NULL, we assume the realloc() call
* failed.
* @param cbNew The user data size (bytes).
* @param pvOld Pointer to the old user data. This is only
* valid on failure of course and used to bail out
* in that case. Should not be NULL.
* @param pszTag The tag string.
* @param enmMethod The method that the user called.
*/
RTDECL(void *) RTMemTrackerHdrReallocDone(void *pvNew, size_t cbNew, void *pvOld, const char *pszTag, RTMEMTRACKERMETHOD enmMethod);
/**
* Do the accounting on free.
*
* @returns @a pv.
* @param pv Pointer to the user data.
* @param cb The size of the user data, 0 if not known.
* @param pszTag The tag string.
* @param enmMethod The method that the user called.
*/
RTDECL(void *) RTMemTrackerHdrFree(void *pv, size_t cb, const char *pszTag, RTMEMTRACKERMETHOD enmMethod);
/**
* Dumps all the allocations and tag statistics to the log.
*/
RTDECL(void) RTMemTrackerDumpAllToLog(void);
/**
* Dumps all the allocations and tag statistics to the release log.
*/
RTDECL(void) RTMemTrackerDumpAllToRelLog(void);
/**
* Dumps all the allocations and tag statistics to standard out.
*/
RTDECL(void) RTMemTrackerDumpAllToStdOut(void);
/**
* Dumps all the allocations and tag statistics to standard err.
*/
RTDECL(void) RTMemTrackerDumpAllToStdErr(void);
/**
* Dumps all the allocations and tag statistics to the specified filename.
*/
RTDECL(void) RTMemTrackerDumpAllToFile(const char *pszFilename);
/**
* Dumps all the tag statistics to the log.
*/
RTDECL(void) RTMemTrackerDumpStatsToLog(void);
/**
* Dumps all the tag statistics to the release log.
*/
RTDECL(void) RTMemTrackerDumpStatsToRelLog(void);
/**
* Dumps all the tag statistics to standard out.
*/
RTDECL(void) RTMemTrackerDumpStatsToStdOut(void);
/**
* Dumps all the tag statistics to standard err.
*/
RTDECL(void) RTMemTrackerDumpStatsToStdErr(void);
/**
* Dumps all the tag statistics to the specified filename.
*/
RTDECL(void) RTMemTrackerDumpStatsToFile(const char *pszFilename);
/** @} */
RT_C_DECLS_END
#endif