1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
|
/*
thread.h
Copyright (C) 2010 Red Hat, Inc.
This program is free software; you can redistribute it and/or modify
it under the terms of the GNU General Public License as published by
the Free Software Foundation; either version 2 of the License, or
(at your option) any later version.
This program is distributed in the hope that it will be useful,
but WITHOUT 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 along
with this program; if not, write to the Free Software Foundation, Inc.,
51 Franklin Street, Fifth Floor, Boston, MA 02110-1301 USA.
*/
#ifndef BTPARSER_THREAD_H
#define BTPARSER_THREAD_H
#include <stdbool.h>
#ifdef __cplusplus
extern "C" {
#endif
struct btp_frame;
struct strbuf;
struct btp_location;
/**
* Represents a thread containing frames.
*/
struct btp_thread
{
unsigned number;
/**
* Thread's frames, starting from the top of the stack.
*/
struct btp_frame *frames;
/**
* A sibling thread, or NULL if this is the last thread in a backtrace.
*/
struct btp_thread *next;
};
/**
* Creates and initializes a new frame structure.
* @returns
* It never returns NULL. The returned pointer must be released by
* calling the function btp_thread_free().
*/
struct btp_thread *
btp_thread_new();
/**
* Initializes all members of the thread to default values.
* No memory is released, members are simply overwritten.
* This is useful for initializing a thread structure placed on the
* stack.
*/
void
btp_thread_init(struct btp_thread *thread);
/**
* Releases the memory held by the thread. The thread siblings are not
* released.
* @param thread
* If thread is NULL, no operation is performed.
*/
void
btp_thread_free(struct btp_thread *thread);
/**
* Creates a duplicate of the thread.
* @param thread
* It must be non-NULL pointer. The thread is not modified by calling
* this function.
* @param siblings
* Whether to duplicate also siblings referenced by thread->next. If
* false, thread->next is not duplicated for the new frame, but it is
* set to NULL.
*/
struct btp_thread *
btp_thread_dup(struct btp_thread *thread,
bool siblings);
/**
* Compares two threads. When comparing the threads, it compares also
* their frames, including the frame numbers.
* @returns
* Returns 0 if the threads are same. Returns negative number if t1
* is found to be 'less' than t2. Returns positive number if t1 is
* found to be 'greater' than t2.
*/
int
btp_thread_cmp(struct btp_thread *t1, struct btp_thread *t2);
/**
* Puts the thread 'b' to the bottom of the stack 'a'. In other words,
* it finds the last sibling of the thread 'a', and appends the thread
* 'b' to this last sibling.
*/
struct btp_thread *
btp_thread_add_sibling(struct btp_thread *a, struct btp_thread *b);
/**
* Returns the number of frames of the thread.
*/
int
btp_thread_get_frame_count(struct btp_thread *thread);
/**
* Counts the number of 'good' frames and the number of all frames in
* a thread. Good means that the function name is known (so it's not
* just '??').
* @param ok_count
* @param all_count
* Not zeroed. This function just adds the numbers to ok_count and
* all_count.
*/
void
btp_thread_quality_counts(struct btp_thread *thread,
int *ok_count,
int *all_count);
/**
* Returns the quality of the thread. The quality is the ratio of the
* number of frames with function name fully known to the number of
* all frames. This function does not take into account that some
* frames are more important than others.
* @param thread
* Must be a non-NULL pointer. It's not modified in this function.
* @returns
* A number between 0 and 1. 0 means the lowest quality, 1 means full
* thread backtrace is known. If the thread contains no frames, this
* function returns 1.
*/
float
btp_thread_quality(struct btp_thread *thread);
/**
* Removes the frame from the thread and then deletes it.
* @returns
* True if the frame was found in the thread and removed and deleted.
* False if the frame was not found in the thread.
*/
bool
btp_thread_remove_frame(struct btp_thread *thread,
struct btp_frame *frame);
/**
* Removes all the frames from the thread that are above certain
* frame.
* @returns
* True if the frame was found, and all the frames that were above the
* frame in the thread were removed from the thread and then deleted.
* False if the frame was not found in the thread.
*/
bool
btp_thread_remove_frames_above(struct btp_thread *thread,
struct btp_frame *frame);
/**
* Keeps only the top n frames in the thread.
*/
void
btp_thread_remove_frames_below_n(struct btp_thread *thread,
int n);
/**
* Appends a textual representation of 'thread' to the 'str'.
*/
void
btp_thread_append_to_str(struct btp_thread *thread,
struct strbuf *str,
bool verbose);
/**
* If the input contains proper thread with frames, parse the thread,
* move the input pointer after the thread, and return a structure
* representing the thread. Otherwise to not modify the input pointer
* and return NULL.
* @param location
* The caller must provide a pointer to struct btp_location here. The
* line and column members are gradually increased as the parser
* handles the input, keep this in mind to get reasonable values.
* When this function returns NULL (an error occurred), the structure
* will contain the error line, column, and message.
* @returns
* NULL or newly allocated structure, which should be released by
* calling btp_thread_free().
*/
struct btp_thread *
btp_thread_parse(char **input,
struct btp_location *location);
/**
* If the input contains a LWP section in form of "(LWP [0-9]+), move
* the input pointer after this section. Otherwise do not modify
* input.
* @returns
* The number of characters parsed from input. 0 if the input does not
* contain a LWP section.
*/
int
btp_thread_skip_lwp(char **input);
#ifdef __cplusplus
}
#endif
#endif
|
