1 ------------------------------------------------------------------------------
3 -- GNAT COMPILER COMPONENTS --
5 -- G N A T . D E B U G _ P O O L S --
9 -- Copyright (C) 1992-2007, 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, 51 Franklin Street, Fifth Floor, --
20 -- Boston, MA 02110-1301, 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 or standard error.
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
88 with System; use System;
89 with System.Storage_Elements; use System.Storage_Elements;
90 with System.Checked_Pools;
92 package GNAT.Debug_Pools is
94 type Debug_Pool is new System.Checked_Pools.Checked_Pool with private;
97 subtype SSC is System.Storage_Elements.Storage_Count;
99 Default_Max_Freed : constant SSC := 50_000_000;
100 Default_Stack_Trace_Depth : constant Natural := 20;
101 Default_Reset_Content : constant Boolean := False;
102 Default_Raise_Exceptions : constant Boolean := True;
103 Default_Advanced_Scanning : constant Boolean := False;
104 Default_Min_Freed : constant SSC := 0;
105 Default_Errors_To_Stdout : constant Boolean := True;
106 Default_Low_Level_Traces : constant Boolean := False;
107 -- The above values are constants used for the parameters to Configure
108 -- if not overridden in the call. See description of Configure for full
109 -- details on these parameters. If these defaults are not satisfactory,
110 -- then you need to call Configure to change the default values.
113 (Pool : in out Debug_Pool;
114 Stack_Trace_Depth : Natural := Default_Stack_Trace_Depth;
115 Maximum_Logically_Freed_Memory : SSC := Default_Max_Freed;
116 Minimum_To_Free : SSC := Default_Min_Freed;
117 Reset_Content_On_Free : Boolean := Default_Reset_Content;
118 Raise_Exceptions : Boolean := Default_Raise_Exceptions;
119 Advanced_Scanning : Boolean := Default_Advanced_Scanning;
120 Errors_To_Stdout : Boolean := Default_Errors_To_Stdout;
121 Low_Level_Traces : Boolean := Default_Low_Level_Traces);
122 -- Subprogram used to configure the debug pool.
124 -- Stack_Trace_Depth. This parameter controls the maximum depth of stack
125 -- traces that are output to indicate locations of actions for error
126 -- conditions such as bad allocations. If set to zero, the debug pool
127 -- will not try to compute backtraces. This is more efficient but gives
128 -- less information on problem locations
130 -- Maximum_Logically_Freed_Memory: maximum amount of memory (bytes)
131 -- that should be kept before starting to physically deallocate some.
132 -- This value should be non-zero, since having memory that is logically
133 -- but not physically freed helps to detect invalid memory accesses.
135 -- Minimum_To_Free is the minimum amount of memory that should be freed
136 -- every time the pool starts physically releasing memory. The algorithm
137 -- to compute which block should be physically released needs some
138 -- expensive initialization (see Advanced_Scanning below), and this
139 -- parameter can be used to limit the performance impact by ensuring
140 -- that a reasonable amount of memory is freed each time. Even in the
141 -- advanced scanning mode, marked blocks may be released to match this
142 -- Minimum_To_Free parameter.
144 -- Reset_Content_On_Free: If true, then the contents of the freed memory
145 -- is reset to the pattern 16#DEADBEEF#, following an old IBM convention.
146 -- This helps in detecting invalid memory references from the debugger.
148 -- Raise_Exceptions: If true, the exceptions below will be raised every
149 -- time an error is detected. If you set this to False, then the action
150 -- is to generate output on standard error or standard output, depending
151 -- on Errors_To_Stdout, noting the errors, but to
152 -- keep running if possible (of course if storage is badly damaged, this
153 -- attempt may fail. This helps to detect more than one error in a run.
155 -- Advanced_Scanning: If true, the pool will check the contents of all
156 -- allocated blocks before physically releasing memory. Any possible
157 -- reference to a logically free block will prevent its deallocation.
158 -- Note that this algorithm is approximate, and it is recommended
159 -- that you set Minimum_To_Free to a non-zero value to save time.
161 -- Errors_To_Stdout: Errors messages will be displayed on stdout if
162 -- this parameter is True, or to stderr otherwise.
164 -- Low_Level_Traces: Traces all allocation and deallocations on the
165 -- stream specified by Errors_To_Stdout. This can be used for
166 -- post-processing by your own application, or to debug the
167 -- debug_pool itself. The output indicates the size of the allocated
168 -- block both as requested by the application and as physically
169 -- allocated to fit the additional information needed by the debug
172 -- All instantiations of this pool use the same internal tables. However,
173 -- they do not store the same amount of information for the tracebacks,
174 -- and they have different counters for maximum logically freed memory.
176 Accessing_Not_Allocated_Storage : exception;
177 -- Exception raised if Raise_Exception is True, and an attempt is made
178 -- to access storage that was never allocated.
180 Accessing_Deallocated_Storage : exception;
181 -- Exception raised if Raise_Exception is True, and an attempt is made
182 -- to access storage that was allocated but has been deallocated.
184 Freeing_Not_Allocated_Storage : exception;
185 -- Exception raised if Raise_Exception is True, and an attempt is made
186 -- to free storage that had not been previously allocated.
188 Freeing_Deallocated_Storage : exception;
189 -- Exception raised if Raise_Exception is True, and an attempt is made
190 -- to free storage that had already been freed.
192 -- Note on the above exceptions. The distinction between not allocated
193 -- and deallocated storage is not guaranteed to be accurate in the case
194 -- where storage is allocated, and then physically freed. Larger values
195 -- of the parameter Maximum_Logically_Freed_Memory will help to guarantee
196 -- that this distinction is made more accurately.
199 with procedure Put_Line (S : String) is <>;
200 with procedure Put (S : String) is <>;
203 Cumulate : Boolean := False;
204 Display_Slots : Boolean := False;
205 Display_Leaks : Boolean := False);
206 -- Print out information about the High Water Mark, the current and
207 -- total number of bytes allocated and the total number of bytes
210 -- If Display_Slots is true, this subprogram prints a list of all the
211 -- locations in the application that have done at least one allocation or
212 -- deallocation. The result might be used to detect places in the program
213 -- where lots of allocations are taking place. This output is not in any
216 -- If Cumulate if True, then each stack trace will display the number of
217 -- allocations that were done either directly, or by the subprograms called
218 -- at that location (e.g: if there were two physical allocations at a->b->c
219 -- and a->b->d, then a->b would be reported as performing two allocations).
221 -- If Display_Leaks is true, then each block that has not been deallocated
222 -- (often called a "memory leak") will be listed, along with the traceback
223 -- showing where it was allocated. Not that no grouping of the blocks is
224 -- done, you should use the Dump_Gnatmem procedure below in conjunction
225 -- with the gnatmem utility.
227 procedure Print_Info_Stdout
229 Cumulate : Boolean := False;
230 Display_Slots : Boolean := False;
231 Display_Leaks : Boolean := False);
232 -- Standard instantiation of Print_Info to print on standard_output. More
233 -- convenient to use where this is the intended location, and in particular
234 -- easier to use from the debugger.
236 procedure Dump_Gnatmem (Pool : Debug_Pool; File_Name : String);
237 -- Create an external file on the disk, which can be processed by gnatmem
238 -- to display the location of memory leaks.
240 -- This provides a nicer output that Print_Info above, and groups similar
241 -- stack traces together. This also provides an easy way to save the memory
242 -- status of your program for post-mortem analysis.
244 -- To use this file, use the following command line:
245 -- gnatmem 5 -i <File_Name> <Executable_Name>
246 -- If you want all the stack traces to be displayed with 5 levels.
248 procedure Print_Pool (A : System.Address);
249 pragma Export (C, Print_Pool, "print_pool");
250 -- This subprogram is meant to be used from a debugger. Given an address in
251 -- memory, it will print on standard output the known information about
252 -- this address (provided, of course, the matching pointer is handled by
255 -- The information includes the stacktrace for the allocation or
256 -- deallocation of that memory chunck, its current status (allocated or
257 -- logically freed), etc.
260 -- The following are the standard primitive subprograms for a pool
263 (Pool : in out Debug_Pool;
264 Storage_Address : out Address;
265 Size_In_Storage_Elements : Storage_Count;
266 Alignment : Storage_Count);
267 -- Allocate a new chunk of memory, and set it up so that the debug pool
268 -- can check accesses to its data, and report incorrect access later on.
269 -- The parameters have the same semantics as defined in the ARM95.
272 (Pool : in out Debug_Pool;
273 Storage_Address : Address;
274 Size_In_Storage_Elements : Storage_Count;
275 Alignment : Storage_Count);
276 -- Mark a block of memory as invalid. It might not be physically removed
277 -- immediately, depending on the setup of the debug pool, so that checks
278 -- are still possible. The parameters have the same semantics as defined
281 function Storage_Size (Pool : Debug_Pool) return SSC;
282 -- Return the maximal size of data that can be allocated through Pool.
283 -- Since Pool uses the malloc() system call, all the memory is accessible
286 procedure Dereference
287 (Pool : in out Debug_Pool;
288 Storage_Address : System.Address;
289 Size_In_Storage_Elements : Storage_Count;
290 Alignment : Storage_Count);
291 -- Check whether a derefence statement is valid, ie whether the pointer
292 -- was allocated through Pool. As documented above, errors will be
293 -- reported either by a special error message or an exception, depending
294 -- on the setup of the storage pool.
295 -- The parameters have the same semantics as defined in the ARM95.
297 type Byte_Count is mod System.Max_Binary_Modulus;
298 -- Type used for maintaining byte counts, needs to be large enough
299 -- to accomodate counts allowing for repeated use of the same memory.
301 type Debug_Pool is new System.Checked_Pools.Checked_Pool with record
302 Stack_Trace_Depth : Natural := Default_Stack_Trace_Depth;
303 Maximum_Logically_Freed_Memory : SSC := Default_Max_Freed;
304 Reset_Content_On_Free : Boolean := Default_Reset_Content;
305 Raise_Exceptions : Boolean := Default_Raise_Exceptions;
306 Minimum_To_Free : SSC := Default_Min_Freed;
307 Advanced_Scanning : Boolean := Default_Advanced_Scanning;
308 Errors_To_Stdout : Boolean := Default_Errors_To_Stdout;
309 Low_Level_Traces : Boolean := Default_Low_Level_Traces;
311 Allocated : Byte_Count := 0;
312 -- Total number of bytes allocated in this pool
314 Logically_Deallocated : Byte_Count := 0;
315 -- Total number of bytes logically deallocated in this pool. This is the
316 -- memory that the application has released, but that the pool has not
317 -- yet physically released through a call to free(), to detect later
318 -- accessed to deallocated memory.
320 Physically_Deallocated : Byte_Count := 0;
321 -- Total number of bytes that were free()-ed
323 Marked_Blocks_Deallocated : Boolean := False;
324 -- Set to true if some mark blocks had to be deallocated in the advanced
325 -- scanning scheme. Since this is potentially dangereous, this is
326 -- reported to the user, who might want to rerun his program with a
327 -- lower Minimum_To_Free value.
329 High_Water : Byte_Count := 0;
330 -- Maximum of Allocated - Logically_Deallocated - Physically_Deallocated
332 First_Free_Block : System.Address := System.Null_Address;
333 Last_Free_Block : System.Address := System.Null_Address;
334 -- Pointers to the first and last logically freed blocks
336 First_Used_Block : System.Address := System.Null_Address;
337 -- Pointer to the list of currently allocated blocks. This list is
338 -- used to list the memory leaks in the application on exit, as well as
339 -- for the advanced freeing algorithms that needs to traverse all these
340 -- blocks to find possible references to the block being physically
343 end GNAT.Debug_Pools;
OSDN Git Service
