gcc/ada/g-debpoo.ads

   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-2007, 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,  51  Franklin  Street,  Fifth  Floor, --
  20 -- Boston, MA 02110-1301, 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 or standard error.
  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 with System;                  use System;
  89 with System.Storage_Elements; use System.Storage_Elements;
  90 with System.Checked_Pools;
  91
  92 package GNAT.Debug_Pools is
  93
  94    type Debug_Pool is new System.Checked_Pools.Checked_Pool with private;
  95    --  The new debug pool
  96
  97    subtype SSC is System.Storage_Elements.Storage_Count;
  98
  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.
 111
 112    procedure Configure
 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.
 123    --
 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
 129    --
 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.
 134    --
 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.
 143    --
 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.
 147    --
 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.
 154    --
 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.
 160    --
 161    --    Errors_To_Stdout: Errors messages will be displayed on stdout if
 162    --    this parameter is True, or to stderr otherwise.
 163    --
 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
 170    --    pool.
 171    --
 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.
 175
 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.
 179
 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.
 183
 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.
 187
 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.
 191
 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.
 197
 198    generic
 199       with procedure Put_Line (S : String) is <>;
 200       with procedure Put      (S : String) is <>;
 201    procedure Print_Info
 202      (Pool          : Debug_Pool;
 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
 208    --  deallocated.
 209    --
 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
 214    --  defined order.
 215    --
 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).
 220    --
 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.
 226
 227    procedure Print_Info_Stdout
 228      (Pool          : Debug_Pool;
 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.
 235
 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.
 239    --
 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.
 243    --
 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.
 247
 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
 253    --  the Debug_Pool).
 254    --
 255    --  The information includes the stacktrace for the allocation or
 256    --  deallocation of that memory chunk, its current status (allocated or
 257    --  logically freed), etc.
 258
 259 private
 260    --  The following are the standard primitive subprograms for a pool
 261
 262    procedure Allocate
 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.
 270
 271    procedure Deallocate
 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
 279    --  in the RM.
 280
 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
 284    --  through the pool
 285
 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 dereference statement is valid, i.e. 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.
 296
 297    type Byte_Count is mod System.Max_Binary_Modulus;
 298    --  Type used for maintaining byte counts, needs to be large enough
 299    --  to accommodate counts allowing for repeated use of the same memory.
 300
 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;
 310
 311       Allocated : Byte_Count := 0;
 312       --  Total number of bytes allocated in this pool
 313
 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.
 319
 320       Physically_Deallocated : Byte_Count := 0;
 321       --  Total number of bytes that were free()-ed
 322
 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 dangerous, this is
 326       --  reported to the user, who might want to rerun his program with a
 327       --  lower Minimum_To_Free value.
 328
 329       High_Water : Byte_Count := 0;
 330       --  Maximum of Allocated - Logically_Deallocated - Physically_Deallocated
 331
 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
 335
 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
 341       --  freed.
 342    end record;
 343 end GNAT.Debug_Pools;