1 /* This file is part of the Linux Trace Toolkit Graphic User Interface
2 * Copyright (C) 2003-2004 Mathieu Desnoyers
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;
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.
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
15 * Foundation, Inc., 59 Temple Place - Suite 330, Boston,
19 /* This file is the API used to launch any background computation on a trace */
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
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.
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.
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.
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.
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.
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
68 #ifndef LTTVWINDOWTRACES_H
69 #define LTTVWINDOWTRACES_H
74 typedef GQuark LttvTraceInfo
;
76 extern LttvTraceInfo LTTV_TRACES
,
79 LTTV_REQUESTS_CURRENT
,
82 LTTV_COMPUTATION_TRACESET
,
83 LTTV_COMPUTATION_TRACESET_CONTEXT
,
84 LTTV_COMPUTATION_SYNC_POSITION
,
85 LTTV_BEFORE_CHUNK_TRACESET
,
86 LTTV_BEFORE_CHUNK_TRACE
,
87 LTTV_BEFORE_CHUNK_TRACEFILE
,
88 LTTV_AFTER_CHUNK_TRACESET
,
89 LTTV_AFTER_CHUNK_TRACE
,
90 LTTV_AFTER_CHUNK_TRACEFILE
,
94 LTTV_EVENT_HOOK_BY_ID
,
103 /* Get a trace by its path name.
105 * @param path path of the trace on the virtual file system.
106 * @return Pointer to trace if found
107 * NULL is returned if the trace is not present
110 LttvTrace
*lttvwindowtraces_get_trace_by_name(gchar
*path
);
112 /* Get a trace by its number identifier */
114 LttvTrace
*lttvwindowtraces_get_trace(guint num
);
116 /* Total number of traces */
118 guint
lttvwindowtraces_get_number();
120 /* Add a trace to the global attributes */
122 void lttvwindowtraces_add_trace(LttvTrace
*trace
);
124 /* Remove a trace from the global attributes */
126 void lttvwindowtraces_remove_trace(LttvTrace
*trace
);
130 * Function to request data from a specific trace
132 * The memory allocated for the request will be managed by the API.
134 * @param trace the trace to compute
135 * @param module_name the name of the module which registered global computation
139 void lttvwindowtraces_background_request_queue
140 (LttvTrace
*trace
, gchar
*module_name
);
143 * Remove a background request from a trace.
145 * This should ONLY be used by the modules which registered the global hooks
146 * (module_name). If this is called by the viewers, it may lead to incomplete
147 * and incoherent background processing information.
149 * Even if the module which deals with the hooks removes the background
150 * requests, it may cause a problem if the module gets loaded again in the
151 * session : the data will be partially calculated. The calculation function
152 * must deal with this case correctly.
154 * @param trace the trace to compute
155 * @param module_name the name of the module which registered global computation
159 void lttvwindowtraces_background_request_remove
160 (LttvTrace
*trace
, gchar
*module_name
);
165 * Find a background request in a trace
169 gboolean lttvwindowtraces_background_request_find
170 (LttvTrace
*trace
, gchar
*module_name
);
173 * Register a callback to be called when requested data is passed in the next
174 * queued background processing.
176 * @param owner owner of the background notification
177 * @param trace the trace computed
178 * @param notify_time time when notification hooks must be called
179 * @param notify_position position when notification hooks must be called
180 * @param notify Hook to call when the notify position is passed
183 void lttvwindowtraces_background_notify_queue
187 const LttvTracesetContextPosition
*notify_position
,
188 const LttvHooks
*notify
);
191 * Register a callback to be called when requested data is passed in the current
192 * background processing.
194 * @param owner owner of the background notification
195 * @param trace the trace computed
196 * @param notify_time time when notification hooks must be called
197 * @param notify_position position when notification hooks must be called
198 * @param notify Hook to call when the notify position is passed
201 void lttvwindowtraces_background_notify_current
205 const LttvTracesetContextPosition
*notify_position
,
206 const LttvHooks
*notify
);
209 * Removes all the notifications requests from a specific viewer.
211 * @param owner owner of the background notification
214 void lttvwindowtraces_background_notify_remove(gpointer owner
);
218 * Tells if the information computed by a module for a trace is ready.
220 * Must be checked before a background processing request.
222 * @param module_name A GQuark : the name of the module which computes the
224 * @param trace The trace for which the information is verified.
227 gboolean
lttvwindowtraces_get_ready(LttvAttributeName module_name
,
231 * Tells if the information computed by a module for a trace is being processed.
233 * Must be checked before a background processing request.
235 * If it is effectively processed, the typical thing to do is to call
236 * lttvwindowtraces_background_notify_current to be notified when the current
237 * processing will be over.
239 * @param module_name A GQuark : the name of the module which computes the
241 * @param trace The trace for which the information is verified.
244 gboolean
lttvwindowtraces_get_in_progress(LttvAttributeName module_name
,
248 * Register the background computation hooks for a specific module. It adds the
249 * computation hooks to the global attrubutes, under "computation/module name"
251 * @param module_name A GQuark : the name of the module which computes the
254 void lttvwindowtraces_register_computation_hooks(LttvAttributeName module_name
,
255 LttvHooks
*before_chunk_traceset
,
256 LttvHooks
*before_chunk_trace
,
257 LttvHooks
*before_chunk_tracefile
,
258 LttvHooks
*after_chunk_traceset
,
259 LttvHooks
*after_chunk_trace
,
260 LttvHooks
*after_chunk_tracefile
,
261 LttvHooks
*before_request
,
262 LttvHooks
*after_request
,
263 LttvHooks
*event_hook
,
264 LttvHooksById
*event_hook_by_id
,
265 LttvHooks
*hook_adder
,
266 LttvHooks
*hook_remover
);
268 * Unregister the background computation hooks for a specific module.
270 * It also removes all the requests than can be currently processed by the
271 * background computation algorithm for all the traces (list_in and list_out).
273 * @param module_name A GQuark : the name of the module which computes the
277 void lttvwindowtraces_unregister_computation_hooks
278 (LttvAttributeName module_name
);
282 * It removes all the requests than can be currently processed by the
283 * background computation algorithm for all the traces (list_in and list_out).
285 * Leaves the flag to in_progress or none.. depending if current or queue
287 * @param module_name A GQuark : the name of the module which computes the
290 void lttvwindowtraces_unregister_requests(LttvAttributeName module_name
);
294 * Lock a trace so no other instance can use it.
296 * @param trace The trace to lock.
297 * @return 0 on success, -1 if cannot get lock.
299 gint
lttvwindowtraces_lock(LttvTrace
*trace
);
305 * @param trace The trace to unlock.
306 * @return 0 on success, -1 if cannot unlock (not locked ?).
308 gint
lttvwindowtraces_unlock(LttvTrace
*trace
);
311 * Verify if a trace is locked.
313 * @param trace The trace to verify.
314 * @return TRUE if locked, FALSE is unlocked.
316 gint
lttvwindowtraces_get_lock_state(LttvTrace
*trace
);
319 #endif //LTTVWINDOWTRACES_H