VirtualBox

source: vbox/trunk/include/iprt/memtracker.h@ 103224

Last change on this file since 103224 was 98103, checked in by vboxsync, 21 months ago

Copyright year updates by scm.

  • Property svn:eol-style set to native
  • Property svn:keywords set to Author Date Id Revision
File size: 8.5 KB
Line 
1/** @file
2 * IPRT - Memory Tracker.
3 */
4
5/*
6 * Copyright (C) 2010-2023 Oracle and/or its affiliates.
7 *
8 * This file is part of VirtualBox base platform packages, as
9 * available from https://www.virtualbox.org.
10 *
11 * This program is free software; you can redistribute it and/or
12 * modify it under the terms of the GNU General Public License
13 * as published by the Free Software Foundation, in version 3 of the
14 * License.
15 *
16 * This program is distributed in the hope that it will be useful, but
17 * WITHOUT ANY WARRANTY; without even the implied warranty of
18 * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU
19 * General Public License for more details.
20 *
21 * You should have received a copy of the GNU General Public License
22 * along with this program; if not, see <https://www.gnu.org/licenses>.
23 *
24 * The contents of this file may alternatively be used under the terms
25 * of the Common Development and Distribution License Version 1.0
26 * (CDDL), a copy of it is provided in the "COPYING.CDDL" file included
27 * in the VirtualBox distribution, in which case the provisions of the
28 * CDDL are applicable instead of those of the GPL.
29 *
30 * You may elect to license modified versions of this file under the
31 * terms and conditions of either the GPL or the CDDL or both.
32 *
33 * SPDX-License-Identifier: GPL-3.0-only OR CDDL-1.0
34 */
35
36#ifndef IPRT_INCLUDED_memtracker_h
37#define IPRT_INCLUDED_memtracker_h
38#ifndef RT_WITHOUT_PRAGMA_ONCE
39# pragma once
40#endif
41
42#include <iprt/cdefs.h>
43#include <iprt/types.h>
44#include <iprt/list.h>
45
46RT_C_DECLS_BEGIN
47
48/** @defgroup grp_rt_memtracker RTMemTracker - Memory Allocation Tracker.
49 * @ingroup grp_rt
50 * @{
51 */
52
53/**
54 * The allocation/free method.
55 */
56typedef enum RTMEMTRACKERMETHOD
57{
58 RTMEMTRACKERMETHOD_INVALID = 0,
59 RTMEMTRACKERMETHOD_ALLOC,
60 RTMEMTRACKERMETHOD_ALLOCZ,
61 RTMEMTRACKERMETHOD_REALLOC_PREP, /**< Internal, don't use. */
62 RTMEMTRACKERMETHOD_REALLOC_DONE, /**< Internal, don't use. */
63 RTMEMTRACKERMETHOD_REALLOC_FAILED, /**< Internal, don't use. */
64 RTMEMTRACKERMETHOD_FREE,
65
66 RTMEMTRACKERMETHOD_NEW,
67 RTMEMTRACKERMETHOD_NEW_ARRAY,
68 RTMEMTRACKERMETHOD_DELETE,
69 RTMEMTRACKERMETHOD_DELETE_ARRAY,
70 RTMEMTRACKERMETHOD_END,
71 RTMEMTRACKERMETHOD_32BIT_HACK = 0x7fffffff
72} RTMEMTRACKERMETHOD;
73
74/** Pointer to a tag structure. */
75typedef struct RTMEMTRACKERTAG *PRTMEMTRACKERTAG;
76
77/** Pointer to a user structure. */
78typedef struct RTMEMTRACKERUSER *PRTMEMTRACKERUSER;
79
80/**
81 * Memory Tracking Header for use with RTMemTrackerHdrAlloc,
82 * RTMemTrackerHdrReallocPrep, RTMemTrackerHdrReallocDone and
83 * RTMemTrackerHdrFree.
84 */
85typedef struct RTMEMTRACKERHDR
86{
87 /** Magic value / eye catcher (RTMEMTRACKERHDR_MAGIC). */
88 size_t uMagic;
89 /** The allocation size, user data only. */
90 size_t cbUser;
91 /** The list entry. */
92 RTLISTNODE ListEntry;
93 /** Pointer to the user structure where this header is linked. */
94 PRTMEMTRACKERUSER pUser;
95 /** Pointer to the per-tag structure. */
96 PRTMEMTRACKERTAG pTag;
97 /** The tag string. */
98 const char *pszTag;
99 /** The caller address. */
100 void *pvCaller;
101 /** Pointer to the user data we're tracking. */
102 void *pvUser;
103 /** Alignment padding. */
104 size_t uReserved;
105} RTMEMTRACKERHDR;
106/** Pointer to a memory tracker header. */
107typedef RTMEMTRACKERHDR *PRTMEMTRACKERHDR;
108/** Pointer to a const memory tracker header. */
109typedef RTMEMTRACKERHDR *PPRTMEMTRACKERHDR;
110
111/** Magic value for RTMEMTRACKERHDR::uMagic (Kelly Link). */
112#if ARCH_BITS == 64
113# define RTMEMTRACKERHDR_MAGIC UINT64_C(0x1907691919690719)
114#else
115# define RTMEMTRACKERHDR_MAGIC UINT32_C(0x19690719)
116#endif
117/** Magic number used when reallocated. */
118#if ARCH_BITS == 64
119# define RTMEMTRACKERHDR_MAGIC_REALLOC UINT64_C(0x0000691919690000)
120#else
121# define RTMEMTRACKERHDR_MAGIC_REALLOC UINT32_C(0x19690000)
122#endif
123/** Magic number used when freed. */
124#define RTMEMTRACKERHDR_MAGIC_FREE (~RTMEMTRACKERHDR_MAGIC)
125
126
127/**
128 * Initializes the allocation header and links it to the relevant tag.
129 *
130 * @returns Pointer to the user data part.
131 * @param pv The header + user data block. This must be at
132 * least @a cb + sizeof(RTMEMTRACKERHDR).
133 * @param cbUser The user data size (bytes).
134 * @param pszTag The tag string.
135 * @param pvCaller The return address.
136 * @param enmMethod The method that the user called.
137 */
138RTDECL(void *) RTMemTrackerHdrAlloc(void *pv, size_t cbUser, const char *pszTag, void *pvCaller, RTMEMTRACKERMETHOD enmMethod);
139
140/**
141 * Prepares for a realloc, i.e. invalidates the header.
142 *
143 * @returns Pointer to the user data part.
144 * @param pvOldUser Pointer to the old user data.
145 * @param cbOldUser The size of the old user data, 0 if not
146 * known.
147 * @param pszTag The tag string.
148 * @param pvCaller The return address.
149 */
150RTDECL(void *) RTMemTrackerHdrReallocPrep(void *pvOldUser, size_t cbOldUser, const char *pszTag, void *pvCaller);
151
152/**
153 * Initializes the allocation header and links it to the relevant tag.
154 *
155 * @returns Pointer to the user data part.
156 * @param pvNew The new header + user data block. This must be
157 * at least @a cb + sizeof(RTMEMTRACKERHDR). If
158 * this is NULL, we assume the realloc() call
159 * failed.
160 * @param cbNewUser The user data size (bytes).
161 * @param pvOldUser Pointer to the old user data. This is only
162 * valid on failure of course and used to bail out
163 * in that case. Should not be NULL.
164 * @param pszTag The tag string.
165 * @param pvCaller The return address.
166 */
167RTDECL(void *) RTMemTrackerHdrReallocDone(void *pvNew, size_t cbNewUser, void *pvOldUser, const char *pszTag, void *pvCaller);
168
169
170/**
171 * Do the accounting on free.
172 *
173 * @returns @a pv.
174 * @param pvUser Pointer to the user data.
175 * @param cbUser The size of the user data, 0 if not known.
176 * @param pszTag The tag string.
177 * @param pvCaller The return address.
178 * @param enmMethod The method that the user called.
179 */
180RTDECL(void *) RTMemTrackerHdrFree(void *pvUser, size_t cbUser, const char *pszTag, void *pvCaller, RTMEMTRACKERMETHOD enmMethod);
181
182
183/**
184 * Dumps all the allocations and tag statistics to the log.
185 */
186RTDECL(void) RTMemTrackerDumpAllToLog(void);
187
188/**
189 * Dumps all the allocations and tag statistics to the release log.
190 */
191RTDECL(void) RTMemTrackerDumpAllToLogRel(void);
192
193/**
194 * Dumps all the allocations and tag statistics to standard out.
195 */
196RTDECL(void) RTMemTrackerDumpAllToStdOut(void);
197
198/**
199 * Dumps all the allocations and tag statistics to standard err.
200 */
201RTDECL(void) RTMemTrackerDumpAllToStdErr(void);
202
203/**
204 * Dumps all the allocations and tag statistics to the specified filename.
205 */
206RTDECL(void) RTMemTrackerDumpAllToFile(const char *pszFilename);
207
208
209/**
210 * Dumps all the tag statistics to the log.
211 *
212 * @param fVerbose Whether to print all the stats or just the ones
213 * relevant to hunting leaks.
214 */
215RTDECL(void) RTMemTrackerDumpStatsToLog(bool fVerbose);
216
217/**
218 * Dumps all the tag statistics to the release log.
219 *
220 * @param fVerbose Whether to print all the stats or just the ones
221 * relevant to hunting leaks.
222 */
223RTDECL(void) RTMemTrackerDumpStatsToLogRel(bool fVerbose);
224
225/**
226 * Dumps all the tag statistics to standard out.
227 *
228 * @param fVerbose Whether to print all the stats or just the ones
229 * relevant to hunting leaks.
230 */
231RTDECL(void) RTMemTrackerDumpStatsToStdOut(bool fVerbose);
232
233/**
234 * Dumps all the tag statistics to standard err.
235 *
236 * @param fVerbose Whether to print all the stats or just the ones
237 * relevant to hunting leaks.
238 */
239RTDECL(void) RTMemTrackerDumpStatsToStdErr(bool fVerbose);
240
241/**
242 * Dumps all the tag statistics to the specified filename.
243 *
244 * @param fVerbose Whether to print all the stats or just the ones
245 * relevant to hunting leaks.
246 * @param pszFilename The name of the file to dump to.
247 */
248RTDECL(void) RTMemTrackerDumpStatsToFile(bool fVerbose, const char *pszFilename);
249
250
251
252/** @} */
253
254RT_C_DECLS_END
255
256#endif /* !IPRT_INCLUDED_memtracker_h */
257
Note: See TracBrowser for help on using the repository browser.

© 2024 Oracle Support Privacy / Do Not Sell My Info Terms of Use Trademark Policy Automated Access Etiquette