every viewer that currently sits in memory so it can destroy them before the
module gets unloaded/destroyed.
+The contructor registration to the main windows adds button and menu entry
+to each main window, thus allowing instanciation of viewers.
+
+
+Main Window
+
+The main window is a container that offers menus, buttons and a notebook. Some
+of those menus and buttons are part of the core of the main window, others
+are dynamically added and removed when modules are loaded/unloaded.
+
+The notebook contains as much tabs as wanted. Each tab is linked with a
+set of traces (traceset). Each trace contains many tracefiles (one per cpu).
+A trace corresponds to a kernel being traced. A traceset corresponds to
+many traces read together. The time span of a traceset goes from the
+earliest start of all the traces to the latest end of all the traces.
+
+Inside each tab are added the viewers. When they interact with the main
+window through the lttvwindow API, they affect the other viewers located
+in the same tab as they are.
+
+The insertion of many viewers in a tab permits a quick look at all the
+information wanted in a glance. The main window does merge the read requests
+from all the viewers in the same tab in a way that every viewer will get exactly
+the events it asked for, while the event reading loop and state update are
+shared. It improves performance of events delivery to the viewers.
+
+
Viewer Instance Related API
Events can be requested by passing a EventsRequest structure to the main window.
They will be delivered later when the next g_idle functions will be called.
-Event delivery is done by calling the middle hook for this event ID, or the
-main middle hooks.
+Event delivery is done by calling the event hook for this event ID, or the
+main event hooks. A pointer to the EventsRequest structure is passed as
+hook_data to the event hooks of the viewers.
EventsRequest consists in
+- a pointer to the viewer specific data structure
- a start timestamp or position
- a stop_flag, ending the read process when set to TRUE
- a end timestamp and/or position and/or number of events to read
- hook lists to call for traceset/trace/tracefile begin and end, and for each
- event (middle).
+ event (event hooks and event_by_id hooks).
The main window will deliver events for every EventRequests it has pending
through an algorithm that guarantee that all events requested, and only them,
of showing the pixmap buffer on the screen. If the pixmap buffer has never
been filled with a drawing, the expose handler may ask for it to be filled.
+The interest of using events request to the main window instead of reading the
+events directly from the trace comes from the fact that the main window
+does merge requests from the different viewers in the same tab so that the
+read loop and the state update is shared. As viewers will, in the common
+scenario, request the same events, only one pass through the trace that will
+call the right hooks for the right intervals will be done.
+
+When the traceset read is over for a events request, the traceset_end hook is
+called. It has the responsibility of finishing the drawing if some parts
+still need to be drawn and to show it on the screen (if the viewer uses a pixmap
+buffer).
+
It can add dotted lines and such visual effects to enhance the user's
experience.
*/
-
+#ifndef VIEWER_H
+#define VIEWER_H
/*! \file viewer.h
* \brief API used by the graphical viewers to interact with their top window.
#include <gtk/gtk.h>
#include <ltt/ltt.h>
+#include <ltt/time.h>
#include <lttv/hook.h>
-#include <lttvwindow/common.h>
+#include <lttv/tracecontext.h>
#include <lttv/stats.h>
+#include <lttvwindow/common.h>
//FIXME (not ready yet) #include <lttv/filter.h>
/* constructor a the viewer */
//FIXME explain LttvTracesetSelector and key
typedef GtkWidget * (*lttvwindow_viewer_constructor)
- (MainWindow * main_window, LttvTracesetSelector * s, char *key);
+ (Tab *tab, LttvTracesetSelector * s, char *key);
/**
* Function to register a view constructor so that main window can generate
- * a toolbar item for the viewer in order to generate a new instance easily.
+ * a menu item and a toolbar item for the viewer in order to generate a new
+ * instance easily. A menu entry and toolbar item will be added to each main
+ * window.
*
* It should be called by init function of the module.
*
- * @param pixmap Image shown on the toolbar item.
+ * @param menu_path path of the menu item. NULL : no menu entry.
+ * @param menu_text text of the menu item.
+ * @param pixmap Image shown on the toolbar item. NULL : no button.
* @param tooltip tooltip of the toolbar item.
* @param view_constructor constructor of the viewer.
*/
-void lttvwindow_register_toolbar
- (char ** pixmap,
+void lttvwindow_register_constructor
+ (char * menu_path,
+ char * menu_text,
+ char ** pixmap,
char * tooltip,
lttvwindow_viewer_constructor view_constructor);
/**
* Function to unregister the viewer's constructor, release the space
- * occupied by pixmap, tooltip and constructor of the viewer.
+ * occupied by menu_path, menu_text, pixmap, tooltip and constructor of the
+ * viewer.
*
* It will be called when a module is unloaded.
*
* @param view_constructor constructor of the viewer.
*/
-void lttvwindow_unregister_toolbar
+void lttvwindow_unregister_constructor
(lttvwindow_viewer_constructor view_constructor);
-/**
- * Function to register a view constructor so that main window can generate
- * a menu item for the viewer in order to generate a new instance easily.
- *
- * It will be called by init function of the module.
- *
- * @param menu_path path of the menu item.
- * @param menu_text text of the menu item.
- * @param view_constructor constructor of the viewer.
- */
-
-void lttvwindow_register_menu(char *menu_path,
- char *menu_text,
- lttvwindow_viewer_constructor view_constructor);
-
-
-/**
- * Function to unregister the viewer's constructor, release the space
- * occupied by menu_path, menu_text and constructor of the viewer.
- *
- * It will be called when a module is unloaded.
- *
- * @param view_constructor constructor of the viewer.
- */
-
-void lttvwindow_unregister_menu(lttvwindow_viewer_constructor view_constructor);
-
/* Viewer Instance Related API */
*
* This register function is typically called by the constructor of the viewer.
*
- * @param main_win the main window the viewer belongs to.
+ * @param tab the tab the viewer belongs to.
* @param hook hook that sould be called by the main window when the time
* interval changes. This hook function takes a
* TimeWindowNotifyData* as call_data.
* be typically a pointer to the viewer's data structure.
*/
-void lttvwindow_register_time_window_notify(MainWindow *main_win,
+void lttvwindow_register_time_window_notify(Tab *tab,
LttvHook hook,
gpointer hook_data);
*
* This unregister function is typically called by the destructor of the viewer.
*
- * @param main_win the main window the viewer belongs to.
+ * @param tab the tab the viewer belongs to.
* @param hook hook that sould be called by the main window when the time
* interval changes. This hook function takes a
* TimeWindowNotifyData* as call_data.
* be typically a pointer to the viewer's data structure.
*/
-void lttvwindow_unregister_time_window_notify(MainWindow *main_win,
+void lttvwindow_unregister_time_window_notify(Tab *tab,
LttvHook hook,
gpointer hook_data);
*
* This register function is typically called by the constructor of the viewer.
*
- * @param main_win the main window the viewer belongs to.
+ * @param tab the tab the viewer belongs to.
* @param hook hook that should be called whenever a change to the traceset
* occurs. The call_data of this hook is a NULL pointer.
* @param hook_data hook data associated with the hook function. It will
* be typically a pointer to the viewer's data structure.
*/
-void lttvwindow_register_traceset_notify(MainWindow *main_win,
+void lttvwindow_register_traceset_notify(Tab *tab,
LttvHook hook,
gpointer hook_data);
/**
* Function to unregister the traceset_notify hook.
*
- * @param main_win the main window the viewer belongs to.
+ * @param tab the tab the viewer belongs to.
* @param hook hook that should be called whenever a change to the traceset
* occurs. The call_data of this hook is a NULL pointer.
* @param hook_data hook data associated with the hook function. It will
* be typically a pointer to the viewer's data structure.
*/
-void lttvwindow_unregister_traceset_notify(MainWindow *main_win,
+void lttvwindow_unregister_traceset_notify(Tab *tab,
LttvHook hook,
gpointer hook_data);
*
* This register function is typically called by the constructor of the viewer.
*
- * @param main_win the main window the viewer belongs to.
+ * @param tab the tab the viewer belongs to.
* @param hook hook function called by the main window when a filter change
* occurs.
* @param hook_data hook data associated with the hook function. It will
* be typically a pointer to the viewer's data structure.
*/
-void lttvwindow_register_filter_notify(MainWindow *main_win,
+void lttvwindow_register_filter_notify(Tab *tab,
LttvHook hook,
gpointer hook_data);
*
* This unregistration is called by the destructor of the viewer.
*
- * @param main_win the main window the viewer belongs to.
+ * @param tab the tab the viewer belongs to.
* @param hook hook function called by the main window when a filter change
* occurs.
* @param hook_data hook data associated with the hook function. It will
* be typically a pointer to the viewer's data structure.
*/
-void lttvwindow_unregister_filter_notify(MainWindow * main_win,
+void lttvwindow_unregister_filter_notify(Tab *tab,
LttvHook hook,
gpointer hook_data);
* Function to register a hook function for a viewer to set/update its
* current time.
*
- * @param main_win the main window the viewer belongs to.
+ * @param tab the tab the viewer belongs to.
* @param hook hook function of the viewer that updates the current time. The
* call_data is a LttTime* representing the new current time.
* @param hook_data hook data associated with the hook function. It will
* be typically a pointer to the viewer's data structure.
*/
-void lttvwindow_register_current_time_notify(MainWindow *main_win,
+void lttvwindow_register_current_time_notify(Tab *tab,
LttvHook hook,
gpointer hook_data);
/**
* Function to unregister a viewer's hook function which is used to
* set/update the current time of the viewer.
- * @param main_win the main window the viewer belongs to.
+ * @param tab the tab the viewer belongs to.
* @param hook hook function of the viewer that updates the current time. The
* call_data is a LttTime* representing the new current time.
* @param hook_data hook data associated with the hook function. It will
* be typically a pointer to the viewer's data structure.
*/
-void lttvwindow_unregister_current_time_notify(MainWindow *main_win,
+void lttvwindow_unregister_current_time_notify(Tab *tab,
LttvHook hook,
gpointer hook_data);
* dividor of the hpane. It provides a way to make the horizontal
* dividors of all the viewers linked together.
*
- * @param main_win the main window the viewer belongs to.
+ * @param tab the tab the viewer belongs to.
* @param hook hook function of the viewer that will be called whenever a
* dividor changes in another viewer. The call_data of this hook
* is a gint*. The value of the integer is the new position of the
* be typically a pointer to the viewer's data structure.
*/
-void lttvwindow_register_dividor(MainWindow *main_win,
+void lttvwindow_register_dividor(Tab *tab,
LttvHook hook,
gpointer hook_data);
* Function to unregister a viewer's hook function which is used to
* set/update hpane's dividor of the viewer.
*
- * @param main_win the main window the viewer belongs to.
+ * @param tab the tab the viewer belongs to.
* @param hook hook function of the viewer that will be called whenever a
* dividor changes in another viewer. The call_data of this hook
* is a gint*. The value of the integer is the new position of the
* be typically a pointer to the viewer's data structure.
*/
-void lttvwindow_unregister_dividor(MainWindow *main_win,
+void lttvwindow_unregister_dividor(Tab *tab,
LttvHook hook,
gpointer hook_data);
* This method reports the information to show on the status bar in the
* main window.
*
- * @param main_win the main window the viewer belongs to.
+ * @param tab the tab the viewer belongs to.
* @param info the message which will be shown in the status bar.
*/
-void lttvwindow_report_status(MainWindow *main_win, const char *info);
+void lttvwindow_report_status(Tab *tab, const char *info);
/**
* Function to set the time interval of the current tab.a
*
- * @param main_win the main window the viewer belongs to.
+ * @param tab the tab the viewer belongs to.
* @param time_interval pointer to the time interval value.
*/
-void lttvwindow_report_time_window(MainWindow *main_win,
+void lttvwindow_report_time_window(Tab *tab,
const TimeWindow *time_window);
/**
* Function to set the current time/event of the current tab.
* It will be called by a viewer's signal handle associated with
* the button-release-event signal
- * @param main_win the main window the viewer belongs to.
+ * @param tab the tab the viewer belongs to.
* @param time a pointer where time is stored.
*/
-void lttvwindow_report_current_time(MainWindow *main_win,
+void lttvwindow_report_current_time(Tab *tab,
const LttTime *time);
* It will typically be called by a viewer's signal handle associated
* with the motion_notify_event event/signal.
*
- * @param main_win the main window the viewer belongs to.
+ * @param tab the tab the viewer belongs to.
* @param position position of the hpane's dividor.
*/
-void lttvwindow_report_dividor(MainWindow *main_win, gint position);
+void lttvwindow_report_dividor(Tab *tab, gint position);
/**
* Function to set the focused viewer of the tab.
* It will be called by a viewer's signal handle associated with
* the grab_focus signal of all widgets in the viewer.
*
- * @param main_win the main window the viewer belongs to.
+ * @param tab the tab the viewer belongs to.
* @param top_widget the top widget containing all the other widgets of the
* viewer.
*/
-void lttvwindow_report_focus(MainWindow *main_win,
+void lttvwindow_report_focus(Tab *tab,
GtkWidget *top_widget);
-
-/* Structure sent to the time request hook */
+/* Structure sent to the events request hook */
/* Value considered as empty */
typedef struct _EventsRequest {
- LttTime start_time, /* Unset : { 0, 0 } */
- LttvTracesetContextPosition start_position, /* Unset : num_traces = 0 */
- LttTime end_time, /* Unset : { 0, 0 } */
- guint num_events, /* Unset : G_MAXUINT */
- LttvTracesetContextPosition end_position, /* Unset : num_traces = 0 */
- LttvHooksById *before_traceset, /* Unset : NULL */
- LttvHooksById *before_trace, /* Unset : NULL */
- LttvHooksById *before_tracefile, /* Unset : NULL */
- LttvHooksById *middle, /* Unset : NULL */
- LttvHooksById *after_tracefile, /* Unset : NULL */
- LttvHooksById *after_trace, /* Unset : NULL */
- LttvHooksById *after_traceset /* Unset : NULL */
+ gpointer viewer_data; /* Unset : NULL */
+ gboolean servicing; /* service in progress: TRUE */
+ LttTime start_time;/* Unset : { G_MAXUINT, G_MAXUINT }*/
+ LttvTracesetContextPosition *start_position; /* Unset : NULL */
+ gboolean stop_flag; /* Continue:TRUE Stop:FALSE */
+ LttTime end_time;/* Unset : { G_MAXUINT, G_MAXUINT } */
+ guint num_events; /* Unset : G_MAXUINT */
+ LttvTracesetContextPosition *end_position; /* Unset : NULL */
+ LttvHooks *before_chunk_traceset; /* Unset : NULL */
+ LttvHooks *before_chunk_trace; /* Unset : NULL */
+ LttvHooks *before_chunk_tracefile;/* Unset : NULL */
+ LttvHooks *event; /* Unset : NULL */
+ LttvHooksById *event_by_id; /* Unset : NULL */
+ LttvHooks *after_chunk_tracefile; /* Unset : NULL */
+ LttvHooks *after_chunk_trace; /* Unset : NULL */
+ LttvHooks *after_chunk_traceset; /* Unset : NULL */
+ LttvHooks *before_request; /* Unset : NULL */
+ LttvHooks *after_request /* Unset : NULL */
} EventsRequest;
/**
* Function to request data in a specific time interval to the main window. The
- * time request servicing is differed until the glib idle functions are
+ * event request servicing is differed until the glib idle functions are
* called.
*
* The viewer has to provide hooks that should be associated with the event
* end_time, end_position and num_events can all be defined. The first one
* to occur will be used as end criterion.
*
- * @param main_win the main window the viewer belongs to.
- * @param events_requested the structure of request from.
+ * @param tab the tab the viewer belongs to.
+ * @param events_requested Details about the event request.
*/
-void lttvwindow_events_request(MainWindow *main_win,
- EventsRequest events_request);
+void lttvwindow_events_request(Tab *tab,
+ const EventsRequest *events_request);
/**
- * Function to get the life span of the traceset
+ * Function to remove data requests related to a viewer.
*
- * @param main_win the main window the viewer belongs to.
- * @return pointer to a time interval : the life span of the traceset.
+ * The existing requests's viewer gpointer is compared to the pointer
+ * given in argument to establish which data request should be removed.
+ *
+ * @param tab the tab the viewer belongs to.
+ * @param viewer a pointer to the viewer data structure
*/
-const TimeInterval *lttvwindow_get_time_span(MainWindow *main_win);
+void lttvwindow_events_request_remove_all(Tab *tab,
+ gconstpointer viewer);
+
+
+typedef struct _BackgroundRequest {
+ gchar *hook_path; /* Hook path in global attributes, where all standard hooks
+ are : i.e. /TraceState/Statistics/ModuleName */
+ gchar *trace_path; /* path_to_trace */
+} BackgroundRequest;
+
+typedef struct _BackgroundNotify {
+ gchar *trace_path; /* path_to_trace */
+ LttTime notify_time;
+ LttvTracesetContextPosition *notify_position;
+ LttvHooks *notify; /* Hook to call when the notify is
+ passed, or at the end of trace */
+} BackgroundNotify;
+
+/**
+ * Function to request data from a specific trace
+ *
+ * @param bg_request Request specification
+ */
+
+void lttvwindow_background_request_queue(const BackgroundRequest *bg_request);
+
+/**
+ * Register a callback to be called when requested data is passed in the next
+ * queued background processing.
+ *
+ * @param bg_request Request specification
+ */
+
+void lttvwindow_background_notify_queue(const BackgroundNotify *bg_notify);
+
+
+/**
+ * Register a callback to be called when requested data is passed in the current
+ * background processing.
+ *
+ * @param bg_request Request specification
+ */
+
+void lttvwindow_background_notify_current(const BackgroundNotify *bg_notify);
+
/**
* Function to get the current time window of the current tab.
*
- * @param main_win the main window the viewer belongs to.
+ * @param tab the tab the viewer belongs to.
* @return a pointer to the current tab's time interval.
*/
-const TimeWindow *lttvwindow_get_time_window(MainWindow *main_win);
+const TimeWindow *lttvwindow_get_time_window(Tab *tab);
/**
* Function to get the current time of the current tab.
*
- * @param main_win the main window the viewer belongs to.
+ * @param tab the tab the viewer belongs to.
* @return a pointer to the current tab's current time.
*/
-const LttTime *lttvwindow_get_current_time(MainWindow *main_win);
+const LttTime *lttvwindow_get_current_time(Tab *tab);
/**
//FIXME
typedef void lttv_filter;
//FIXME
-const lttv_filter *lttvwindow_get_filter(MainWindow *main_win);
+const lttv_filter *lttvwindow_get_filter(Tab *tab);
/**
* Function to get the stats of the traceset
* It must be non const so the viewer can modify it.
* FIXME : a set/get pair of functions would be more appropriate here.
- * @param main_win the main window the viewer belongs to.
+ * @param tab the tab the viewer belongs to.
* @return A pointer to Traceset statistics.
*/
-LttvTracesetStats* lttvwindow_get_traceset_stats(MainWindow *main_win);
+LttvTracesetStats* lttvwindow_get_traceset_stats(Tab *tab);
/**
* Function to get the context of the traceset
* It must be non const so the viewer can add and remove hooks from it.
- * @param main_win the main window the viewer belongs to.
+ * @param tab the tab the viewer belongs to.
* @return Context of the current tab.
*/
-LttvTracesetContext* lttvwindow_get_traceset_context(MainWindow *main_win);
+LttvTracesetContext* lttvwindow_get_traceset_context(Tab *tab);
+#endif //VIEWER_H
projects / lttv.git / blobdiff