Updated line info documentation & regenerated manuals with proper dependency tracking.
[dyninst.git] / stackwalk / doc / 2-Abstractions.tex
1 \section{Abstractions}
2 \label{sec:abstractions}
3
4 StackwalkerAPI contains two interfaces: the Stackwalking Interface and the
5 Callback Interface. The stackwalking interface is used to walk the call stack,
6 query information about stack frames, and collect basic information about
7 threads. The Callback Interface is used to provide custom mechanisms for walking
8 a call stack. Users who operate in one of StackwalkerAPI's standard
9 configurations do not need to use the Callback Interface. 
10     
11 Figure~\ref{fig:object-ownership} shows the ownership hierarchy for
12 StackwalkerAPI's classes. Ownership is a "contains" relationship; if one class
13 owns another, then instances of the owner class maintain an exclusive instance
14 of the other. For example, in Figure~\ref{fig:object-ownership} the each Walker
15 instance contains exactly one instance of a ProcessState object.  No other
16 instance of Walker uses that instance of ProcessState.  
17
18 This remainder of this
19 section briefly describes the six classes that make up StackwalkerAPI's two
20 interfaces. For more details, see the class descriptions in
21 Section~\ref{sec:api}.
22
23 \input{fig/object-ownership}
24
25 \subsection{Stackwalking Interface}
26 \begin{description}
27     \item [Walker] The Walker class is the top-level class used for collecting
28         stackwalks. It provides a simple interface for requesting a stackwalk.
29         Each Walker object is associated with one process, but may walk the call
30         stacks of multiple threads within that process.
31     \item [Frame] A call stack is returned as a vector of Frame objects, where
32         each Frame object represents a stack frame. It can provide information
33         about the stack frame and basic information about the function, signal
34         handler or other mechanism that created it. Users can request
35         information such as the symbolic name associated with the Frame object,
36         and values of its saved registers. 
37 \end{description}
38
39 \subsection{Callback Interface}
40 StackwalkerAPI includes default implementations of the Callback Interface on
41 each of its supported platforms. These default implementations allow
42 StackwalkerAPI to work "out of the box" in a standard configuration on each
43 platform. Users can port StackwalkerAPI to new platforms or customize its call
44 stack walking behavior by implementing their own versions of the classes in the
45 Callback Interface.
46
47 \begin{description}
48 \item [FrameStepper] A FrameStepper object describes how to walk through a
49     single type of stack frame. Users can provide an implementation of this
50     interface that allows StackwalkerAPI to walk through new types of stack
51     frames. For example, the DyninstAPI uses this interface to extend
52     StackwalkerAPI to allow it to walk through stack frames created by
53     instrumentation code.
54
55 \item [StepperGroup] A StepperGroup is a collection of FrameStepper objects and
56     criteria that describes when to use each type of FrameStepper. These
57     criteria are based on simple address ranges in the code space of the target
58     process. In the above example with DyninstAPI, it would be the job of the
59     StepperGroup to identify a stack frame as belonging to instrumentation code
60     and use the instrumentation FrameStepper to walk through it.
61
62 \item [ProcessState] A ProcessState interface describes how to access data in
63     the target process. To walk a call stack, StackwalkerAPI needs to access
64     both registers and memory in the target process; ProcessState provides an
65     interface that StackwalkerAPI can use to access that information.
66     StackwalkerAPI includes two default implementation of ProcessState for each
67     platform: one to collect a first party stackwalk in the current process, and
68     one that uses a debugger interface to collect a third party stackwalk in
69     another process.
70
71 \item [SymbolLookup] The SymbolLookup interface is used to associate a symbolic
72     name with a stack frame. A stackwalk returns a collection of addresses in
73     the code space of a binary. This class uses the binary's symbol table to map
74     those addresses into symbolic names. A default implementation of this class,
75     which uses the DynSymtab package, is provided with StackwalkerAPI. A user
76     could, for example, use this interface to allow StackwalkerAPI to use libelf
77     to look up symbol names instead.
78 \end{description}