Added stackwalk/doc LaTeX files.
[dyninst.git] / stackwalk / doc / API / StepperGroup.tex
1 \subsubsection{Class StepperGroup}
2 \label{subsec:steppergroup}
3 \definedin{steppergroup.h}
4
5 The \code{StepperGroup} class contains a collection of \code{FrameStepper} objects. The
6 \code{StepperGroup}'s primary job is to decide which \code{FrameStepper} should be used to
7 walk through a stack frame given a return address. The default \code{StepperGroup}
8 keeps a set of address ranges for each \code{FrameStepper}. If multiple \code{FrameStepper}
9 objects overlap an address, then the default \code{StepperGroup} will use a priority
10 system to decide.
11
12 \code{StepperGroup} provides both an interface and a default implementation of that
13 interface. Users who want to customize the \code{StepperGroup} should inherit from this
14 class and re-implement any of the below virtual functions.
15
16 \begin{apient}
17 virtual StepperGroup(Walker *walker)
18 \end{apient}
19 \apidesc{
20     This factory constructor creates a new \code{StepperGroup} object associated
21 with \code{walker}. 
22 }
23
24 \begin{apient}
25 virtual bool addStepper(FrameStepper *stepper)
26 \end{apient}
27 \apidesc{
28     This method adds a new \code{FrameStepper} to this \code{StepperGroup}. The
29     newly added stepper will be tracked by this \code{StepperGroup}, and it will
30     be considered for use when walking through stack frames. 
31
32     This method returns \code{\code{true}} if it successfully added the
33     \code{FrameStepper}, and \code{\code{false}} on error.
34 }
35
36 \begin{apient}
37 virtual bool addAddressRanges(
38     const std::vector<std::pair<Address, Address> >&ranges,
39     const FrameStepper *stepper) = 0
40 \end{apient}
41 \apidesc{
42     This method associates a set of address ranges, \code{ranges}, with a \code{FrameStepper},
43     stepper. These address ranges contain objects in the process' code space
44     that create stack frames that \code{stepper} can walk through.
45
46     The default \code{StepperGroup} will use \code{stepper} to walk through a Frame object (by
47     returning it from findStepperForAddr) if the Frame object's RA falls within
48     a range registered by this method. A Frame object, frame, falls within a
49     range, range[i], if . If multiple \code{FrameStepper} objects have overlapping
50     ranges, then the default \code{StepperGroup} will use the one with the highest
51     priority first (see \code{FrameStepper}::getPriority in Section~
52     \ref{subsec:framestepper}).
53
54     For example, suppose this \code{FrameStepper} was designed to walk through a signal
55     handler frame on Linux/x86. During initialization the \code{FrameStepper} inspects
56     the target process' vsyscall page and finds that signal handlers will appear
57     on the call stack with a RA between \code{0xffffe000} and \code{0xffffe400}. It then
58     registers this range with its \code{StepperGroup} using addAddressRanges. If the
59     \code{StepperGroup} encounters an RA in this range, it then uses the signal handler
60     \code{FrameStepper} to walk through it.
61
62     Suppose another \code{FrameStepper} was designed to walk through regular stack
63     frames created by ABI-compliant functions. This \code{FrameStepper} will be used as
64     a general catch-all if no other \code{FrameStepper} can walk through a Frame
65     object. The \code{FrameStepper} can register itself with an address range that
66     spans the whole address space, and a lower priority than the signal handler
67     \code{FrameStepper}. The \code{StepperGroup} will then use the signal handler \code{FrameStepper}
68     to step through signal handlers, and this \code{FrameStepper} to step through any
69     other Frame object.
70
71     This method returns \code{true} on success and \code{false} if there is an
72     error.
73 }
74
75 \begin{apient}
76 virtual bool removeAddressRanges(
77     const std::vector<std::pair<Address, Address > > &ranges, 
78     const FrameStepper *stepper) = 0
79 \end{apient}
80 \apidesc{
81     This method removes a FrameStepper's address range from a StepperGroup. See
82     addAddressRange for more details on how StepperGroup and FrameStepper
83     objects use address ranges. The address ranges specified by ranges will be
84     deleted from stepper's address ranges. For example, if the address range
85     \code{0x1000} to \code{0x2000} was registered to a FrameStepper named \code{foo}, and then
86     removeAddressRanges was used to remove the address range \code{0x1500} to
87     \code{0x1600}
88     out of \code{foo}, then \code{foo} would have two address ranges associated with it:
89     \code{0x1000} to \code{0x1500} and \code{0x1600} to \code{0x2000}.
90
91         This function returns \code{true} on success and \code{false} on error.
92 }
93
94 \begin{apient}
95 virtual bool findStepperForAddr(Address addr, FrameStepper* &out, 
96                                 const FrameStepper *last_tried = NULL)
97 \end{apient}
98 \apidesc{
99     Given an address that points into a function (or function-like object),
100     addr, this method decides which \code{FrameStepper} should be used to walk through
101     the stack frame created by the function at that address. A pointer to the
102     \code{FrameStepper} will be returned in parameter \code{out}. 
103
104     It may be possible that the \code{FrameStepper} this method decides on is unable to
105     walk through the stack frame (it returns \code{gcf\_not\_me} from
106     \code{FrameStepper::getCallerFrame}). In this case StackwalkerAPI will call
107     findStepperForAddr again with the last\_tried parameter set to the failed
108     \code{FrameStepper}. findStepperForAddr should then find another \code{FrameStepper} to
109     use. Parameter \code{last\_tried} will be set to NULL the first time getStepperToUse
110     is called for a stack frame.
111
112     The default version of this method uses address ranges to decide which
113     \code{FrameStepper} to use. The address ranges are contained within the process'
114     code space, and map a piece of the code space to a \code{FrameStepper} that can
115     walk through stack frames created in that code range. If multiple
116     \code{FrameStepper} objects share the same range, then the one with the highest
117     priority will be tried first.
118         
119     This method returns \code{true} on success and \code{false} on failure.  
120 }
121
122 \begin{apient}
123 Walker *getWalker() const
124 \end{apient}
125 \apidesc{
126         This method returns the Walker object that associated with this StepperGroup.
127 }