Fixing another bug related to amdgpu register names (#948)
[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 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 addStepper(FrameStepper *stepper, Address start, Address
38 end) = 0;
39 \end{apient}
40 \apidesc{Add the specified \code{FrameStepper} to the list of known
41   steppers, and register it to handle frames in the range
42   [\code{start}, \code{end}).}
43
44 \begin{apient}
45 virtual void registerStepper(FrameStepper *stepper);
46 \end{apient}
47
48 \apidesc{Add the specified \code{FrameStepper} to the list of known
49   steppers and use it over the entire address space.}
50
51 \begin{apient}
52 virtual bool findStepperForAddr(Address addr, FrameStepper* &out, 
53                                 const FrameStepper *last_tried = NULL) = 0
54 \end{apient}
55 \apidesc{
56     Given an address that points into a function (or function-like object),
57     addr, this method decides which \code{FrameStepper} should be used to walk through
58     the stack frame created by the function at that address. A pointer to the
59     \code{FrameStepper} will be returned in parameter \code{out}. 
60
61     It may be possible that the \code{FrameStepper} this method decides on is unable to
62     walk through the stack frame (it returns \code{gcf\_not\_me} from
63     \code{FrameStepper::getCallerFrame}). In this case StackwalkerAPI will call
64     findStepperForAddr again with the last\_tried parameter set to the failed
65     \code{FrameStepper}. findStepperForAddr should then find another \code{FrameStepper} to
66     use. Parameter \code{last\_tried} will be set to NULL the first time getStepperToUse
67     is called for a stack frame.
68
69     The default version of this method uses address ranges to decide which
70     \code{FrameStepper} to use. The address ranges are contained within the process'
71     code space, and map a piece of the code space to a \code{FrameStepper} that can
72     walk through stack frames created in that code range. If multiple
73     \code{FrameStepper} objects share the same range, then the one with the highest
74     priority will be tried first.
75         
76     This method returns \code{true} on success and \code{false} on failure.  
77 }
78
79 \begin{apient}
80 typedef std::pair<std::string, Address> LibAddrPair;
81 typedef enum { library_load, library_unload } lib_change_t;    
82 virtual void newLibraryNotification(LibAddrPair *libaddr, lib_change_t
83 change);
84 \end{apient}
85 \apidesc{Called by the StackwalkerAPI when a new library is loaded.}
86
87 \begin{apient}
88 Walker *getWalker() const
89 \end{apient}
90 \apidesc{
91         This method returns the Walker object that associated with this StepperGroup.
92 }
93
94 \begin{apient}
95 void getSteppers(std::set<FrameStepper *> &);
96 \end{apient}
97 \apidesc{Fill in the provided set with all \code{FrameSteppers}
98   registered in the \code{StepperGroup}. }
99