added API for calculators (module which calculate trace information)
[lttv.git] / ltt / branches / poly / lttv / modules / gui / lttvwindow / lttvwindow / lttvwindow.h
CommitLineData
501e4e70 1/* This file is part of the Linux Trace Toolkit Graphic User Interface
2 * Copyright (C) 2003-2004 Xiangxiu Yang, 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/*
20This file is what every viewer plugin writer should refer to.
21
22
23Module Related API
24
2d262115 25A viewer plugin is, before anything, a plugin. As a dynamically loadable
501e4e70 26module, it thus has an init and a destroy function called whenever it is
27loaded/initialized and unloaded/destroyed. A graphical module depends on
2d262115 28lttvwindow for construction of its viewer instances. In order to achieve
29this, it must register its constructor function to the main window along
30with button description or text menu entry description. A module keeps
31a list of every viewer that currently sits in memory so it can destroy
32them before the module gets unloaded/destroyed.
501e4e70 33
2d262115 34The contructor registration to the main windows adds button and menu
35entry to each main window, thus allowing instanciation of viewers.
501e4e70 36
37
38Main Window
39
2d262115 40The main window is a container that offers menus, buttons and a
41notebook. Some of those menus and buttons are part of the core of the
42main window, others are dynamically added and removed when modules are
43loaded/unloaded.
501e4e70 44
2d262115 45The notebook contains as much tabs as wanted. Each tab is linked with
46a set of traces (traceset). Each trace contains many tracefiles (one
47per cpu). A trace corresponds to a kernel being traced. A traceset
48corresponds to many traces read together. The time span of a traceset
49goes from the earliest start of all the traces to the latest end of all
50the traces.
501e4e70 51
52Inside each tab are added the viewers. When they interact with the main
53window through the lttvwindow API, they affect the other viewers located
54in the same tab as they are.
55
56The insertion of many viewers in a tab permits a quick look at all the
2d262115 57information wanted in a glance. The main window does merge the read
58requests from all the viewers in the same tab in a way that every viewer
59will get exactly the events it asked for, while the event reading loop
60and state update are shared. It improves performance of events delivery
61to the viewers.
501e4e70 62
63
64
65Viewer Instance Related API
66
2d262115 67The lifetime of a viewer is as follows. The viewer constructor function
68is called each time an instance view is created (one subwindow of this
69viewer type is created by the user either by clicking on the menu item
70or the button corresponding to the viewer). Thereafter, the viewer gets
71hooks called for different purposes by the window containing it. These
72hooks are detailed below. It also has to deal with GTK Events. Finally,
73it can be destructed by having its top level widget unreferenced by the
74main window or by any GTK Event causing a "destroy-event" signal on the
75its top widget. Another possible way for it do be destroyed is if the
76module gets unloaded. The module unload function will have to emit a
77"destroy" signal on each top level widget of all instances of its viewers.
501e4e70 78
79
80Notices from Main Window
81
82time_window : This is the time interval visible on the viewer's tab. Every
83 viewer that cares about being synchronised by respect to the
84 time with other viewers should register to this notification.
85 They should redraw all or part of their display when this occurs.
86
87traceset : This notification is called whenever a trace is added/removed
88 from the traceset. As it affects all the data displayed by the
89 viewer, it sould redraw itself totally.
90
91filter : FIXME : describe..
92
93current_time: Being able to zoom nearer a specific time or highlight a specific
94 time on every viewer in synchronicity implies that the viewer
95 has to shown a visual sign over the drawing or select an event
96 when it receives this notice. It should also inform the main
97 window with the appropriate report API function when a user
98 selects a specific time as being the current time.
99
100dividor : This notice links the positions of the horizontal dividors
101 between the graphic display zone of every viewer and their Y axis,
102 typically showing processes, cpus, ...
103
104
105FIXME : Add background computation explanation here
106background_init: prepare for background computation (comes after show_end).
107process_trace for background: done in small chunks in gtk_idle, hooks called.
108background_end: remove the hooks and perhaps update the window.
109
110
111Reporting Changes to the Main Window
112
2d262115 113In most cases, the enclosing window knows about updates such as described
114in the Notification section higher. There are a few cases, however, where
115updates are caused by actions known by a view instance. For example,
116clicking in a view may update the current time; all viewers within
117the same window must be told about the new current time to change the
118currently highlighted time point. A viewer reports such events by calling
119lttvwindow_report_current_time on its lttvwindow. The lttvwindow will
120consequently call current_time_notify for each of its contained viewers.
501e4e70 121
122
123Available report methods are :
124
125lttvwindow_report_status : reports the text of the status bar.
126lttvwindow_report_time_window : reports the new time window.
127lttvwindow_report_current_time : reports the new current time.
128lttvwindow_report_dividor : reports the new horizontal dividor's position.
129lttvwindow_report_focus : One on the widgets in the viewer has the keyboard's
130 focus from GTK.
131
132
133
134Requesting Events to Main Window
135
2d262115 136Events can be requested by passing a EventsRequest structure to the main
137window. They will be delivered later when the next g_idle functions
138will be called. Event delivery is done by calling the event hook for
139this event ID, or the main event hooks. A pointer to the EventsRequest
140structure is passed as hook_data to the event hooks of the viewers.
501e4e70 141
142EventsRequest consists in
143- a pointer to the viewer specific data structure
144- a start timestamp or position
145- a stop_flag, ending the read process when set to TRUE
146- a end timestamp and/or position and/or number of events to read
147- hook lists to call for traceset/trace/tracefile begin and end, and for each
148 event (event hooks and event_by_id hooks).
149
2d262115 150The main window will deliver events for every EventRequests it has
151pending through an algorithm that guarantee that all events requested,
152and only them, will be delivered to the viewer between the call of the
153tracefile_begin hooks and the call of the tracefile_end hooks.
501e4e70 154
2d262115 155If a viewer wants to stop the event request at a certain point inside the
156event hooks, it has to set the stop_flag to TRUE and return TRUE from the
157hook function. Then return value will stop the process traceset. Then,
158the main window will look for the stop_flag and remove the EventRequests
159from its lists, calling the process_traceset_end for this request (it
160removes hooks from the context and calls the after hooks).
501e4e70 161
2d262115 162It no stop_flag is rose, the end timestamp, end position or number
163of events to read has to be reached to determine the end of the
164request. Otherwise, the end of traceset does determine it.
501e4e70 165
166
167GTK Events
168
169Events and Signals
170
2d262115 171GTK is quite different from the other graphical toolkits around
172there. The main difference resides in that there are many X Windows
173inside one GtkWindow, instead of just one. That means that X events are
174delivered by the glib main loop directly to the widget corresponding to
175the GdkWindow affected by the X event.
501e4e70 176
2d262115 177Event delivery to a widget emits a signal on that widget. Then, if a
178handler is connected to this widget's signal, it will be executed. There
179are default handlers for signals, connected at class instantiation
180time. There is also the possibility to connect other handlers to these
181signals, which is what should be done in most cases when a viewer needs
182to interact with X in any way.
501e4e70 183
184
185
186Signal emission and propagation is described there :
187
188http://www.gtk.org/tutorial/sec-signalemissionandpropagation.html
189
190For further information on the GTK main loop (now a wrapper over glib main loop)
191see :
192
193http://developer.gnome.org/doc/API/2.0/gtk/gtk-General.html
194http://developer.gnome.org/doc/API/2.0/glib/glib-The-Main-Event-Loop.html
195
196
197For documentation on event handling in GTK/GDK, see :
198
199http://developer.gnome.org/doc/API/2.0/gdk/gdk-Events.html
200http://developer.gnome.org/doc/API/2.0/gdk/gdk-Event-Structures.html
201
202
203Signals can be connected to handlers, emitted, propagated, blocked,
204stopped. See :
205
206http://developer.gnome.org/doc/API/2.0/gobject/gobject-Signals.html
207
208
209
210
211The "expose_event"
212
213Provides the exposed region in the GdkEventExpose structure.
214
2d262115 215There are two ways of dealing with exposures. The first one is to directly
216draw on the screen and the second one is to draw in a pixmap buffer,
217and then to update the screen when necessary.
501e4e70 218
2d262115 219In the first case, the expose event will be responsible for registering
220hooks to process_traceset and require time intervals to the main
221window. So, in this scenario, if a part of the screen is damaged, the
222trace has to be read to redraw the screen.
501e4e70 223
2d262115 224In the second case, with a pixmap buffer, the expose handler is only
225responsible of showing the pixmap buffer on the screen. If the pixmap
226buffer has never been filled with a drawing, the expose handler may ask
227for it to be filled.
501e4e70 228
2d262115 229The interest of using events request to the main window instead of reading
230the events directly from the trace comes from the fact that the main
231window does merge requests from the different viewers in the same tab so
232that the read loop and the state update is shared. As viewers will, in
233the common scenario, request the same events, only one pass through the
234trace that will call the right hooks for the right intervals will be done.
501e4e70 235
2d262115 236When the traceset read is over for a events request, the traceset_end
237hook is called. It has the responsibility of finishing the drawing if
238some parts still need to be drawn and to show it on the screen (if the
239viewer uses a pixmap buffer).
501e4e70 240
241It can add dotted lines and such visual effects to enhance the user's
242experience.
243
244
245FIXME : explain other important events
246
247*/
248
249
250#ifndef VIEWER_H
251#define VIEWER_H
252
253/*! \file lttvwindow.h
254 * \brief API used by the graphical viewers to interact with their top window.
255 *
256 * Main window (lttvwindow module) is the place to contain and display viewers.
257 * Viewers (lttv plugins) interact with main window through this API.
258 * This header file should be included in each graphic module.
259 *
260 */
261
262#include <gtk/gtk.h>
263#include <ltt/ltt.h>
264#include <ltt/time.h>
265#include <lttv/hook.h>
266#include <lttv/tracecontext.h>
267#include <lttv/stats.h>
2d262115 268#include <lttvwindow/mainwindow.h>
269#include <lttvwindow/lttvfilter.h>
501e4e70 270//FIXME (not ready yet) #include <lttv/filter.h>
271
501e4e70 272/* Module Related API */
273
274
275/* constructor a the viewer */
276//FIXME explain LttvTracesetSelector and key
277typedef GtkWidget * (*lttvwindow_viewer_constructor)
278 (Tab *tab, LttvTracesetSelector * s, char *key);
279
280
281/**
282 * Function to register a view constructor so that main window can generate
283 * a menu item and a toolbar item for the viewer in order to generate a new
284 * instance easily. A menu entry and toolbar item will be added to each main
285 * window.
286 *
287 * It should be called by init function of the module.
288 *
289 * @param menu_path path of the menu item. NULL : no menu entry.
290 * @param menu_text text of the menu item.
291 * @param pixmap Image shown on the toolbar item. NULL : no button.
292 * @param tooltip tooltip of the toolbar item.
293 * @param view_constructor constructor of the viewer.
294 */
295
296void lttvwindow_register_constructor
297 (char * menu_path,
298 char * menu_text,
299 char ** pixmap,
300 char * tooltip,
301 lttvwindow_viewer_constructor view_constructor);
302
303
304/**
305 * Function to unregister the viewer's constructor, release the space
306 * occupied by menu_path, menu_text, pixmap, tooltip and constructor of the
307 * viewer.
308 *
309 * It will be called when a module is unloaded.
310 *
311 * @param view_constructor constructor of the viewer.
312 */
313
314void lttvwindow_unregister_constructor
315 (lttvwindow_viewer_constructor view_constructor);
316
317
318
319
320/* Viewer Instance Related API */
321
322/**
323 * Structure used as hook_data for the time_window_notify hook.
324 */
325typedef struct _TimeWindowNotifyData {
326 TimeWindow *new_time_window;
327 TimeWindow *old_time_window;
328} TimeWindowNotifyData;
329
330
331/**
332 * Function to register a hook function that will be called by the main window
333 * when the time interval needs to be updated.
334 *
335 * This register function is typically called by the constructor of the viewer.
336 *
337 * @param tab the tab the viewer belongs to.
338 * @param hook hook that sould be called by the main window when the time
339 * interval changes. This hook function takes a
340 * TimeWindowNotifyData* as call_data.
341 * @param hook_data hook data associated with the hook function. It will
342 * be typically a pointer to the viewer's data structure.
343 */
344
345void lttvwindow_register_time_window_notify(Tab *tab,
346 LttvHook hook,
347 gpointer hook_data);
348
349
350/**
351 * Function to unregister the time_window notification hook.
352 *
353 * This unregister function is typically called by the destructor of the viewer.
354 *
355 * @param tab the tab the viewer belongs to.
356 * @param hook hook that sould be called by the main window when the time
357 * interval changes. This hook function takes a
358 * TimeWindowNotifyData* as call_data.
359 * @param hook_data hook data associated with the hook function. It will
360 * be typically a pointer to the viewer's data structure.
361 */
362
363void lttvwindow_unregister_time_window_notify(Tab *tab,
364 LttvHook hook,
365 gpointer hook_data);
366
367
368/**
369 * Function to register a hook function that will be called by the main window
370 * when the traceset is changed. That means that the viewer must redraw
371 * itself completely or check if it's affected by the particular change to the
372 * traceset.
373 *
374 * This register function is typically called by the constructor of the viewer.
375 *
376 * @param tab the tab the viewer belongs to.
377 * @param hook hook that should be called whenever a change to the traceset
378 * occurs. The call_data of this hook is a NULL pointer.
379 * @param hook_data hook data associated with the hook function. It will
380 * be typically a pointer to the viewer's data structure.
381 */
382
383void lttvwindow_register_traceset_notify(Tab *tab,
384 LttvHook hook,
385 gpointer hook_data);
386
387
388/**
389 * Function to unregister the traceset_notify hook.
390 *
391 * @param tab the tab the viewer belongs to.
392 * @param hook hook that should be called whenever a change to the traceset
393 * occurs. The call_data of this hook is a NULL pointer.
394 * @param hook_data hook data associated with the hook function. It will
395 * be typically a pointer to the viewer's data structure.
396 */
397
398void lttvwindow_unregister_traceset_notify(Tab *tab,
399 LttvHook hook,
400 gpointer hook_data);
401
402
403/**
404 * Function to register a hook function for a viewer to set/update its
405 * filter.
406 *
407 * FIXME : Add information about what a filter is as seen from a viewer and how
408 * to use it.
409 *
410 * This register function is typically called by the constructor of the viewer.
411 *
412 * @param tab the tab the viewer belongs to.
413 * @param hook hook function called by the main window when a filter change
414 * occurs.
415 * @param hook_data hook data associated with the hook function. It will
416 * be typically a pointer to the viewer's data structure.
417 */
418
419void lttvwindow_register_filter_notify(Tab *tab,
420 LttvHook hook,
421 gpointer hook_data);
422
423
424/**
425 * Function to unregister a viewer's hook function which is used to
426 * set/update the filter of the viewer.
427 *
428 * This unregistration is called by the destructor of the viewer.
429 *
430 * @param tab the tab the viewer belongs to.
431 * @param hook hook function called by the main window when a filter change
432 * occurs.
433 * @param hook_data hook data associated with the hook function. It will
434 * be typically a pointer to the viewer's data structure.
435 */
436
437void lttvwindow_unregister_filter_notify(Tab *tab,
438 LttvHook hook,
439 gpointer hook_data);
440
441
442/**
443 * Function to register a hook function for a viewer to set/update its
444 * current time.
445 *
446 * @param tab the tab the viewer belongs to.
447 * @param hook hook function of the viewer that updates the current time. The
448 * call_data is a LttTime* representing the new current time.
449 * @param hook_data hook data associated with the hook function. It will
450 * be typically a pointer to the viewer's data structure.
451 */
452
453void lttvwindow_register_current_time_notify(Tab *tab,
454 LttvHook hook,
455 gpointer hook_data);
456
457
458/**
459 * Function to unregister a viewer's hook function which is used to
460 * set/update the current time of the viewer.
461 * @param tab the tab the viewer belongs to.
462 * @param hook hook function of the viewer that updates the current time. The
463 * call_data is a LttTime* representing the new current time.
464 * @param hook_data hook data associated with the hook function. It will
465 * be typically a pointer to the viewer's data structure.
466 */
467
468void lttvwindow_unregister_current_time_notify(Tab *tab,
469 LttvHook hook,
470 gpointer hook_data);
471
472
473/**
474 * Function to register a hook function for a viewer to set/update the
475 * dividor of the hpane. It provides a way to make the horizontal
476 * dividors of all the viewers linked together.
477 *
478 * @param tab the tab the viewer belongs to.
479 * @param hook hook function of the viewer that will be called whenever a
480 * dividor changes in another viewer. The call_data of this hook
481 * is a gint*. The value of the integer is the new position of the
482 * hpane dividor.
483 * @param hook_data hook data associated with the hook function. It will
484 * be typically a pointer to the viewer's data structure.
485 */
486
487void lttvwindow_register_dividor(Tab *tab,
488 LttvHook hook,
489 gpointer hook_data);
490
491
492/**
493 * Function to unregister a viewer's hook function which is used to
494 * set/update hpane's dividor of the viewer.
495 *
496 * @param tab the tab the viewer belongs to.
497 * @param hook hook function of the viewer that will be called whenever a
498 * dividor changes in another viewer. The call_data of this hook
499 * is a gint*. The value of the integer is the new position of the
500 * hpane dividor.
501 * @param hook_data hook data associated with the hook function. It will
502 * be typically a pointer to the viewer's data structure.
503 */
504
505void lttvwindow_unregister_dividor(Tab *tab,
506 LttvHook hook,
507 gpointer hook_data);
508
509
510
511/**
512 * This method reports the information to show on the status bar in the
513 * main window.
514 *
515 * @param tab the tab the viewer belongs to.
516 * @param info the message which will be shown in the status bar.
517 */
518
519void lttvwindow_report_status(Tab *tab, const char *info);
520
521
522/**
523 * Function to set the time interval of the current tab.a
524 *
525 * @param tab the tab the viewer belongs to.
526 * @param time_interval pointer to the time interval value.
527 */
528
529void lttvwindow_report_time_window(Tab *tab,
530 const TimeWindow *time_window);
531
532/**
533 * Function to set the current time/event of the current tab.
534 * It will be called by a viewer's signal handle associated with
535 * the button-release-event signal
536 * @param tab the tab the viewer belongs to.
537 * @param time a pointer where time is stored.
538 */
539
540void lttvwindow_report_current_time(Tab *tab,
541 const LttTime *time);
542
543
544/**
545 * Function to set the position of the hpane's dividor (viewer).
546 * It will typically be called by a viewer's signal handle associated
547 * with the motion_notify_event event/signal.
548 *
549 * @param tab the tab the viewer belongs to.
550 * @param position position of the hpane's dividor.
551 */
552
553void lttvwindow_report_dividor(Tab *tab, gint position);
554
555/**
556 * Function to set the focused viewer of the tab.
557 * It will be called by a viewer's signal handle associated with
558 * the grab_focus signal of all widgets in the viewer.
559 *
560 * @param tab the tab the viewer belongs to.
561 * @param top_widget the top widget containing all the other widgets of the
562 * viewer.
563 */
564void lttvwindow_report_focus(Tab *tab,
565 GtkWidget *top_widget);
566
567
568/* Structure sent to the events request hook */
569 /* Value considered as empty */
570typedef struct _EventsRequest {
2d262115 571 gpointer owner; /* Owner of the request */
501e4e70 572 gpointer viewer_data; /* Unset : NULL */
573 gboolean servicing; /* service in progress: TRUE */
574 LttTime start_time;/* Unset : { G_MAXUINT, G_MAXUINT }*/
575 LttvTracesetContextPosition *start_position; /* Unset : NULL */
576 gboolean stop_flag; /* Continue:TRUE Stop:FALSE */
577 LttTime end_time;/* Unset : { G_MAXUINT, G_MAXUINT } */
578 guint num_events; /* Unset : G_MAXUINT */
579 LttvTracesetContextPosition *end_position; /* Unset : NULL */
580 LttvHooks *before_chunk_traceset; /* Unset : NULL */
581 LttvHooks *before_chunk_trace; /* Unset : NULL */
582 LttvHooks *before_chunk_tracefile;/* Unset : NULL */
583 LttvHooks *event; /* Unset : NULL */
584 LttvHooksById *event_by_id; /* Unset : NULL */
585 LttvHooks *after_chunk_tracefile; /* Unset : NULL */
586 LttvHooks *after_chunk_trace; /* Unset : NULL */
587 LttvHooks *after_chunk_traceset; /* Unset : NULL */
588 LttvHooks *before_request; /* Unset : NULL */
2d262115 589 LttvHooks *after_request; /* Unset : NULL */
501e4e70 590} EventsRequest;
591
2d262115 592/* Maximum number of events to proceed at once in a chunk */
593#define CHUNK_NUM_EVENTS 50000
594
501e4e70 595
596/**
597 * Function to request data in a specific time interval to the main window. The
598 * event request servicing is differed until the glib idle functions are
599 * called.
600 *
601 * The viewer has to provide hooks that should be associated with the event
602 * request.
603 *
604 * Either start time or start position must be defined in a EventRequest
605 * structure for it to be valid.
606 *
607 * end_time, end_position and num_events can all be defined. The first one
608 * to occur will be used as end criterion.
20fde85f 609 *
610 * The events_request memory will be managed by the main window once its
611 * pointer is passed by this function.
501e4e70 612 *
613 * @param tab the tab the viewer belongs to.
614 * @param events_requested Details about the event request.
615 */
616
617void lttvwindow_events_request(Tab *tab,
20fde85f 618 EventsRequest *events_request);
501e4e70 619
620/**
621 * Function to remove data requests related to a viewer.
622 *
623 * The existing requests's viewer gpointer is compared to the pointer
624 * given in argument to establish which data request should be removed.
625 *
626 * @param tab the tab the viewer belongs to.
627 * @param viewer a pointer to the viewer data structure
628 */
629
630void lttvwindow_events_request_remove_all(Tab *tab,
631 gconstpointer viewer);
632
633
501e4e70 634/**
635 * Function to get the current time window of the current tab.
636 *
637 * @param tab the tab the viewer belongs to.
638 * @return a pointer to the current tab's time interval.
639 */
640
641const TimeWindow *lttvwindow_get_time_window(Tab *tab);
642
643
644/**
645 * Function to get the current time of the current tab.
646 *
647 * @param tab the tab the viewer belongs to.
648 * @return a pointer to the current tab's current time.
649 */
650
651const LttTime *lttvwindow_get_current_time(Tab *tab);
652
653
654/**
655 * Function to get the filter of the current tab.
656 * @param main_win, the main window the viewer belongs to.
657 * @param filter, a pointer to a filter.
658 */
659
660//FIXME
661typedef void lttv_filter;
662//FIXME
663const lttv_filter *lttvwindow_get_filter(Tab *tab);
664
665
666/**
667 * Function to get the stats of the traceset
668 * It must be non const so the viewer can modify it.
669 * FIXME : a set/get pair of functions would be more appropriate here.
670 * @param tab the tab the viewer belongs to.
671 * @return A pointer to Traceset statistics.
672 */
673
674LttvTracesetStats* lttvwindow_get_traceset_stats(Tab *tab);
675
676/**
677 * Function to get the context of the traceset
678 * It must be non const so the viewer can add and remove hooks from it.
679 * @param tab the tab the viewer belongs to.
680 * @return Context of the current tab.
681 */
682
683
684LttvTracesetContext* lttvwindow_get_traceset_context(Tab *tab);
685
686
687#endif //VIEWER_H
This page took 0.048611 seconds and 4 git commands to generate.