[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 */

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