1 ------------------------------------------------------------------------------
3 -- GNAT COMPILER COMPONENTS --
5 -- G N A T . D E B U G _ P O O L S --
9 -- Copyright (C) 1992-2004 Free Software Foundation, Inc. --
11 -- GNAT is free software; you can redistribute it and/or modify it under --
12 -- terms of the GNU General Public License as published by the Free Soft- --
13 -- ware Foundation; either version 2, or (at your option) any later ver- --
14 -- sion. GNAT is distributed in the hope that it will be useful, but WITH- --
15 -- OUT ANY WARRANTY; without even the implied warranty of MERCHANTABILITY --
16 -- or FITNESS FOR A PARTICULAR PURPOSE. See the GNU General Public License --
17 -- for more details. You should have received a copy of the GNU General --
18 -- Public License distributed with GNAT; see file COPYING. If not, write --
19 -- to the Free Software Foundation, 59 Temple Place - Suite 330, Boston, --
20 -- MA 02111-1307, USA. --
22 -- As a special exception, if other files instantiate generics from this --
23 -- unit, or you link this unit with other files to produce an executable, --
24 -- this unit does not by itself cause the resulting executable to be --
25 -- covered by the GNU General Public License. This exception does not --
26 -- however invalidate any other reasons why the executable file might be --
27 -- covered by the GNU Public License. --
29 -- GNAT was originally developed by the GNAT team at New York University. --
30 -- Extensive contributions were provided by Ada Core Technologies Inc. --
32 ------------------------------------------------------------------------------
34 -- This packages provides a special implementation of the Ada95 storage pools.
36 -- The goal of this debug pool is to detect incorrect uses of memory
37 -- (multiple deallocations, access to invalid memory,...). Errors are reported
38 -- in one of two ways: either by immediately raising an exception, or by
39 -- printing a message on standard output.
41 -- You need to instrument your code to use this package: for each access type
42 -- you want to monitor, you need to add a clause similar to:
44 -- type Integer_Access is access Integer;
45 -- for Integer_Access'Storage_Pool use Pool;
47 -- where Pool is a tagged object declared with
49 -- Pool : GNAT.Debug_Pools.Debug_Pool;
51 -- This package was designed to be as efficient as possible, but still has an
52 -- impact on the performance of your code, which depends on the number of
53 -- allocations, deallocations and, somewhat less, dereferences that your
54 -- application performs.
56 -- For each faulty memory use, this debug pool will print several lines
57 -- of information, including things like the location where the memory
58 -- was initially allocated, the location where it was freed etc.
60 -- Physical allocations and deallocations are done through the usual system
61 -- calls. However, in order to provide proper checks, the debug pool will not
62 -- release the memory immediately. It keeps released memory around (the amount
63 -- kept around is configurable) so that it can distinguish between memory that
64 -- has not been allocated and memory that has been allocated but freed. This
65 -- also means that this memory cannot be reallocated, preventing what would
66 -- otherwise be a false indication that freed memory is now allocated.
68 -- In addition, this package presents several subprograms that help analyze
69 -- the behavior of your program, by reporting memory leaks, the total amount
70 -- of memory that was allocated. The pool is also designed to work correctly
71 -- in conjunction with gnatmem.
73 -- Finally, a subprogram Print_Pool is provided for use from the debugger.
78 -- Current limitation of this debug pool: if you use this debug pool for a
79 -- general access type ("access all"), the pool might report invalid
80 -- dereferences if the access object is pointing to another object on the
81 -- stack which was not allocated through a call to "new".
83 -- This debug pool will respect all alignments specified in your code, but
84 -- it does that by aligning all objects using Standard'Maximum_Alignment.
85 -- This allows faster checks, and limits the performance impact of using
89 with System
; use System
;
90 with System
.Storage_Elements
; use System
.Storage_Elements
;
91 with System
.Checked_Pools
;
93 package GNAT
.Debug_Pools
is
95 type Debug_Pool
is new System
.Checked_Pools
.Checked_Pool
with private;
98 subtype SSC
is System
.Storage_Elements
.Storage_Count
;
100 Default_Max_Freed
: constant SSC
:= 50_000_000
;
101 Default_Stack_Trace_Depth
: constant Natural := 20;
102 Default_Reset_Content
: constant Boolean := False;
103 Default_Raise_Exceptions
: constant Boolean := True;
104 Default_Advanced_Scanning
: constant Boolean := False;
105 Default_Min_Freed
: constant SSC
:= 0;
106 -- The above values are constants used for the parameters to Configure
107 -- if not overridden in the call. See description of Configure for full
108 -- details on these parameters. If these defaults are not satisfactory,
109 -- then you need to call Configure to change the default values.
112 (Pool
: in out Debug_Pool
;
113 Stack_Trace_Depth
: Natural := Default_Stack_Trace_Depth
;
114 Maximum_Logically_Freed_Memory
: SSC
:= Default_Max_Freed
;
115 Minimum_To_Free
: SSC
:= Default_Min_Freed
;
116 Reset_Content_On_Free
: Boolean := Default_Reset_Content
;
117 Raise_Exceptions
: Boolean := Default_Raise_Exceptions
;
118 Advanced_Scanning
: Boolean := Default_Advanced_Scanning
);
119 -- Subprogram used to configure the debug pool.
121 -- Stack_Trace_Depth. This parameter controls the maximum depth of stack
122 -- traces that are output to indicate locations of actions for error
123 -- conditions such as bad allocations. If set to zero, the debug pool
124 -- will not try to compute backtraces. This is more efficient but gives
125 -- less information on problem locations
127 -- Maximum_Logically_Freed_Memory: maximum amount of memory (bytes)
128 -- that should be kept before starting to physically deallocate some.
129 -- This value should be non-zero, since having memory that is logically
130 -- but not physically freed helps to detect invalid memory accesses.
132 -- Minimum_To_Free is the minimum amount of memory that should be freed
133 -- every time the pool starts physically releasing memory. The algorithm
134 -- to compute which block should be physically released needs some
135 -- expensive initialization (see Advanced_Scanning below), and this
136 -- parameter can be used to limit the performance impact by ensuring
137 -- that a reasonable amount of memory is freed each time. Even in the
138 -- advanced scanning mode, marked blocks may be released to match this
139 -- Minimum_To_Free parameter.
141 -- Reset_Content_On_Free: If true, then the contents of the freed memory
142 -- is reset to the pattern 16#DEADBEEF#, following an old IBM convention.
143 -- This helps in detecting invalid memory references from the debugger.
145 -- Raise_Exceptions: If true, the exceptions below will be raised every
146 -- time an error is detected. If you set this to False, then the action
147 -- is to generate output on standard error, noting the errors, but to
148 -- keep running if possible (of course if storage is badly damaged, this
149 -- attempt may fail. This helps to detect more than one error in a run.
151 -- Advanced_Scanning: If true, the pool will check the contents of all
152 -- allocated blocks before physically releasing memory. Any possible
153 -- reference to a logically free block will prevent its deallocation.
154 -- Note that this algorithm is approximate, and it is recommended
155 -- that you set Minimum_To_Free to a non-zero value to save time.
157 -- All instantiations of this pool use the same internal tables. However,
158 -- they do not store the same amount of information for the tracebacks,
159 -- and they have different counters for maximum logically freed memory.
161 Accessing_Not_Allocated_Storage
: exception;
162 -- Exception raised if Raise_Exception is True, and an attempt is made
163 -- to access storage that was never allocated.
165 Accessing_Deallocated_Storage
: exception;
166 -- Exception raised if Raise_Exception is True, and an attempt is made
167 -- to access storage that was allocated but has been deallocated.
169 Freeing_Not_Allocated_Storage
: exception;
170 -- Exception raised if Raise_Exception is True, and an attempt is made
171 -- to free storage that had not been previously allocated.
173 Freeing_Deallocated_Storage
: exception;
174 -- Exception raised if Raise_Exception is True, and an attempt is made
175 -- to free storage that had already been freed.
177 -- Note on the above exceptions. The distinction between not allocated
178 -- and deallocated storage is not guaranteed to be accurate in the case
179 -- where storage is allocated, and then physically freed. Larger values
180 -- of the parameter Maximum_Logically_Freed_Memory will help to guarantee
181 -- that this distinction is made more accurately.
184 with procedure Put_Line
(S
: String) is <>;
185 with procedure Put
(S
: String) is <>;
188 Cumulate
: Boolean := False;
189 Display_Slots
: Boolean := False;
190 Display_Leaks
: Boolean := False);
191 -- Print out information about the High Water Mark, the current and
192 -- total number of bytes allocated and the total number of bytes
195 -- If Display_Slots is true, this subprogram prints a list of all the
196 -- locations in the application that have done at least one allocation or
197 -- deallocation. The result might be used to detect places in the program
198 -- where lots of allocations are taking place. This output is not in any
201 -- If Cumulate if True, then each stack trace will display the number of
202 -- allocations that were done either directly, or by the subprograms called
203 -- at that location (e.g: if there were two physical allocations at a->b->c
204 -- and a->b->d, then a->b would be reported as performing two allocations).
206 -- If Display_Leaks is true, then each block that has not been deallocated
207 -- (often called a "memory leak") will be listed, along with the traceback
208 -- showing where it was allocated. Not that no grouping of the blocks is
209 -- done, you should use the Dump_Gnatmem procedure below in conjunction
210 -- with the gnatmem utility.
212 procedure Print_Info_Stdout
214 Cumulate
: Boolean := False;
215 Display_Slots
: Boolean := False;
216 Display_Leaks
: Boolean := False);
217 -- Standard instantiation of Print_Info to print on standard_output. More
218 -- convenient to use where this is the intended location, and in particular
219 -- easier to use from the debugger.
221 procedure Dump_Gnatmem
(Pool
: Debug_Pool
; File_Name
: String);
222 -- Create an external file on the disk, which can be processed by gnatmem
223 -- to display the location of memory leaks.
225 -- This provides a nicer output that Print_Info above, and groups similar
226 -- stack traces together. This also provides an easy way to save the memory
227 -- status of your program for post-mortem analysis.
229 -- To use this file, use the following command line:
230 -- gnatmem 5 -i <File_Name> <Executable_Name>
231 -- If you want all the stack traces to be displayed with 5 levels.
233 procedure Print_Pool
(A
: System
.Address
);
234 pragma Export
(C
, Print_Pool
, "print_pool");
235 -- This subprogram is meant to be used from a debugger. Given an address in
236 -- memory, it will print on standard output the known information about
237 -- this address (provided, of course, the matching pointer is handled by
240 -- The information includes the stacktrace for the allocation or
241 -- deallocation of that memory chunck, its current status (allocated or
242 -- logically freed), etc.
245 -- The following are the standard primitive subprograms for a pool
248 (Pool
: in out Debug_Pool
;
249 Storage_Address
: out Address
;
250 Size_In_Storage_Elements
: Storage_Count
;
251 Alignment
: Storage_Count
);
252 -- Allocate a new chunk of memory, and set it up so that the debug pool
253 -- can check accesses to its data, and report incorrect access later on.
254 -- The parameters have the same semantics as defined in the ARM95.
257 (Pool
: in out Debug_Pool
;
258 Storage_Address
: Address
;
259 Size_In_Storage_Elements
: Storage_Count
;
260 Alignment
: Storage_Count
);
261 -- Mark a block of memory as invalid. It might not be physically removed
262 -- immediately, depending on the setup of the debug pool, so that checks
263 -- are still possible. The parameters have the same semantics as defined
266 function Storage_Size
(Pool
: Debug_Pool
) return SSC
;
267 -- Return the maximal size of data that can be allocated through Pool.
268 -- Since Pool uses the malloc() system call, all the memory is accessible
271 procedure Dereference
272 (Pool
: in out Debug_Pool
;
273 Storage_Address
: System
.Address
;
274 Size_In_Storage_Elements
: Storage_Count
;
275 Alignment
: Storage_Count
);
276 -- Check whether a derefence statement is valid, ie whether the pointer
277 -- was allocated through Pool. As documented above, errors will be
278 -- reported either by a special error message or an exception, depending
279 -- on the setup of the storage pool.
280 -- The parameters have the same semantics as defined in the ARM95.
282 type Byte_Count
is mod System
.Max_Binary_Modulus
;
283 -- Type used for maintaining byte counts, needs to be large enough
284 -- to accomodate counts allowing for repeated use of the same memory.
286 type Debug_Pool
is new System
.Checked_Pools
.Checked_Pool
with record
287 Stack_Trace_Depth
: Natural := Default_Stack_Trace_Depth
;
288 Maximum_Logically_Freed_Memory
: SSC
:= Default_Max_Freed
;
289 Reset_Content_On_Free
: Boolean := Default_Reset_Content
;
290 Raise_Exceptions
: Boolean := Default_Raise_Exceptions
;
291 Minimum_To_Free
: SSC
:= Default_Min_Freed
;
292 Advanced_Scanning
: Boolean := Default_Advanced_Scanning
;
294 Allocated
: Byte_Count
:= 0;
295 -- Total number of bytes allocated in this pool
297 Logically_Deallocated
: Byte_Count
:= 0;
298 -- Total number of bytes logically deallocated in this pool. This is the
299 -- memory that the application has released, but that the pool has not
300 -- yet physically released through a call to free(), to detect later
301 -- accesed to deallocated memory.
303 Physically_Deallocated
: Byte_Count
:= 0;
304 -- Total number of bytes that were free()-ed.
306 Marked_Blocks_Deallocated
: Boolean := False;
307 -- Set to true if some mark blocks had to be deallocated in the advanced
308 -- scanning scheme. Since this is potentially dangereous, this is
309 -- reported to the user, who might want to rerun his program with a
310 -- lower Minimum_To_Free value.
312 High_Water
: Byte_Count
:= 0;
313 -- Maximum of Allocated - Logically_Deallocated - Physically_Deallocated
315 First_Free_Block
: System
.Address
:= System
.Null_Address
;
316 Last_Free_Block
: System
.Address
:= System
.Null_Address
;
317 -- Pointers to the first and last logically freed blocks.
319 First_Used_Block
: System
.Address
:= System
.Null_Address
;
320 -- Pointer to the list of currently allocated blocks. This list is
321 -- used to list the memory leaks in the application on exit, as well as
322 -- for the advanced freeing algorithms that needs to traverse all these
323 -- blocks to find possible references to the block being physically
326 end GNAT
.Debug_Pools
;