Added stackwalk/doc LaTeX files.
[dyninst.git] / stackwalk / doc / API / Walker.tex
1 \subsubsection{Class Walker}
2 \label{subsec:walker}
3 \definedin{walker.h}
4
5 The \code{Walker} class allows users to walk call stacks and query basic information
6 about threads in a target process. The user should create a \code{Walker} object for
7 each process from which they are walking call stacks. Each \code{Walker} object is
8 associated with one process, but may walk call stacks on multiple threads within
9 that process. The \code{Walker} class allows users to query for the threads available
10 for walking, and it allows you to specify a particular thread whose call stack
11 should be walked. Stackwalks are returned as a vector of Frame objects. 
12
13 Each Walker object contains three objects: 
14 \begin{itemize}
15     \item ProcessState
16     \item StepperGroup
17     \item SymbolLookup
18 \end{itemize}
19
20 These objects are part of the Callback Interface and can be used to customize
21 StackwalkerAPI. The \code{ProcessState} object tells \code{Walker} how to access data in the
22 target process, and it determines whether this \code{Walker} collects first party or
23 third party stackwalks. \code{Walker} will pick an appropriate default \code{ProcessState}
24 object based on which factory method the users calls. The \code{StepperGroup} object is
25 used to customize how the \code{Walker} steps through stack frames. The
26 \code{SymbolLookup}
27 object is used to customize how StackwalkerAPI looks up symbolic names of the
28 function or object that created a stack frame.
29
30 \begin{apient}
31 static Walker *newWalker()
32 \end{apient}
33 \apidesc{
34         This factory method creates a new \code{Walker} object that performs first party stackwalks.
35
36     The new \code{Walker} object uses the default \code{StepperGroup} and
37     \code{SymbolLookup} callbacks for the current platform, and it uses the
38     \code{ProcSelf} callback for its \code{ProcessState} object. See
39     Section~\ref{subsec:defaults} for more information about defaults in the
40     Callback Interface. 
41
42     This method returns \code{NULL} if it was unable to create a new \code{Walker}
43     object. The new \code{Walker} object was created with the \code{new} operator, and
44     should be deallocated with the \code{delete} operator when it is no longer needed.
45 }
46  
47 \begin{apient}
48 static Walker *newWalker(Dyninst::PID pid)
49 \end{apient}
50 \apidesc{
51     This factory method creates a new \code{Walker} object that performs third
52     party stackwalks, on the process identified by \code{pid}. 
53
54     The new \code{Walker} object uses the default \code{StepperGroup} and
55     \code{SymbolLookup}
56     callbacks for the current platform, and it uses the \code{ProcSelf} callback for
57     its \code{ProcessState} object. See Section~\ref{subsec:defaults} for more information about
58     defaults in the Callback Interface. 
59
60     This method returns \code{NULL} if it is unable to create a new
61     \code{Walker} object. The
62     new \code{Walker} object is created with the \code{new} operator, and should be
63     deallocated with the \code{delete} operator when it is no longer needed.
64 }
65  
66 \begin{apient}
67 static Walker *newWalker(ProcessState *proc,                    
68                          StepperGroup *steppergroup = NULL              ,
69                          SymbolLookup *lookup = NULL)
70 \end{apient}
71 \apidesc{
72     This factory method creates a new \code{Walker} object that walks call stacks on
73     the given \code{proc} object. Custom \code{StepperGroup} and
74     \code{SymbolLookup} can be given
75     with the steppergroup and lookup parameters. If the steppergroup or lookup
76     parameters are \code{NULL}, then StackwalkerAPI will create a \code{Walker} object that
77     uses a default callbacks for the \code{NULL} parameter, as described in
78     Section~\ref{sec:defaults}. 
79
80     It is an error to pass \code{NULL} in the \code{proc} parameter. \code{proc} is used to determine
81     whether to collect first party or third party stackwalks and, in the case of
82     third party stackwalks, identify the target process.
83
84     This method returns \code{NULL} if there was an error creating the new \code{Walker}
85     object. The new \code{Walker} object is created with the \code{new} operator, and
86     should be deallocated with the \code{delete} operator when it is no longer needed.
87 }
88  
89 \begin{apient}
90 bool walkStack(std::vector<Frame> &stackwalk,    
91                Dyninst::THR_ID thread = NULL_THR_ID)
92 \end{apient}
93 \apidesc{
94     This method walks a call stack in the process associated with this \code{Walker}.
95     The call stack is returned as a vector of \code{Frame} objects in stackwalk. The
96     top of the stack is returned in index 0 of stackwalk, and the bottom of the
97     stack is returned in index \code{stackwalk.size()-1}.
98
99     A stackwalk can be taken on a specific thread by passing a value in the
100     thread parameter. If \code{thread} has the value \code{NULL\_THR\_ID}, then a default thread
101     will be chosen. When doing a third party stackwalk, the default thread will
102     be the process' initial thread. When doing a first party stackwalk, the
103     default thread will be the thread that called \code{walkStack}. 
104
105     This method returns \code{true} on success and \code{false} on failure.
106 }
107  
108 \begin{apient}
109 bool walkStackFromFrame(std::vector<Frame> &stackwalk, const Frame &frame)
110 \end{apient}
111 \apidesc{
112     This method walks a call stack starting from the given stack frame,
113     \code{frame}.
114     The call stack will be output in the \code{stackwalk} vector, with frame stored in
115     index 0 of \code{stackwalk} and the bottom of the stack stored in index
116     \code{stackwalk.size()-1}.
117
118     This method returns \code{true} on success and \code{false} on failure.
119 }
120  
121 \begin{apient}
122 bool walkSingleFrame(const Frame &in, Frame &out)
123 \end{apient}
124 \apidesc{
125     This methods walks through single frame, \code{in}. Parameter \code{out}
126     will be set to \code{in}'s caller frame.
127
128     This method returns \code{true} on success and \code{false} on failure.
129 }
130  
131 \begin{apient}
132 bool getInitialFrame(Frame &frame, Dyninst::THR_ID thread = NULL_THR_ID)
133 \end{apient}
134 \apidesc{
135     This method returns the \code{Frame} object on the top of the stack in parameter
136     frame. Under \code{walkStack}, \code{frame} would be the one returned in index 0 of the
137     \code{stackwalk} vector.  A stack frame can be found on a specific thread by
138     passing a value in the thread parameter. If \code{thread} has the value
139     \code{NULL\_THR\_ID}, then a default thread will be chosen. When doing a third party
140     stackwalk, the default thread will be the process' initial thread. When
141     doing a first party stackwalk, the default thread will be the thread that
142     called \code{getInitialFrame}. 
143
144     This method returns \code{true} on success and \code{false} on failure.
145 }
146  
147 \begin{apient}
148 bool getAvailableThreads(std::vector<Dyninst::THR_ID> &threads)
149 \end{apient}
150 \apidesc{
151     This method returns a vector of threads in the target process upon which
152     StackwalkerAPI can walk call stacks. The threads are returned in output
153     parameter \code{threads}. Note that this method may return a subset of the actual
154     threads in the process. For example, when walking call stacks on the current
155     process, it is only legal to walk the call stack on the currently running
156     thread. In this case, \code{getAvailableThreads} returns a vector containing only
157     the current thread.
158
159     This method returns \code{true} on success and \code{false} on failure.
160 }
161  
162 \begin{apient}
163 ProcessState *getProcessState() const
164 \end{apient}
165 \apidesc{
166     This method returns the \code{ProcessState} object associated with this \code{Walker}.
167 }
168  
169 \begin{apient}
170 StepperGroup *getStepperGroup() const
171 \end{apient}
172 \apidesc{
173     This method returns the \code{StepperGroup} object associated with this \code{Walker}.
174 }
175  
176 \begin{apient}
177 SymbolLookup *getSymbolLookup() const
178 \end{apient}
179 \apidesc{
180     This method returns the \code{SymbolLookup} object associated with this \code{Walker}.
181 }