Commit | Line | Data |
---|---|---|
a1a2b649 | 1 | /* This file is part of the Linux Trace Toolkit Graphic User Interface |
2 | * Copyright (C) 2003-2004 Mathieu Desnoyers | |
3 | * | |
4 | * This program is free software; you can redistribute it and/or modify | |
5 | * it under the terms of the GNU General Public License Version 2 as | |
6 | * published by the Free Software Foundation; | |
7 | * | |
8 | * This program is distributed in the hope that it will be useful, | |
9 | * but WITHOUT ANY WARRANTY; without even the implied warranty of | |
10 | * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the | |
11 | * GNU General Public License for more details. | |
12 | * | |
13 | * You should have received a copy of the GNU General Public License | |
14 | * along with this program; if not, write to the Free Software | |
b9ce0bad YB |
15 | * Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, |
16 | * MA 02110-1301, USA. | |
a1a2b649 | 17 | */ |
18 | ||
19 | /* This file is the API used to launch any background computation on a trace */ | |
20 | ||
9232f6fd | 21 | /* lttvwindowtraces |
22 | * | |
23 | * This API consists in two main parts. The first one is for the background | |
24 | * computation provider and the second is for the viewer which needs this | |
25 | * information. | |
26 | * | |
27 | * A computation provider, i.e. a statistics computation module or a state | |
28 | * computation module, have two things in common : they append data to a trace | |
29 | * in an extensible container (LttvAttributes). This extended information, once | |
30 | * computed, can be kept all along with the trace and does not need to be | |
31 | * recomputed : a computation done on a trace must result in a identical result | |
32 | * each time it is done. | |
33 | * | |
34 | * This API provides functions for computation provider to register their | |
35 | * computation functions (or computation functions insertion and removal | |
36 | * functions). Once the computation provider is registered with its module name, | |
37 | * extended computation for a trace can be requested by any viewer by specifying | |
38 | * the module name, as we will describe in a moment. | |
39 | * | |
40 | * A viewer which needs extended information about a trace must ask for it to be | |
41 | * computed by doing a background computation request. It may also ask to be | |
42 | * notified of the completion of its request by doing a notify request. | |
43 | * | |
44 | * Before asking for the computation, it must check for its readiness. If it is | |
45 | * ready, the information has already been computed, so it is ready to use. If | |
46 | * the information is not ready, in must check whether or not the processing of | |
47 | * this task is in progress. If it is, it must not do any background computation | |
48 | * request. It must only do a background notification request of the current | |
49 | * processing to be informed of its completion. If the information is not ready | |
50 | * and not being processed, then the viewer may do a background computation | |
51 | * request and add a notify request to the notify queue. | |
52 | * | |
53 | * When a context takes control of a trace, it must lock the trace. This is a | |
54 | * way of ensuring that not conflict will occur between two traceset contexts | |
55 | * and shared traces. It will generate an error if a context try to get a lock | |
56 | * on a trace what is not unlocked. Upon every trace locking, | |
57 | * lttv_process_traceset_synchronize_tracefiles should be used to resynchronize | |
58 | * the traces with the trace context information. | |
59 | * | |
60 | * The usefulness of the lock in this framework can be questionable in a | |
61 | * single threaded environment, but can be great in the eventuality of | |
62 | * multiple threads. | |
63 | * | |
64 | */ | |
65 | ||
66 | ||
67 | ||
a1a2b649 | 68 | #ifndef LTTVWINDOWTRACES_H |
69 | #define LTTVWINDOWTRACES_H | |
70 | ||
190724cd | 71 | #include <lttv/time.h> |
a1a2b649 | 72 | #include <glib.h> |
b5e17af5 | 73 | #include <gtk/gtk.h> |
a1a2b649 | 74 | |
75 | typedef GQuark LttvTraceInfo; | |
76 | ||
77 | extern LttvTraceInfo LTTV_TRACES, | |
78 | LTTV_COMPUTATION, | |
79 | LTTV_REQUESTS_QUEUE, | |
80 | LTTV_REQUESTS_CURRENT, | |
81 | LTTV_NOTIFY_QUEUE, | |
8bc02ec8 | 82 | LTTV_NOTIFY_CURRENT, |
83 | LTTV_COMPUTATION_TRACESET, | |
84 | LTTV_COMPUTATION_TRACESET_CONTEXT, | |
79257ba5 | 85 | LTTV_COMPUTATION_SYNC_POSITION, |
8bc02ec8 | 86 | LTTV_BEFORE_CHUNK_TRACESET, |
87 | LTTV_BEFORE_CHUNK_TRACE, | |
88 | LTTV_BEFORE_CHUNK_TRACEFILE, | |
89 | LTTV_AFTER_CHUNK_TRACESET, | |
90 | LTTV_AFTER_CHUNK_TRACE, | |
91 | LTTV_AFTER_CHUNK_TRACEFILE, | |
92 | LTTV_BEFORE_REQUEST, | |
93 | LTTV_AFTER_REQUEST, | |
94 | LTTV_EVENT_HOOK, | |
750eb11a | 95 | LTTV_EVENT_HOOK_BY_ID_CHANNEL, |
313bd6fc | 96 | LTTV_HOOK_ADDER, |
97 | LTTV_HOOK_REMOVER, | |
8bc02ec8 | 98 | LTTV_IN_PROGRESS, |
b052368a | 99 | LTTV_READY, |
100 | LTTV_LOCK; | |
8bc02ec8 | 101 | |
102 | ||
a1a2b649 | 103 | |
104 | /* Get a trace by its path name. | |
105 | * | |
106 | * @param path path of the trace on the virtual file system. | |
107 | * @return Pointer to trace if found | |
108 | * NULL is returned if the trace is not present | |
109 | */ | |
110 | ||
111 | LttvTrace *lttvwindowtraces_get_trace_by_name(gchar *path); | |
112 | ||
113 | /* Get a trace by its number identifier */ | |
114 | ||
115 | LttvTrace *lttvwindowtraces_get_trace(guint num); | |
116 | ||
117 | /* Total number of traces */ | |
118 | ||
119 | guint lttvwindowtraces_get_number(); | |
120 | ||
121 | /* Add a trace to the global attributes */ | |
122 | ||
123 | void lttvwindowtraces_add_trace(LttvTrace *trace); | |
124 | ||
125 | /* Remove a trace from the global attributes */ | |
126 | ||
127 | void lttvwindowtraces_remove_trace(LttvTrace *trace); | |
128 | ||
129 | ||
130 | /** | |
131 | * Function to request data from a specific trace | |
132 | * | |
133 | * The memory allocated for the request will be managed by the API. | |
134 | * | |
b5e17af5 | 135 | * @param tab parent Window |
a1a2b649 | 136 | * @param trace the trace to compute |
137 | * @param module_name the name of the module which registered global computation | |
138 | * hooks. | |
139 | */ | |
140 | ||
141 | void lttvwindowtraces_background_request_queue | |
b5e17af5 | 142 | (GtkWidget *widget, LttvTrace *trace, gchar *module_name); |
a1a2b649 | 143 | |
144 | /** | |
145 | * Remove a background request from a trace. | |
146 | * | |
147 | * This should ONLY be used by the modules which registered the global hooks | |
148 | * (module_name). If this is called by the viewers, it may lead to incomplete | |
149 | * and incoherent background processing information. | |
150 | * | |
151 | * Even if the module which deals with the hooks removes the background | |
152 | * requests, it may cause a problem if the module gets loaded again in the | |
153 | * session : the data will be partially calculated. The calculation function | |
154 | * must deal with this case correctly. | |
155 | * | |
156 | * @param trace the trace to compute | |
157 | * @param module_name the name of the module which registered global computation | |
158 | * hooks. | |
159 | */ | |
160 | ||
161 | void lttvwindowtraces_background_request_remove | |
162 | (LttvTrace *trace, gchar *module_name); | |
163 | ||
93ac601b | 164 | |
165 | ||
166 | /** | |
167 | * Find a background request in a trace | |
168 | * | |
169 | */ | |
170 | ||
171 | gboolean lttvwindowtraces_background_request_find | |
172 | (LttvTrace *trace, gchar *module_name); | |
173 | ||
a1a2b649 | 174 | /** |
175 | * Register a callback to be called when requested data is passed in the next | |
176 | * queued background processing. | |
177 | * | |
178 | * @param owner owner of the background notification | |
179 | * @param trace the trace computed | |
180 | * @param notify_time time when notification hooks must be called | |
181 | * @param notify_position position when notification hooks must be called | |
182 | * @param notify Hook to call when the notify position is passed | |
183 | */ | |
184 | ||
185 | void lttvwindowtraces_background_notify_queue | |
186 | (gpointer owner, | |
187 | LttvTrace *trace, | |
188 | LttTime notify_time, | |
451aaf27 | 189 | const LttvTracesetPosition *notify_position, |
a1a2b649 | 190 | const LttvHooks *notify); |
191 | ||
192 | /** | |
193 | * Register a callback to be called when requested data is passed in the current | |
194 | * background processing. | |
195 | * | |
196 | * @param owner owner of the background notification | |
197 | * @param trace the trace computed | |
198 | * @param notify_time time when notification hooks must be called | |
199 | * @param notify_position position when notification hooks must be called | |
200 | * @param notify Hook to call when the notify position is passed | |
201 | */ | |
202 | ||
203 | void lttvwindowtraces_background_notify_current | |
204 | (gpointer owner, | |
205 | LttvTrace *trace, | |
206 | LttTime notify_time, | |
451aaf27 | 207 | const LttvTracesetPosition *notify_position, |
a1a2b649 | 208 | const LttvHooks *notify); |
209 | ||
210 | /** | |
211 | * Removes all the notifications requests from a specific viewer. | |
212 | * | |
213 | * @param owner owner of the background notification | |
214 | */ | |
215 | ||
216 | void lttvwindowtraces_background_notify_remove(gpointer owner); | |
217 | ||
218 | ||
e62a7964 | 219 | /** |
220 | * Tells if the information computed by a module for a trace is ready. | |
221 | * | |
222 | * Must be checked before a background processing request. | |
223 | * | |
224 | * @param module_name A GQuark : the name of the module which computes the | |
225 | * information. | |
226 | * @param trace The trace for which the information is verified. | |
227 | */ | |
228 | ||
229 | gboolean lttvwindowtraces_get_ready(LttvAttributeName module_name, | |
230 | LttvTrace *trace); | |
231 | ||
232 | /** | |
233 | * Tells if the information computed by a module for a trace is being processed. | |
234 | * | |
235 | * Must be checked before a background processing request. | |
236 | * | |
237 | * If it is effectively processed, the typical thing to do is to call | |
238 | * lttvwindowtraces_background_notify_current to be notified when the current | |
239 | * processing will be over. | |
240 | * | |
241 | * @param module_name A GQuark : the name of the module which computes the | |
242 | * information. | |
243 | * @param trace The trace for which the information is verified. | |
244 | */ | |
245 | ||
246 | gboolean lttvwindowtraces_get_in_progress(LttvAttributeName module_name, | |
247 | LttvTrace *trace); | |
248 | ||
249 | /** | |
250 | * Register the background computation hooks for a specific module. It adds the | |
251 | * computation hooks to the global attrubutes, under "computation/module name" | |
252 | * | |
253 | * @param module_name A GQuark : the name of the module which computes the | |
254 | * information. | |
255 | */ | |
256 | void lttvwindowtraces_register_computation_hooks(LttvAttributeName module_name, | |
257 | LttvHooks *before_chunk_traceset, | |
258 | LttvHooks *before_chunk_trace, | |
259 | LttvHooks *before_chunk_tracefile, | |
260 | LttvHooks *after_chunk_traceset, | |
261 | LttvHooks *after_chunk_trace, | |
262 | LttvHooks *after_chunk_tracefile, | |
263 | LttvHooks *before_request, | |
264 | LttvHooks *after_request, | |
265 | LttvHooks *event_hook, | |
313bd6fc | 266 | LttvHooks *hook_adder, |
267 | LttvHooks *hook_remover); | |
e62a7964 | 268 | /** |
269 | * Unregister the background computation hooks for a specific module. | |
270 | * | |
271 | * It also removes all the requests than can be currently processed by the | |
272 | * background computation algorithm for all the traces (list_in and list_out). | |
273 | * | |
274 | * @param module_name A GQuark : the name of the module which computes the | |
275 | * information. | |
276 | */ | |
277 | ||
278 | void lttvwindowtraces_unregister_computation_hooks | |
279 | (LttvAttributeName module_name); | |
280 | ||
281 | ||
282 | /** | |
283 | * It removes all the requests than can be currently processed by the | |
284 | * background computation algorithm for all the traces (list_in and list_out). | |
285 | * | |
286 | * Leaves the flag to in_progress or none.. depending if current or queue | |
287 | * | |
288 | * @param module_name A GQuark : the name of the module which computes the | |
289 | * information. | |
290 | */ | |
291 | void lttvwindowtraces_unregister_requests(LttvAttributeName module_name); | |
292 | ||
293 | ||
b052368a | 294 | /** |
295 | * Lock a trace so no other instance can use it. | |
296 | * | |
297 | * @param trace The trace to lock. | |
298 | * @return 0 on success, -1 if cannot get lock. | |
299 | */ | |
300 | gint lttvwindowtraces_lock(LttvTrace *trace); | |
301 | ||
302 | ||
303 | /** | |
304 | * Unlock a trace. | |
305 | * | |
306 | * @param trace The trace to unlock. | |
307 | * @return 0 on success, -1 if cannot unlock (not locked ?). | |
308 | */ | |
309 | gint lttvwindowtraces_unlock(LttvTrace *trace); | |
310 | ||
311 | /** | |
312 | * Verify if a trace is locked. | |
313 | * | |
314 | * @param trace The trace to verify. | |
315 | * @return TRUE if locked, FALSE is unlocked. | |
316 | */ | |
317 | gint lttvwindowtraces_get_lock_state(LttvTrace *trace); | |
318 | ||
319 | ||
a1a2b649 | 320 | #endif //LTTVWINDOWTRACES_H |