[lttv.git] / ltt / branches / poly / lttv / modules / gui / lttvwindow / lttvwindow / lttvwindowtraces.h

/* This file is part of the Linux Trace Toolkit Graphic User Interface
 * Copyright (C) 2003-2004 Mathieu Desnoyers
 *
 * This program is free software; you can redistribute it and/or modify
 * it under the terms of the GNU General Public License Version 2 as
 * published by the Free Software Foundation;
 *
 * 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., 59 Temple Place - Suite 330, Boston, 
 * MA 02111-1307, USA.
 */

/* This file is the API used to launch any background computation on a trace */

/* lttvwindowtraces
 *
 * This API consists in two main parts. The first one is for the background
 * computation provider and the second is for the viewer which needs this
 * information.
 *
 * A computation provider, i.e. a statistics computation module or a state
 * computation module, have two things in common : they append data to a trace
 * in an extensible container (LttvAttributes). This extended information, once
 * computed, can be kept all along with the trace and does not need to be
 * recomputed : a computation done on a trace must result in a identical result
 * each time it is done.
 *
 * This API provides functions for computation provider to register their
 * computation functions (or computation functions insertion and removal
 * functions). Once the computation provider is registered with its module name,
 * extended computation for a trace can be requested by any viewer by specifying
 * the module name, as we will describe in a moment.
 *
 * A viewer which needs extended information about a trace must ask for it to be
 * computed by doing a background computation request. It may also ask to be
 * notified of the completion of its request by doing a notify request.
 *
 * Before asking for the computation, it must check for its readiness. If it is
 * ready, the information has already been computed, so it is ready to use. If
 * the information is not ready, in must check whether or not the processing of
 * this task is in progress. If it is, it must not do any background computation
 * request. It must only do a background notification request of the current
 * processing to be informed of its completion. If the information is not ready
 * and not being processed, then the viewer may do a background computation
 * request and add a notify request to the notify queue.
 *
 * When a context takes control of a trace, it must lock the trace. This is a
 * way of ensuring that not conflict will occur between two traceset contexts
 * and shared traces. It will generate an error if a context try to get a lock
 * on a trace what is not unlocked. Upon every trace locking,
 * lttv_process_traceset_synchronize_tracefiles should be used to resynchronize
 * the traces with the trace context information.
 *
 * The usefulness of the lock in this framework can be questionable in a
 * single threaded environment, but can be great in the eventuality of
 * multiple threads.
 * 
 */


#ifndef LTTVWINDOWTRACES_H
#define LTTVWINDOWTRACES_H

#include <ltt/time.h>
#include <glib.h>

typedef GQuark LttvTraceInfo;

extern LttvTraceInfo LTTV_TRACES,
              LTTV_COMPUTATION,
              LTTV_REQUESTS_QUEUE,
              LTTV_REQUESTS_CURRENT,
              LTTV_NOTIFY_QUEUE,
              LTTV_NOTIFY_CURRENT,
              LTTV_COMPUTATION_TRACESET,
              LTTV_COMPUTATION_TRACESET_CONTEXT,
              LTTV_BEFORE_CHUNK_TRACESET,
              LTTV_BEFORE_CHUNK_TRACE,
              LTTV_BEFORE_CHUNK_TRACEFILE,
              LTTV_AFTER_CHUNK_TRACESET,
              LTTV_AFTER_CHUNK_TRACE,
              LTTV_AFTER_CHUNK_TRACEFILE,
              LTTV_BEFORE_REQUEST,
              LTTV_AFTER_REQUEST,
              LTTV_EVENT_HOOK,
              LTTV_EVENT_HOOK_BY_ID,
              LTTV_HOOK_ADDER,
              LTTV_HOOK_REMOVER,
              LTTV_IN_PROGRESS,
              LTTV_READY,
              LTTV_LOCK;
              

/* Get a trace by its path name. 
 *
 * @param path path of the trace on the virtual file system.
 * @return Pointer to trace if found
 *        NULL is returned if the trace is not present
 */

LttvTrace *lttvwindowtraces_get_trace_by_name(gchar *path);

/* Get a trace by its number identifier */

LttvTrace *lttvwindowtraces_get_trace(guint num);

/* Total number of traces */

guint lttvwindowtraces_get_number();

/* Add a trace to the global attributes */

void lttvwindowtraces_add_trace(LttvTrace *trace);

/* Remove a trace from the global attributes */

void lttvwindowtraces_remove_trace(LttvTrace *trace);


/**
 * Function to request data from a specific trace
 *
 * The memory allocated for the request will be managed by the API.
 * 
 * @param trace the trace to compute
 * @param module_name the name of the module which registered global computation
 *                    hooks.
 */

void lttvwindowtraces_background_request_queue
                     (LttvTrace *trace, gchar *module_name);

/**
 * Remove a background request from a trace.
 *
 * This should ONLY be used by the modules which registered the global hooks
 * (module_name). If this is called by the viewers, it may lead to incomplete
 * and incoherent background processing information.
 *
 * Even if the module which deals with the hooks removes the background
 * requests, it may cause a problem if the module gets loaded again in the
 * session : the data will be partially calculated. The calculation function
 * must deal with this case correctly.
 * 
 * @param trace the trace to compute
 * @param module_name the name of the module which registered global computation
 *                    hooks.
 */

void lttvwindowtraces_background_request_remove
                     (LttvTrace *trace, gchar *module_name);
                     
/**
 * Register a callback to be called when requested data is passed in the next
 * queued background processing.
 * 
 * @param owner owner of the background notification
 * @param trace the trace computed
 * @param notify_time time when notification hooks must be called
 * @param notify_position position when notification hooks must be called
 * @param notify  Hook to call when the notify position is passed
 */

void lttvwindowtraces_background_notify_queue
 (gpointer                     owner,
  LttvTrace                   *trace,
  LttTime                      notify_time,
  const LttvTracesetContextPosition *notify_position,
  const LttvHooks                   *notify);

/**
 * Register a callback to be called when requested data is passed in the current
 * background processing.
 * 
 * @param owner owner of the background notification
 * @param trace the trace computed
 * @param notify_time time when notification hooks must be called
 * @param notify_position position when notification hooks must be called
 * @param notify  Hook to call when the notify position is passed
 */

void lttvwindowtraces_background_notify_current
 (gpointer                     owner,
  LttvTrace                   *trace,
  LttTime                      notify_time,
  const LttvTracesetContextPosition *notify_position,
  const LttvHooks                   *notify);

/**
 * Removes all the notifications requests from a specific viewer.
 * 
 * @param owner owner of the background notification
 */

void lttvwindowtraces_background_notify_remove(gpointer owner);


/**
 * Tells if the information computed by a module for a trace is ready.
 *
 * Must be checked before a background processing request.
 *
 * @param module_name A GQuark : the name of the module which computes the
 *                    information.
 * @param trace The trace for which the information is verified.
 */

gboolean lttvwindowtraces_get_ready(LttvAttributeName module_name,
                                    LttvTrace *trace);

/**
 * Tells if the information computed by a module for a trace is being processed.
 * 
 * Must be checked before a background processing request.
 *
 * If it is effectively processed, the typical thing to do is to call
 * lttvwindowtraces_background_notify_current to be notified when the current
 * processing will be over.
 *
 * @param module_name A GQuark : the name of the module which computes the
 *                    information.
 * @param trace The trace for which the information is verified.
 */

gboolean lttvwindowtraces_get_in_progress(LttvAttributeName module_name,
                                    LttvTrace *trace);

/**
 * Register the background computation hooks for a specific module. It adds the
 * computation hooks to the global attrubutes, under "computation/module name"
 *
 * @param module_name A GQuark : the name of the module which computes the
 *                    information.
 */
void lttvwindowtraces_register_computation_hooks(LttvAttributeName module_name,
                                          LttvHooks *before_chunk_traceset,
                                          LttvHooks *before_chunk_trace,
                                          LttvHooks *before_chunk_tracefile,
                                          LttvHooks *after_chunk_traceset,
                                          LttvHooks *after_chunk_trace,
                                          LttvHooks *after_chunk_tracefile,
                                          LttvHooks *before_request,
                                          LttvHooks *after_request,
                                          LttvHooks *event_hook,
                                          LttvHooksById *event_hook_by_id,
                                          LttvHooks *hook_adder,
                                          LttvHooks *hook_remover);
/**
 * Unregister the background computation hooks for a specific module.
 *
 * It also removes all the requests than can be currently processed by the
 * background computation algorithm for all the traces (list_in and list_out).
 *
 * @param module_name A GQuark : the name of the module which computes the
 *                    information.
 */

void lttvwindowtraces_unregister_computation_hooks
                                     (LttvAttributeName module_name);


/**
 * It removes all the requests than can be currently processed by the
 * background computation algorithm for all the traces (list_in and list_out).
 *
 * Leaves the flag to in_progress or none.. depending if current or queue
 *
 * @param module_name A GQuark : the name of the module which computes the
 *                    information.
 */
void lttvwindowtraces_unregister_requests(LttvAttributeName module_name);


/**
 * Lock a trace so no other instance can use it.
 *
 * @param trace The trace to lock.
 * @return 0 on success, -1 if cannot get lock.
 */
gint lttvwindowtraces_lock(LttvTrace *trace);


/**
 * Unlock a trace.
 *
 * @param trace The trace to unlock.
 * @return 0 on success, -1 if cannot unlock (not locked ?).
 */
gint lttvwindowtraces_unlock(LttvTrace *trace);

/**
 * Verify if a trace is locked.
 *
 * @param trace The trace to verify.
 * @return TRUE if locked, FALSE is unlocked.
 */
gint lttvwindowtraces_get_lock_state(LttvTrace *trace);


#endif //LTTVWINDOWTRACES_H
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
	15	* Foundation, Inc., 59 Temple Place - Suite 330, Boston,
	16	* MA 02111-1307, USA.
	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
	71	#include <ltt/time.h>
	72	#include <glib.h>
	73
	74	typedef GQuark LttvTraceInfo;
	75
	76	extern LttvTraceInfo LTTV_TRACES,
	77	LTTV_COMPUTATION,
	78	LTTV_REQUESTS_QUEUE,
	79	LTTV_REQUESTS_CURRENT,
	80	LTTV_NOTIFY_QUEUE,
8bc02ec8	81	LTTV_NOTIFY_CURRENT,
	82	LTTV_COMPUTATION_TRACESET,
	83	LTTV_COMPUTATION_TRACESET_CONTEXT,
	84	LTTV_BEFORE_CHUNK_TRACESET,
	85	LTTV_BEFORE_CHUNK_TRACE,
	86	LTTV_BEFORE_CHUNK_TRACEFILE,
	87	LTTV_AFTER_CHUNK_TRACESET,
	88	LTTV_AFTER_CHUNK_TRACE,
	89	LTTV_AFTER_CHUNK_TRACEFILE,
	90	LTTV_BEFORE_REQUEST,
	91	LTTV_AFTER_REQUEST,
	92	LTTV_EVENT_HOOK,
	93	LTTV_EVENT_HOOK_BY_ID,
313bd6fc	94	LTTV_HOOK_ADDER,
313bd6fc	95	LTTV_HOOK_REMOVER,
8bc02ec8	96	LTTV_IN_PROGRESS,
b052368a	97	LTTV_READY,
b052368a	98	LTTV_LOCK;
8bc02ec8	99
8bc02ec8	100
a1a2b649	101
	102	/* Get a trace by its path name.
	103	*
	104	* @param path path of the trace on the virtual file system.
	105	* @return Pointer to trace if found
	106	* NULL is returned if the trace is not present
	107	*/
	108
	109	LttvTrace lttvwindowtraces_get_trace_by_name(gchar path);
	110
	111	/* Get a trace by its number identifier */
	112
	113	LttvTrace *lttvwindowtraces_get_trace(guint num);
	114
	115	/* Total number of traces */
	116
	117	guint lttvwindowtraces_get_number();
	118
	119	/* Add a trace to the global attributes */
	120
	121	void lttvwindowtraces_add_trace(LttvTrace *trace);
	122
	123	/* Remove a trace from the global attributes */
	124
	125	void lttvwindowtraces_remove_trace(LttvTrace *trace);
	126
	127
	128	/**
	129	* Function to request data from a specific trace
	130	*
	131	* The memory allocated for the request will be managed by the API.
	132	*
	133	* @param trace the trace to compute
	134	* @param module_name the name of the module which registered global computation
	135	* hooks.
	136	*/
	137
	138	void lttvwindowtraces_background_request_queue
	139	(LttvTrace trace, gchar module_name);
	140
	141	/**
	142	* Remove a background request from a trace.
	143	*
	144	* This should ONLY be used by the modules which registered the global hooks
	145	* (module_name). If this is called by the viewers, it may lead to incomplete
	146	* and incoherent background processing information.
	147	*
	148	* Even if the module which deals with the hooks removes the background
	149	* requests, it may cause a problem if the module gets loaded again in the
	150	* session : the data will be partially calculated. The calculation function
	151	* must deal with this case correctly.
	152	*
	153	* @param trace the trace to compute
	154	* @param module_name the name of the module which registered global computation
	155	* hooks.
	156	*/
	157
	158	void lttvwindowtraces_background_request_remove
	159	(LttvTrace trace, gchar module_name);
	160
	161	/**
	162	* Register a callback to be called when requested data is passed in the next
	163	* queued background processing.
	164	*
165	* @param owner owner of the background notification
166	* @param trace the trace computed
167	* @param notify_time time when notification hooks must be called
168	* @param notify_position position when notification hooks must be called
169	* @param notify Hook to call when the notify position is passed
170	*/
171
172	void lttvwindowtraces_background_notify_queue
173	(gpointer owner,
174	LttvTrace *trace,
175	LttTime notify_time,
176	const LttvTracesetContextPosition *notify_position,
177	const LttvHooks *notify);
178
179	/**
180	* Register a callback to be called when requested data is passed in the current
181	* background processing.
182	*
183	* @param owner owner of the background notification
184	* @param trace the trace computed
185	* @param notify_time time when notification hooks must be called
186	* @param notify_position position when notification hooks must be called
187	* @param notify Hook to call when the notify position is passed
188	*/
189
190	void lttvwindowtraces_background_notify_current
191	(gpointer owner,
192	LttvTrace *trace,
193	LttTime notify_time,
194	const LttvTracesetContextPosition *notify_position,
195	const LttvHooks *notify);
196
197	/**
198	* Removes all the notifications requests from a specific viewer.
199	*
200	* @param owner owner of the background notification
201	*/
202
203	void lttvwindowtraces_background_notify_remove(gpointer owner);
204
205
e62a7964	206	/**
	207	* Tells if the information computed by a module for a trace is ready.
	208	*
	209	* Must be checked before a background processing request.
	210	*
	211	* @param module_name A GQuark : the name of the module which computes the
	212	* information.
	213	* @param trace The trace for which the information is verified.
	214	*/
	215
	216	gboolean lttvwindowtraces_get_ready(LttvAttributeName module_name,
	217	LttvTrace *trace);
	218
	219	/**
	220	* Tells if the information computed by a module for a trace is being processed.
	221	*
	222	* Must be checked before a background processing request.
	223	*
	224	* If it is effectively processed, the typical thing to do is to call
	225	* lttvwindowtraces_background_notify_current to be notified when the current
	226	* processing will be over.
	227	*
	228	* @param module_name A GQuark : the name of the module which computes the
	229	* information.
	230	* @param trace The trace for which the information is verified.
	231	*/
	232
	233	gboolean lttvwindowtraces_get_in_progress(LttvAttributeName module_name,
	234	LttvTrace *trace);
	235
	236	/**
	237	* Register the background computation hooks for a specific module. It adds the
	238	* computation hooks to the global attrubutes, under "computation/module name"
	239	*
	240	* @param module_name A GQuark : the name of the module which computes the
	241	* information.
	242	*/
	243	void lttvwindowtraces_register_computation_hooks(LttvAttributeName module_name,
	244	LttvHooks *before_chunk_traceset,
	245	LttvHooks *before_chunk_trace,
	246	LttvHooks *before_chunk_tracefile,
	247	LttvHooks *after_chunk_traceset,
	248	LttvHooks *after_chunk_trace,
	249	LttvHooks *after_chunk_tracefile,
	250	LttvHooks *before_request,
	251	LttvHooks *after_request,
	252	LttvHooks *event_hook,
313bd6fc	253	LttvHooksById *event_hook_by_id,
	254	LttvHooks *hook_adder,
	255	LttvHooks *hook_remover);
e62a7964	256	/**
	257	* Unregister the background computation hooks for a specific module.
	258	*
	259	* It also removes all the requests than can be currently processed by the
	260	* background computation algorithm for all the traces (list_in and list_out).
	261	*
	262	* @param module_name A GQuark : the name of the module which computes the
	263	* information.
	264	*/
	265
	266	void lttvwindowtraces_unregister_computation_hooks
	267	(LttvAttributeName module_name);
	268
	269
	270	/**
	271	* It 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	* Leaves the flag to in_progress or none.. depending if current or queue
	275	*
	276	* @param module_name A GQuark : the name of the module which computes the
	277	* information.
	278	*/
	279	void lttvwindowtraces_unregister_requests(LttvAttributeName module_name);
	280
	281
b052368a	282	/**
	283	* Lock a trace so no other instance can use it.
	284	*
	285	* @param trace The trace to lock.
	286	* @return 0 on success, -1 if cannot get lock.
	287	*/
	288	gint lttvwindowtraces_lock(LttvTrace *trace);
	289
	290
	291	/**
	292	* Unlock a trace.
	293	*
	294	* @param trace The trace to unlock.
	295	* @return 0 on success, -1 if cannot unlock (not locked ?).
	296	*/
	297	gint lttvwindowtraces_unlock(LttvTrace *trace);
	298
	299	/**
	300	* Verify if a trace is locked.
	301	*
	302	* @param trace The trace to verify.
	303	* @return TRUE if locked, FALSE is unlocked.
	304	*/
	305	gint lttvwindowtraces_get_lock_state(LttvTrace *trace);
	306
	307
a1a2b649	308	#endif //LTTVWINDOWTRACES_H