File : s-traceb.ads
------------------------------------------------------------------------------
-- --
-- GNAT COMPILER COMPONENTS --
-- --
-- S Y S T E M . T R A C E B A C K --
-- --
-- S p e c --
-- --
-- $Revision: 1.1 $
-- --
-- Copyright (C) 1999 Ada Core Technologies, 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- --
-- 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, 59 Temple Place - Suite 330, Boston, --
-- MA 02111-1307, USA. --
-- --
-- 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. --
-- --
-- GNAT was originally developed by the GNAT team at New York University. --
-- It is now maintained by Ada Core Technologies Inc (http://www.gnat.com). --
-- --
------------------------------------------------------------------------------
pragma Polling (Off);
-- We must turn polling off for this unit, because otherwise we get
-- elaboration circularities with System.Exception_Tables.
-- This package provides a method for generating a traceback of the
-- current execution location. The traceback shows the locations of
-- calls in the call chain, up to either the top or a designated
-- number of levels.
package System.Traceback is
subtype Code_Loc is System.Address;
-- Code location used for call addresses when computing tracebacks.
-- Values of this type are created by using Label'Address or
-- extracted from machine states using Get_Code_Loc.
type Machine_State is new System.Address;
-- Similar to System.Machine_State_Operations.Machine_State, except that
-- the structure needed to get program counter tracebacks may be simpler if
-- the underlying implementation used is different.
function Allocate_Machine_State return Machine_State;
-- Allocate the required space for a Machine_State
procedure Free_Machine_State (M : in out Machine_State);
-- Free the dynamic memory taken by Machine_State
function Get_Code_Loc (M : Machine_State) return Code_Loc;
-- This function extracts the program counter value from a machine
-- state, which the caller uses for recording entries in a traceback
-- table. The call returns a value of Null_Loc if the machine state
-- represents the outer level, or some other frame for which no information
-- can be provided.
procedure Pop_Frame (M : Machine_State);
-- This procedure pops the machine state M so that it represents the
-- call point, as though the current subprogram had returned. It
-- changes only the value referenced by M, and does not affect
-- the current stack environment.
procedure Set_Machine_State (M : Machine_State);
-- This routine sets M from the current machine state. It is called
-- to initiate a call chain computation.
end System.Traceback;