1------------------------------------------------------------------------------ 2-- -- 3-- GNAT COMPILER COMPONENTS -- 4-- -- 5-- G N A T . D E B U G _ P O O L S -- 6-- -- 7-- S p e c -- 8-- -- 9-- Copyright (C) 1992-2003 Free Software Foundation, Inc. -- 10-- -- 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. -- 21-- -- 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. -- 28-- -- 29-- GNAT was originally developed by the GNAT team at New York University. -- 30-- Extensive contributions were provided by Ada Core Technologies Inc. -- 31-- -- 32------------------------------------------------------------------------------ 33 34-- This packages provides a special implementation of the Ada95 storage pools. 35-- 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. 40-- 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: 43-- 44-- type Integer_Access is access Integer; 45-- for Integer_Access'Storage_Pool use Pool; 46 47-- where Pool is a tagged object declared with 48-- 49-- Pool : GNAT.Debug_Pools.Debug_Pool; 50-- 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. 55-- 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. 59-- 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. 67-- 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. 72-- 73-- Finally, a subprogram Print_Pool is provided for use from the debugger. 74-- 75-- Limitations 76-- =========== 77-- 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". 82-- 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 86-- this pool. 87-- 88 89with System; use System; 90with System.Storage_Elements; use System.Storage_Elements; 91with System.Checked_Pools; 92 93package GNAT.Debug_Pools is 94 95 type Debug_Pool is new System.Checked_Pools.Checked_Pool with private; 96 -- The new debug pool 97 98 subtype SSC is System.Storage_Elements.Storage_Count; 99 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. 110 111 procedure Configure 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. 120 -- 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 126 -- 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. 131 -- 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. 140 -- 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. 144 -- 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. 150 -- 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. 156 -- 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. 160 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. 164 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. 168 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. 172 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. 176 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. 182 183 generic 184 with procedure Put_Line (S : String) is <>; 185 with procedure Put (S : String) is <>; 186 procedure Print_Info 187 (Pool : Debug_Pool; 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 193 -- deallocated. 194 -- 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 199 -- defined order. 200 -- 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). 205 -- 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. 211 212 procedure Print_Info_Stdout 213 (Pool : Debug_Pool; 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. 220 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. 224 -- 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. 228 -- 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. 232 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 238 -- the Debug_Pool). 239 -- 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. 243 244private 245 -- The following are the standard primitive subprograms for a pool 246 247 procedure Allocate 248 (Pool : in out Debug_Pool; 249 Storage_Address : out Address; 250 Size_In_Storage_Elements : Storage_Count; 251 Alignment : Storage_Count); 252 253 procedure Deallocate 254 (Pool : in out Debug_Pool; 255 Storage_Address : Address; 256 Size_In_Storage_Elements : Storage_Count; 257 Alignment : Storage_Count); 258 259 function Storage_Size (Pool : Debug_Pool) return SSC; 260 261 procedure Dereference 262 (Pool : in out Debug_Pool; 263 Storage_Address : System.Address; 264 Size_In_Storage_Elements : Storage_Count; 265 Alignment : Storage_Count); 266 267 type Byte_Count is mod System.Max_Binary_Modulus; 268 -- Type used for maintaining byte counts, needs to be large enough 269 -- to accomodate counts allowing for repeated use of the same memory. 270 271 type Debug_Pool is new System.Checked_Pools.Checked_Pool with record 272 Stack_Trace_Depth : Natural := Default_Stack_Trace_Depth; 273 Maximum_Logically_Freed_Memory : SSC := Default_Max_Freed; 274 Reset_Content_On_Free : Boolean := Default_Reset_Content; 275 Raise_Exceptions : Boolean := Default_Raise_Exceptions; 276 Minimum_To_Free : SSC := Default_Min_Freed; 277 Advanced_Scanning : Boolean := Default_Advanced_Scanning; 278 279 Allocated : Byte_Count := 0; 280 -- Total number of bytes allocated in this pool 281 282 Logically_Deallocated : Byte_Count := 0; 283 -- Total number of bytes logically deallocated in this pool. This is the 284 -- memory that the application has released, but that the pool has not 285 -- yet physically released through a call to free(), to detect later 286 -- accesed to deallocated memory. 287 288 Physically_Deallocated : Byte_Count := 0; 289 -- Total number of bytes that were free()-ed. 290 291 Marked_Blocks_Deallocated : Boolean := False; 292 -- Set to true if some mark blocks had to be deallocated in the advanced 293 -- scanning scheme. Since this is potentially dangereous, this is 294 -- reported to the user, who might want to rerun his program with a 295 -- lower Minimum_To_Free value. 296 297 High_Water : Byte_Count := 0; 298 -- Maximum of Allocated - Logically_Deallocated - Physically_Deallocated 299 300 First_Free_Block : System.Address := System.Null_Address; 301 Last_Free_Block : System.Address := System.Null_Address; 302 -- Pointers to the first and last logically freed blocks. 303 304 First_Used_Block : System.Address := System.Null_Address; 305 -- Pointer to the list of currently allocated blocks. This list is 306 -- used to list the memory leaks in the application on exit, as well as 307 -- for the advanced freeing algorithms that needs to traverse all these 308 -- blocks to find possible references to the block being physically 309 -- freed. 310 end record; 311end GNAT.Debug_Pools; 312