-- --
-- S p e c --
-- --
--- Copyright (C) 1992-2005 Free Software Foundation, Inc. --
+-- Copyright (C) 1992-2011, Free Software Foundation, Inc. --
-- --
-- GNAT is free software; you can redistribute it and/or modify it under --
-- terms of the GNU General Public License as published by the Free Soft- --
--- ware Foundation; either version 2, or (at your option) any later ver- --
+-- ware Foundation; either version 3, or (at your option) any later ver- --
-- sion. GNAT is distributed in the hope that it will be useful, but WITH- --
-- OUT ANY WARRANTY; without even the implied warranty of MERCHANTABILITY --
--- or FITNESS FOR A PARTICULAR PURPOSE. See the GNU General Public License --
--- for more details. You should have received a copy of the GNU General --
--- Public License distributed with GNAT; see file COPYING. If not, write --
--- to the Free Software Foundation, 51 Franklin Street, Fifth Floor, --
--- Boston, MA 02110-1301, USA. --
+-- or FITNESS FOR A PARTICULAR PURPOSE. --
-- --
--- As a special exception, if other files instantiate generics from this --
--- unit, or you link this unit with other files to produce an executable, --
--- this unit does not by itself cause the resulting executable to be --
--- covered by the GNU General Public License. This exception does not --
--- however invalidate any other reasons why the executable file might be --
--- covered by the GNU Public License. --
+-- As a special exception under Section 7 of GPL version 3, you are granted --
+-- additional permissions described in the GCC Runtime Library Exception, --
+-- version 3.1, as published by the Free Software Foundation. --
+-- --
+-- You should have received a copy of the GNU General Public License and --
+-- a copy of the GCC Runtime Library Exception along with this program; --
+-- see the files COPYING3 and COPYING.RUNTIME respectively. If not, see --
+-- <http://www.gnu.org/licenses/>. --
-- --
-- GNAT was originally developed by the GNAT team at New York University. --
-- Extensive contributions were provided by Ada Core Technologies Inc. --
-- --
------------------------------------------------------------------------------
--- This packages provides a special implementation of the Ada95 storage pools.
+-- This packages provides a special implementation of the Ada 95 storage pools
-- The goal of this debug pool is to detect incorrect uses of memory
-- (multiple deallocations, access to invalid memory,...). Errors are reported
-- in one of two ways: either by immediately raising an exception, or by
--- printing a message on standard output.
+-- printing a message on standard output or standard error.
-- You need to instrument your code to use this package: for each access type
-- you want to monitor, you need to add a clause similar to:
-- of memory that was allocated. The pool is also designed to work correctly
-- in conjunction with gnatmem.
--- Finally, a subprogram Print_Pool is provided for use from the debugger.
+-- Finally, a subprogram Print_Pool is provided for use from the debugger
-- Limitations
-- ===========
Default_Raise_Exceptions : constant Boolean := True;
Default_Advanced_Scanning : constant Boolean := False;
Default_Min_Freed : constant SSC := 0;
+ Default_Errors_To_Stdout : constant Boolean := True;
+ Default_Low_Level_Traces : constant Boolean := False;
-- The above values are constants used for the parameters to Configure
-- if not overridden in the call. See description of Configure for full
-- details on these parameters. If these defaults are not satisfactory,
Minimum_To_Free : SSC := Default_Min_Freed;
Reset_Content_On_Free : Boolean := Default_Reset_Content;
Raise_Exceptions : Boolean := Default_Raise_Exceptions;
- Advanced_Scanning : Boolean := Default_Advanced_Scanning);
+ Advanced_Scanning : Boolean := Default_Advanced_Scanning;
+ Errors_To_Stdout : Boolean := Default_Errors_To_Stdout;
+ Low_Level_Traces : Boolean := Default_Low_Level_Traces);
-- Subprogram used to configure the debug pool.
--
-- Stack_Trace_Depth. This parameter controls the maximum depth of stack
--
-- Raise_Exceptions: If true, the exceptions below will be raised every
-- time an error is detected. If you set this to False, then the action
- -- is to generate output on standard error, noting the errors, but to
+ -- is to generate output on standard error or standard output, depending
+ -- on Errors_To_Stdout, noting the errors, but to
-- keep running if possible (of course if storage is badly damaged, this
-- attempt may fail. This helps to detect more than one error in a run.
--
-- Note that this algorithm is approximate, and it is recommended
-- that you set Minimum_To_Free to a non-zero value to save time.
--
+ -- Errors_To_Stdout: Errors messages will be displayed on stdout if
+ -- this parameter is True, or to stderr otherwise.
+ --
+ -- Low_Level_Traces: Traces all allocation and deallocations on the
+ -- stream specified by Errors_To_Stdout. This can be used for
+ -- post-processing by your own application, or to debug the
+ -- debug_pool itself. The output indicates the size of the allocated
+ -- block both as requested by the application and as physically
+ -- allocated to fit the additional information needed by the debug
+ -- pool.
+ --
-- All instantiations of this pool use the same internal tables. However,
-- they do not store the same amount of information for the tracebacks,
-- and they have different counters for maximum logically freed memory.
-- the Debug_Pool).
--
-- The information includes the stacktrace for the allocation or
- -- deallocation of that memory chunck, its current status (allocated or
+ -- deallocation of that memory chunk, its current status (allocated or
-- logically freed), etc.
private
Storage_Address : System.Address;
Size_In_Storage_Elements : Storage_Count;
Alignment : Storage_Count);
- -- Check whether a derefence statement is valid, ie whether the pointer
+ -- Check whether a dereference statement is valid, i.e. whether the pointer
-- was allocated through Pool. As documented above, errors will be
-- reported either by a special error message or an exception, depending
-- on the setup of the storage pool.
type Byte_Count is mod System.Max_Binary_Modulus;
-- Type used for maintaining byte counts, needs to be large enough
- -- to accomodate counts allowing for repeated use of the same memory.
+ -- to accommodate counts allowing for repeated use of the same memory.
type Debug_Pool is new System.Checked_Pools.Checked_Pool with record
Stack_Trace_Depth : Natural := Default_Stack_Trace_Depth;
Raise_Exceptions : Boolean := Default_Raise_Exceptions;
Minimum_To_Free : SSC := Default_Min_Freed;
Advanced_Scanning : Boolean := Default_Advanced_Scanning;
+ Errors_To_Stdout : Boolean := Default_Errors_To_Stdout;
+ Low_Level_Traces : Boolean := Default_Low_Level_Traces;
Allocated : Byte_Count := 0;
-- Total number of bytes allocated in this pool
-- Total number of bytes logically deallocated in this pool. This is the
-- memory that the application has released, but that the pool has not
-- yet physically released through a call to free(), to detect later
- -- accesed to deallocated memory.
+ -- accessed to deallocated memory.
Physically_Deallocated : Byte_Count := 0;
- -- Total number of bytes that were free()-ed.
+ -- Total number of bytes that were free()-ed
Marked_Blocks_Deallocated : Boolean := False;
-- Set to true if some mark blocks had to be deallocated in the advanced
- -- scanning scheme. Since this is potentially dangereous, this is
+ -- scanning scheme. Since this is potentially dangerous, this is
-- reported to the user, who might want to rerun his program with a
-- lower Minimum_To_Free value.
First_Free_Block : System.Address := System.Null_Address;
Last_Free_Block : System.Address := System.Null_Address;
- -- Pointers to the first and last logically freed blocks.
+ -- Pointers to the first and last logically freed blocks
First_Used_Block : System.Address := System.Null_Address;
-- Pointer to the list of currently allocated blocks. This list is