lttv/modules/gui/lttvwindow/lttvwindow/lttvwindow.h

   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 /*
  20 This file is what every viewer plugin writer should refer to.
  21
  22
  23 Module Related API
  24
  25 A viewer plugin is, before anything, a plugin. As a dynamically loadable
  26 module, it thus has an init and a destroy function called whenever it is
  27 loaded/initialized and unloaded/destroyed. A graphical module depends on
  28 lttvwindow for construction of its viewer instances. In order to achieve
  29 this, it must register its constructor function to the main window along
  30 with button description or text menu entry description. A module keeps
  31 a list of every viewer that currently sits in memory so it can destroy
  32 them before the module gets unloaded/destroyed.
  33
  34 The contructor registration to the main windows adds button and menu
  35 entry to each main window, thus allowing instanciation of viewers.
  36
  37
  38 Main Window
  39
  40 The main window is a container that offers menus, buttons and a
  41 notebook. Some of those menus and buttons are part of the core of the
  42 main window, others are dynamically added and removed when modules are
  43 loaded/unloaded.
  44
  45 The notebook contains as much tabs as wanted. Each tab is linked with
  46 a set of traces (traceset). Each trace contains many tracefiles (one
  47 per cpu).  A trace corresponds to a kernel being traced. A traceset
  48 corresponds to many traces read together. The time span of a traceset
  49 goes from the earliest start of all the traces to the latest end of all
  50 the traces.
  51
  52 Inside each tab are added the viewers. When they interact with the main
  53 window through the lttvwindow API, they affect the other viewers located
  54 in the same tab as they are.
  55
  56 The insertion of many viewers in a tab permits a quick look at all the
  57 information wanted in a glance. The main window does merge the read
  58 requests from all the viewers in the same tab in a way that every viewer
  59 will get exactly the events it asked for, while the event reading loop
  60 and state update are shared. It improves performance of events delivery
  61 to the viewers.
  62
  63
  64
  65 Viewer Instance Related API
  66
  67 The lifetime of a viewer is as follows. The viewer constructor function
  68 is called each time an instance view is created (one subwindow of this
  69 viewer type is created by the user either by clicking on the menu item
  70 or the button corresponding to the viewer). Thereafter, the viewer gets
  71 hooks called for different purposes by the window containing it. These
  72 hooks are detailed below. It also has to deal with GTK Events. Finally,
  73 it can be destructed by having its top level widget unreferenced by the
  74 main window or by any GTK Event causing a "destroy-event" signal on the
  75 its top widget. Another possible way for it do be destroyed is if the
  76 module 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.
  78
  79
  80 Notices from Main Window
  81
  82 time_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
  87 traceset :    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
  91 filter :      FIXME : describe..
  92
  93 current_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
 100 dividor :     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
 105 Reporting Changes to the Main Window
 106
 107 In most cases, the enclosing window knows about updates such as described
 108 in the Notification section higher. There are a few cases, however, where
 109 updates are caused by actions known by a view instance. For example,
 110 clicking in a view may update the current time; all viewers within
 111 the same window must be told about the new current time to change the
 112 currently highlighted time point. A viewer reports such events by calling
 113 lttvwindow_report_current_time on its lttvwindow.  The lttvwindow will
 114 consequently call current_time_notify for each of its contained viewers.
 115
 116
 117 Available report methods are :
 118
 119 lttvwindow_report_time_window : reports the new time window.
 120 lttvwindow_report_current_time : reports the new current time.
 121 lttvwindow_report_dividor : reports the new horizontal dividor's position.
 122 lttvwindow_report_filter : reports the new filter object
 123
 124
 125
 126 Requesting Events to Main Window
 127
 128 Events can be requested by passing a EventsRequest structure to the main
 129 window.  They will be delivered later when the next g_idle functions
 130 will be called.  Event delivery is done by calling the event hook for
 131 this event ID, or the main event hooks. A pointer to the EventsRequest
 132 structure is passed as hook_data to the event hooks of the viewers.
 133
 134 EventsRequest consists in
 135 - a pointer to the viewer specific data structure
 136 - a start timestamp or position
 137 - a stop_flag, ending the read process when set to TRUE
 138 - a end timestamp and/or position and/or number of events to read
 139 - hook lists to call for traceset/trace/tracefile begin and end, and for each
 140   event (event hooks and event_by_id_channel hooks).
 141
 142 The main window will deliver events for every EventRequests it has
 143 pending through an algorithm that guarantee that all events requested,
 144 and only them, will be delivered to the viewer between the call of the
 145 tracefile_begin hooks and the call of the tracefile_end hooks.
 146
 147 If a viewer wants to stop the event request at a certain point inside the
 148 event hooks, it has to set the stop_flag to TRUE and return TRUE from the
 149 hook function. Then return value will stop the process traceset. Then,
 150 the main window will look for the stop_flag and remove the EventRequests
 151 from its lists, calling the process_traceset_end for this request (it
 152 removes hooks from the context and calls the after hooks).
 153
 154 It no stop_flag is risen, the end timestamp, end position or number
 155 of events to read has to be reached to determine the end of the
 156 request. Otherwise, the end of traceset does determine it.
 157
 158
 159 GTK Events
 160
 161 Events and Signals
 162
 163 GTK is quite different from the other graphical toolkits around
 164 there. The main difference resides in that there are many X Windows
 165 inside one GtkWindow, instead of just one. That means that X events are
 166 delivered by the glib main loop directly to the widget corresponding to
 167 the GdkWindow affected by the X event.
 168
 169 Event delivery to a widget emits a signal on that widget. Then, if a
 170 handler is connected to this widget's signal, it will be executed. There
 171 are default handlers for signals, connected at class instantiation
 172 time. There is also the possibility to connect other handlers to these
 173 signals, which is what should be done in most cases when a viewer needs
 174 to interact with X in any way.
 175
 176
 177
 178 Signal emission and propagation is described there :
 179
 180 http://www.gtk.org/tutorial/sec-signalemissionandpropagation.html
 181
 182 For further information on the GTK main loop (now a wrapper over glib main loop)
 183 see :
 184
 185 http://developer.gnome.org/doc/API/2.0/gtk/gtk-General.html
 186 http://developer.gnome.org/doc/API/2.0/glib/glib-The-Main-Event-Loop.html
 187
 188
 189 For documentation on event handling in GTK/GDK, see :
 190
 191 http://developer.gnome.org/doc/API/2.0/gdk/gdk-Events.html
 192 http://developer.gnome.org/doc/API/2.0/gdk/gdk-Event-Structures.html
 193
 194
 195 Signals can be connected to handlers, emitted, propagated, blocked,
 196 stopped. See :
 197
 198 http://developer.gnome.org/doc/API/2.0/gobject/gobject-Signals.html
 199
 200
 201
 202
 203 The "expose_event"
 204
 205 Provides the exposed region in the GdkEventExpose structure.
 206
 207 There are two ways of dealing with exposures. The first one is to directly
 208 draw on the screen and the second one is to draw in a pixmap buffer,
 209 and then to update the screen when necessary.
 210
 211 In the first case, the expose event will be responsible for registering
 212 hooks to process_traceset and require time intervals to the main
 213 window. So, in this scenario, if a part of the screen is damaged, the
 214 trace has to be read to redraw the screen.
 215
 216 In the second case, with a pixmap buffer, the expose handler is only
 217 responsible of showing the pixmap buffer on the screen. If the pixmap
 218 buffer has never been filled with a drawing, the expose handler may ask
 219 for it to be filled.
 220
 221 The interest of using events request to the main window instead of reading
 222 the events directly from the trace comes from the fact that the main
 223 window does merge requests from the different viewers in the same tab so
 224 that the read loop and the state update is shared. As viewers will, in
 225 the common scenario, request the same events, only one pass through the
 226 trace that will call the right hooks for the right intervals will be done.
 227
 228 When the traceset read is over for a events request, the traceset_end
 229 hook is called. It has the responsibility of finishing the drawing if
 230 some parts still need to be drawn and to show it on the screen (if the
 231 viewer uses a pixmap buffer).
 232
 233 It can add dotted lines and such visual effects to enhance the user's
 234 experience.
 235
 236
 237 FIXME : explain other important events
 238
 239 */
 240
 241
 242 #ifndef LTTVWINDOW_H
 243 #define LTTVWINDOW_H
 244
 245 /*! \file lttvwindow.h
 246  * \brief API used by the graphical viewers to interact with their top window.
 247  *
 248  * Main window (lttvwindow module) is the place to contain and display viewers.
 249  * Viewers (lttv plugins) interact with main window through this API.
 250  * This header file should be included in each graphic module.
 251  *
 252  */
 253
 254 #include <gtk/gtk.h>
 255 #include <lttv/traceset.h>
 256 #include <lttv/hook.h>
 257 #ifdef BABEL_CLEANUP
 258 #include <lttv/stats.h>
 259 #include <lttv/filter.h>
 260 #endif /* BABEL_CLEANUP */
 261 #include <lttvwindow/mainwindow.h>
 262 #include <lttvwindow/lttv_plugin.h>
 263
 264 /* Module Related API */
 265
 266 /* GQuark containing constructors of viewers in global attributes */
 267 extern GQuark LTTV_VIEWER_CONSTRUCTORS;
 268
 269 /* constructor a the viewer */
 270 typedef GtkWidget* (*lttvwindow_viewer_constructor)(LttvPlugin *plugin);
 271
 272 extern gint lttvwindow_preempt_count;
 273
 274 #define CHECK_GDK_INTERVAL 50000
 275
 276 /**
 277  * Function to register a view constructor so that main window can generate
 278  * a menu item and a toolbar item for the viewer in order to generate a new
 279  * instance easily. A menu entry and toolbar item will be added to each main
 280  * window.
 281  *
 282  * It should be called by init function of the module.
 283  *
 284  * @param name name of the viewer : mainly used as tag for constructor
 285  * @param menu_path path of the menu item. NULL : no menu entry.
 286  * @param menu_text text of the menu item.
 287  * @param pixmap Image shown on the toolbar item. NULL : no button.
 288  * @param tooltip tooltip of the toolbar item.
 289  * @param view_constructor constructor of the viewer.
 290  */
 291
 292 void lttvwindow_register_constructor
 293                             (char * name,
 294                              char *  menu_path,
 295                              char *  menu_text,
 296                              char ** pixmap,
 297                              char *  tooltip,
 298                              lttvwindow_viewer_constructor view_constructor);
 299
 300
 301 /**
 302  * Function to unregister the viewer's constructor, release the space
 303  * occupied by menu_path, menu_text, pixmap, tooltip and constructor of the
 304  * viewer.
 305  *
 306  * It will be called when a module is unloaded.
 307  *
 308  * @param view_constructor constructor of the viewer.
 309  */
 310
 311 void lttvwindow_unregister_constructor
 312                             (lttvwindow_viewer_constructor view_constructor);
 313
 314
 315
 316
 317 /* Viewer Instance Related API */
 318
 319 /**
 320  * Structure used as hook_data for the time_window_notify hook.
 321  */
 322 typedef struct _TimeWindowNotifyData {
 323   TimeWindow *new_time_window;
 324   TimeWindow *old_time_window;
 325 } TimeWindowNotifyData;
 326
 327
 328 /**
 329  * Function to register a hook function that will be called by the main window
 330  * when the time interval needs to be updated.
 331  *
 332  * This register function is typically called by the constructor of the viewer.
 333  *
 334  * @param tab the tab the viewer belongs to.
 335  * @param hook hook that sould be called by the main window when the time
 336  *             interval changes. This hook function takes a
 337  *             TimeWindowNotifyData* as call_data.
 338  * @param hook_data hook data associated with the hook function. It will
 339  *                  be typically a pointer to the viewer's data structure.
 340  */
 341
 342 void lttvwindow_register_time_window_notify(Tab *tab,
 343                                             LttvHook    hook,
 344                                             gpointer    hook_data);
 345
 346
 347 /**
 348  * Function to unregister the time_window notification hook.
 349  *
 350  * This unregister function is typically called by the destructor of the viewer.
 351  *
 352  * @param tab the tab the viewer belongs to.
 353  * @param hook hook that sould be called by the main window when the time
 354  *             interval changes. This hook function takes a
 355  *             TimeWindowNotifyData* as call_data.
 356  * @param hook_data hook data associated with the hook function. It will
 357  *                  be typically a pointer to the viewer's data structure.
 358  */
 359
 360 void lttvwindow_unregister_time_window_notify(Tab *tab,
 361                                               LttvHook    hook,
 362                                               gpointer    hook_data);
 363
 364 /**
 365  * Function to register a hook function that will be called by the main window
 366  * when the time span of the traceset is updated.
 367  *
 368  * This register function is typically called by the constructor of the viewer.
 369  *
 370  * @param tab the tab the viewer belongs to.
 371  * @param hook hook that sould be called by the main window when the time
 372  *             interval changes.
 373  * @param hook_data hook data associated with the hook function. It will
 374  *                  be typically a pointer to the viewer's data structure.
 375  */
 376 void lttvwindow_register_timespan_notify(Tab *tab,
 377                                             LttvHook    hook,
 378                                             gpointer    hook_data);
 379
 380 /**
 381  * Function to unregister the time_span notification hook.
 382  *
 383  * This unregister function is typically called by the destructor of the viewer.
 384  *
 385  * @param tab the tab the viewer belongs to.
 386  * @param hook hook that sould be called by the main window when the time
 387  *             interval changes.
 388  * @param hook_data hook data associated with the hook function. It will
 389  *                  be typically a pointer to the viewer's data structure.
 390  */
 391 void lttvwindow_unregister_timespan_notify(Tab *tab,
 392                                             LttvHook    hook,
 393                                             gpointer    hook_data);
 394
 395 /**
 396  * Function to register a hook function that will be called by the main window
 397  * when the traceset is changed. That means that the viewer must redraw
 398  * itself completely or check if it's affected by the particular change to the
 399  * traceset.
 400  *
 401  * This register function is typically called by the constructor of the viewer.
 402  *
 403  * @param tab the tab the viewer belongs to.
 404  * @param hook hook that should be called whenever a change to the traceset
 405  *             occurs. The call_data of this hook is a NULL pointer.
 406  * @param hook_data hook data associated with the hook function. It will
 407  *                  be typically a pointer to the viewer's data structure.
 408  */
 409
 410 void lttvwindow_register_traceset_notify(Tab *tab,
 411                                          LttvHook    hook,
 412                                          gpointer    hook_data);
 413
 414
 415 /**
 416  * Function to unregister the traceset_notify hook.
 417  *
 418  * @param tab the tab the viewer belongs to.
 419  * @param hook hook that should be called whenever a change to the traceset
 420  *             occurs. The call_data of this hook is a NULL pointer.
 421  * @param hook_data hook data associated with the hook function. It will
 422  *                  be typically a pointer to the viewer's data structure.
 423  */
 424
 425 void lttvwindow_unregister_traceset_notify(Tab *tab,
 426                                            LttvHook    hook,
 427                                            gpointer    hook_data);
 428
 429
 430 /**
 431  * Function to register a hook function for a viewer be completely redrawn.
 432  *
 433  * @param tab viewer's tab
 434  * @param hook hook function of the viewer.
 435  * @param hook_data hook data associated with the hook function.
 436  */
 437
 438 void lttvwindow_register_redraw_notify(Tab *tab,
 439     LttvHook hook, gpointer hook_data);
 440
 441 /**
 442  * Function to unregister a hook function for a viewer be completely redrawn.
 443  *
 444  * @param tab viewer's tab
 445  * @param hook hook function of the viewer.
 446  * @param hook_data hook data associated with the hook function.
 447  */
 448
 449 void lttvwindow_unregister_redraw_notify(Tab *tab,
 450               LttvHook hook, gpointer hook_data);
 451
 452
 453 /**
 454  * Function to register a hook function for a viewer to re-do the events
 455  * requests for the needed interval.
 456  *
 457  * This action is typically done after a "stop".
 458  *
 459  * The typical hook will remove all current requests for the viewer
 460  * and make requests for missing information.
 461  *
 462  * @param tab viewer's tab
 463  * @param hook hook function of the viewer.
 464  * @param hook_data hook data associated with the hook function.
 465  */
 466
 467 void lttvwindow_register_continue_notify(Tab *tab,
 468     LttvHook hook, gpointer hook_data);
 469
 470
 471 /**
 472  * Function to unregister a hook function for a viewer to re-do the events
 473  * requests for the needed interval.
 474  *
 475  * @param tab viewer's tab
 476  * @param hook hook function of the viewer.
 477  * @param hook_data hook data associated with the hook function.
 478  */
 479
 480 void lttvwindow_unregister_continue_notify(Tab *tab,
 481               LttvHook hook, gpointer hook_data);
 482
 483
 484 /**
 485  * Function to register a hook function for a viewer to set/update its
 486  * filter.
 487  *
 488  * FIXME : Add information about what a filter is as seen from a viewer and how
 489  * to use it.
 490  *
 491  * This register function is typically called by the constructor of the viewer.
 492  *
 493  * @param tab the tab the viewer belongs to.
 494  * @param hook hook function called by the main window when a filter change
 495  *             occurs.
 496  * @param hook_data hook data associated with the hook function. It will
 497  *                  be typically a pointer to the viewer's data structure.
 498  */
 499
 500 void lttvwindow_register_filter_notify(Tab *tab,
 501                                        LttvHook    hook,
 502                                        gpointer    hook_data);
 503
 504
 505 /**
 506  * Function to unregister a viewer's hook function which is used to
 507  * set/update the filter of the viewer.
 508  *
 509  * This unregistration is called by the destructor of the viewer.
 510  *
 511  * @param tab the tab the viewer belongs to.
 512  * @param hook hook function called by the main window when a filter change
 513  *             occurs.
 514  * @param hook_data hook data associated with the hook function. It will
 515  *                  be typically a pointer to the viewer's data structure.
 516  */
 517
 518 void lttvwindow_unregister_filter_notify(Tab *tab,
 519                                          LttvHook     hook,
 520                                          gpointer     hook_data);
 521
 522
 523 /**
 524  * Function to get the current filter of the main window : useful at viewer
 525  * instanciation.
 526  *
 527  * @param tab the tab the viewer belongs to.
 528  *
 529  * returns : the current filter.
 530  */
 531
 532
 533 LttvFilter *lttvwindow_get_filter(Tab *tab);
 534
 535 /**
 536  * Function to register a hook function for a viewer to set/update its
 537  * current time.
 538  *
 539  * @param tab the tab the viewer belongs to.
 540  * @param hook hook function of the viewer that updates the current time. The
 541  *             call_data is a LttTime* representing the new current time.
 542  * @param hook_data hook data associated with the hook function. It will
 543  *                  be typically a pointer to the viewer's data structure.
 544  */
 545
 546 void lttvwindow_register_current_time_notify(Tab *tab,
 547                                              LttvHook    hook,
 548                                              gpointer    hook_data);
 549
 550
 551 /**
 552  * Function to unregister a viewer's hook function which is used to
 553  * set/update the current time of the viewer.
 554  * @param tab the tab the viewer belongs to.
 555  * @param hook hook function of the viewer that updates the current time. The
 556  *             call_data is a LttTime* representing the new current time.
 557  * @param hook_data hook data associated with the hook function. It will
 558  *                  be typically a pointer to the viewer's data structure.
 559  */
 560
 561 void lttvwindow_unregister_current_time_notify(Tab *tab,
 562                                                LttvHook    hook,
 563                                                gpointer    hook_data);
 564
 565 /**
 566  * Function to register a hook function for a viewer to set/update its
 567  * current position.
 568  *
 569  * @param tab the tab the viewer belongs to.
 570  * @param hook hook function of the viewer that updates the current time. The
 571  *             call_data is a LttTime* representing the new current time.
 572  * @param hook_data hook data associated with the hook function. It will
 573  *                  be typically a pointer to the viewer's data structure.
 574  */
 575
 576 void lttvwindow_register_current_position_notify(Tab *tab,
 577                                              LttvHook    hook,
 578                                              gpointer    hook_data);
 579
 580
 581 /**
 582  * Function to unregister a viewer's hook function which is used to
 583  * set/update the current position of the viewer.
 584  * @param tab the tab the viewer belongs to.
 585  * @param hook hook function of the viewer that updates the current time. The
 586  *             call_data is a LttTime* representing the new current time.
 587  * @param hook_data hook data associated with the hook function. It will
 588  *                  be typically a pointer to the viewer's data structure.
 589  */
 590
 591 void lttvwindow_unregister_current_position_notify(Tab *tab,
 592                                                LttvHook    hook,
 593                                                gpointer    hook_data);
 594
 595
 596
 597 /**
 598  * Function to register a hook function for a viewer to set/update the
 599  * dividor of the hpane. It provides a way to make the horizontal
 600  * dividors of all the viewers linked together.
 601  *
 602  * @param tab the tab the viewer belongs to.
 603  * @param hook hook function of the viewer that will be called whenever a
 604  *             dividor changes in another viewer. The call_data of this hook
 605  *             is a gint*. The value of the integer is the new position of the
 606  *             hpane dividor.
 607  * @param hook_data hook data associated with the hook function. It will
 608  *                  be typically a pointer to the viewer's data structure.
 609  */
 610
 611 void lttvwindow_register_dividor(Tab *tab,
 612                                  LttvHook    hook,
 613                                  gpointer    hook_data);
 614
 615
 616 /**
 617  * Function to unregister a viewer's hook function which is used to
 618  * set/update hpane's dividor of the viewer.
 619  *
 620  * @param tab the tab the viewer belongs to.
 621  * @param hook hook function of the viewer that will be called whenever a
 622  *             dividor changes in another viewer. The call_data of this hook
 623  *             is a gint*. The value of the integer is the new position of the
 624  *             hpane dividor.
 625  * @param hook_data hook data associated with the hook function. It will
 626  *                  be typically a pointer to the viewer's data structure.
 627  */
 628
 629 void lttvwindow_unregister_dividor(Tab *tab,
 630                                    LttvHook    hook,
 631                                    gpointer    hook_data);
 632
 633
 634
 635 /**
 636  * Function to set the time interval of the current tab.a
 637  *
 638  * @param tab the tab the viewer belongs to.
 639  * @param time_interval new time window.
 640  */
 641
 642 void lttvwindow_report_time_window(Tab *tab,
 643                                    TimeWindow time_window);
 644
 645 /**
 646  * Function to set the current time of the current tab.
 647  * It will be called by a viewer's signal handle associated with
 648  * the button-release-event signal
 649  * @param tab the tab the viewer belongs to.
 650  * @param time current time.
 651  */
 652
 653 void lttvwindow_report_current_time(Tab *tab,
 654                                     LttTime time);
 655
 656
 657 /**
 658  * Function to set the current event of the current tab.
 659  * It will be called by a viewer's signal handle associated with
 660  * the button-release-event signal
 661  * @param tab the tab the viewer belongs to.
 662  * @param pos the current position.
 663  */
 664
 665 void lttvwindow_report_current_position(Tab *tab,
 666                                         LttvTracesetPosition *pos);
 667
 668 /**
 669  * Function to set the position of the hpane's dividor (viewer).
 670  * It will typically be called by a viewer's signal handle associated
 671  * with the motion_notify_event event/signal.
 672  *
 673  * @param tab the tab the viewer belongs to.
 674  * @param position position of the hpane's dividor.
 675  */
 676
 677 void lttvwindow_report_dividor(Tab *tab, gint position);
 678
 679
 680 /* Structure sent to the events request hook */
 681                                                 /* Value considered as empty*/
 682 typedef struct _EventsRequest {
 683   gpointer                     owner;           /* Owner of the request     */
 684   gpointer                     viewer_data;     /* Unset : NULL             */
 685   gboolean                     servicing;       /* service in progress: TRUE*/
 686   LttTime                      start_time;      /* Unset : ltt_time_infinite*/
 687   LttvTracesetPosition *start_position;  /* Unset : NULL             */
 688   gboolean                     stop_flag;       /* Continue:TRUE Stop:FALSE */
 689   LttTime                      end_time;        /* Unset : ltt_time_infinite*/
 690   guint                        num_events;      /* Unset : G_MAXUINT        */
 691   LttvTracesetPosition *end_position;    /* Unset : NULL             */
 692   gint                         trace;           /* unset : -1               */
 693   GArray                      *hooks;           /* Unset : NULL             */
 694   LttvHooks                   *before_chunk_traceset; /* Unset : NULL       */
 695   LttvHooks                   *before_chunk_trace;    /* Unset : NULL       */
 696   LttvHooks                   *before_chunk_tracefile;/* Unset : NULL       */
 697   LttvHooks                   *event;           /* Unset : NULL             */
 698   LttvHooks                   *after_chunk_tracefile; /* Unset : NULL       */
 699   LttvHooks                   *after_chunk_trace;     /* Unset : NULL       */
 700   LttvHooks                   *after_chunk_traceset;  /* Unset : NULL       */
 701   LttvHooks                   *before_request;  /* Unset : NULL             */
 702   LttvHooks                   *after_request;   /* Unset : NULL             */
 703 } EventsRequest;
 704
 705 /* Maximum number of events to proceed at once in a chunk */
 706 // TODO ybrosseau, temporarly disable the chunking of event request
 707 //     to solve a bug in the event state stability
 708 #define CHUNK_NUM_EVENTS G_MAXUINT
 709
 710
 711 /**
 712  * Function to request data in a specific time interval to the main window. The
 713  * event request servicing is differed until the glib idle functions are
 714  * called.
 715  *
 716  * The viewer has to provide hooks that should be associated with the event
 717  * request.
 718  *
 719  * Either start time or start position must be defined in a EventRequest
 720  * structure for it to be valid.
 721  *
 722  * end_time, end_position and num_events can all be defined. The first one
 723  * to occur will be used as end criterion.
 724  *
 725  * The events_request memory will be managed by the main window once its
 726  * pointer is passed by this function.
 727  *
 728  * @param tab the tab the viewer belongs to.
 729  * @param events_requested Details about the event request.
 730  */
 731
 732 void lttvwindow_events_request(Tab                  *tab,
 733                                EventsRequest  *events_request);
 734
 735 /**
 736  * Function to remove data requests related to a viewer.
 737  *
 738  * The existing requests's viewer gpointer is compared to the pointer
 739  * given in argument to establish which data request should be removed.
 740  *
 741  * @param tab the tab the viewer belongs to.
 742  * @param viewer a pointer to the viewer data structure
 743  */
 744
 745 void lttvwindow_events_request_remove_all(Tab            *tab,
 746                                           gconstpointer   viewer);
 747
 748
 749 /**
 750  * Function to see if there are events request pending.
 751  *
 752  * It tells if events requests are pending. Useful for checks in some events,
 753  * i.e. detailed event list scrolling.
 754  *
 755  * @param tab the tab the viewer belongs to.
 756  * @param viewer a pointer to the viewer data structure
 757  * @return : TRUE is events requests are pending, else FALSE.
 758  */
 759
 760 gboolean lttvwindow_events_request_pending(Tab            *tab);
 761
 762
 763
 764
 765 /**
 766  * Function to get the current time interval shown on the current tab.
 767  * It will be called by a viewer's hook function to update the
 768  * shown time interval of the viewer and also be called by the constructor
 769  * of the viewer.
 770  * @param tab viewer's tab
 771  * @return time window.
 772  */
 773
 774 TimeWindow lttvwindow_get_time_window(Tab *tab);
 775
 776
 777 /**
 778  * Function to get the current time of the current tab.
 779  *
 780  * @param tab the tab the viewer belongs to.
 781  * @return the current tab's current time.
 782  */
 783
 784 LttTime lttvwindow_get_current_time(Tab *tab);
 785
 786
 787 /**
 788  * Function to get the filter of the current tab.
 789  * @param main_win, the main window the viewer belongs to.
 790  * @param filter, a pointer to a filter.
 791  */
 792
 793 //LttvFilter *lttvwindow_get_filter(Tab *tab);
 794
 795 /**
 796  * Function to set the filter of the current tab.
 797  * It should be called by the filter GUI to tell the
 798  * main window to update the filter tab's lttv_filter.
 799  *
 800  * Notice : the lttv_filter object will be owned by the
 801  *          main window after the return of this function.
 802  *          Do NOT desallocate it.
 803  *
 804  * @param main_win, the main window the viewer belongs to.
 805  * @param filter, a pointer to a filter.
 806  */
 807
 808 void lttvwindow_report_filter(Tab *tab, LttvFilter *filter);
 809
 810 #ifdef BABEL_CLEANUP
 811
 812 /**
 813  * Function to get the stats of the traceset
 814  * It must be non const so the viewer can modify it.
 815  * FIXME : a set/get pair of functions would be more appropriate here.
 816  * @param tab the tab the viewer belongs to.
 817  * @return A pointer to Traceset statistics.
 818  */
 819
 820 LttvTracesetStats* lttvwindow_get_traceset_stats(Tab *tab);
 821 #endif /*BABEL_CLEANUP*/
 822
 823 LttvTraceset* lttvwindow_get_traceset(Tab *tab);
 824
 825 /* set_time_window
 826  *
 827  * It updates the time window of the tab, then calls the updatetimewindow
 828  * hooks of each viewer.
 829  *
 830  * This is called whenever the scrollbar value changes.
 831  *
 832  * This is mostly an internal function.
 833  */
 834
 835 void set_time_window(Tab *tab, const TimeWindow *time_window);
 836
 837
 838 /* set_current_time
 839  *
 840  * It updates the current time of the tab, then calls the updatetimewindow
 841  * hooks of each viewer.
 842  *
 843  * This is called whenever the current time value changes.
 844  *
 845  * This is mostly an internal function.
 846  */
 847
 848 void set_current_time(Tab *tab, const LttTime *current_time);
 849
 850 void events_request_free(EventsRequest *events_request);
 851
 852 GtkWidget *main_window_get_widget(Tab *tab);
 853
 854 void set_current_position(Tab *tab, const LttvTracesetPosition *pos);
 855
 856
 857 /**
 858  * Function to disable the EventsRequests scheduler, nestable.
 859  *
 860  */
 861 static inline void lttvwindow_events_request_disable(void)
 862 {
 863   lttvwindow_preempt_count++;
 864 }
 865
 866 /**
 867  * Function to restore the EventsRequests scheduler, nestable.
 868  *
 869  */
 870 static inline void lttvwindow_events_request_enable(void)
 871 {
 872   lttvwindow_preempt_count--;
 873 }
 874
 875
 876 void current_position_change_manager(Tab *tab,
 877                                      LttvTracesetPosition *pos);
 878
 879 #endif //LTTVWINDOW_H