Module Related API
-A viewer plugin is, before anything, a plugin. As a dynamically loadable
+A viewer plugin is, before anything, a plugin. As a dynamically loadable
module, it thus has an init and a destroy function called whenever it is
loaded/initialized and unloaded/destroyed. A graphical module depends on
-lttvwindow for construction of its viewer instances. In order to achieve this,
-it must register its constructor function to the main window along with
-button description or text menu entry description. A module keeps a list of
-every viewer that currently sits in memory so it can destroy them before the
-module gets unloaded/destroyed.
+lttvwindow for construction of its viewer instances. In order to achieve
+this, it must register its constructor function to the main window along
+with button description or text menu entry description. A module keeps
+a list of 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.
+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 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.
+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.
+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
-The lifetime of a viewer is as follows. The viewer constructor function is
-called each time an instance view is created (one subwindow of this viewer
-type is created by the user either by clicking on the menu item or the button
-corresponding to the viewer). Thereafter, the viewer gets hooks called for
-different purposes by the window containing it. These hooks are detailed
-below. It also has to deal with GTK Events. Finally, it can be destructed by
-having its top level widget unreferenced by the main window or by any
-GTK Event causing a "destroy-event" signal on the its top widget. Another
-possible way for it do be destroyed is if the module gets unloaded. The module
-unload function will have to emit a "destroy" signal on each top level widget
-of all instances of its viewers.
+The lifetime of a viewer is as follows. The viewer constructor function
+is called each time an instance view is created (one subwindow of this
+viewer type is created by the user either by clicking on the menu item
+or the button corresponding to the viewer). Thereafter, the viewer gets
+hooks called for different purposes by the window containing it. These
+hooks are detailed below. It also has to deal with GTK Events. Finally,
+it can be destructed by having its top level widget unreferenced by the
+main window or by any GTK Event causing a "destroy-event" signal on the
+its top widget. Another possible way for it do be destroyed is if the
+module gets unloaded. The module unload function will have to emit a
+"destroy" signal on each top level widget of all instances of its viewers.
Notices from Main Window
typically showing processes, cpus, ...
-FIXME : Add background computation explanation here
-background_init: prepare for background computation (comes after show_end).
-process_trace for background: done in small chunks in gtk_idle, hooks called.
-background_end: remove the hooks and perhaps update the window.
-
-
Reporting Changes to the Main Window
-In most cases, the enclosing window knows about updates such as described in the
-Notification section higher. There are a few cases, however, where updates are
-caused by actions known by a view instance. For example, clicking in a view may
-update the current time; all viewers within the same window must be told about
-the new current time to change the currently highlighted time point. A viewer
-reports such events by calling lttvwindow_report_current_time on its lttvwindow.
-The lttvwindow will consequently call current_time_notify for each of its
-contained viewers.
+In most cases, the enclosing window knows about updates such as described
+in the Notification section higher. There are a few cases, however, where
+updates are caused by actions known by a view instance. For example,
+clicking in a view may update the current time; all viewers within
+the same window must be told about the new current time to change the
+currently highlighted time point. A viewer reports such events by calling
+lttvwindow_report_current_time on its lttvwindow. The lttvwindow will
+consequently call current_time_notify for each of its contained viewers.
Available report methods are :
-lttvwindow_report_status : reports the text of the status bar.
lttvwindow_report_time_window : reports the new time window.
lttvwindow_report_current_time : reports the new current time.
lttvwindow_report_dividor : reports the new horizontal dividor's position.
-lttvwindow_report_focus : One on the widgets in the viewer has the keyboard's
- focus from GTK.
Requesting Events to Main Window
-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 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.
+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 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
- hook lists to call for traceset/trace/tracefile begin and end, and for each
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,
-will be delivered to the viewer between the call of the tracefile_begin hooks
-and the call of the tracefile_end 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, will be delivered to the viewer between the call of the
+tracefile_begin hooks and the call of the tracefile_end hooks.
-If a viewer wants to stop the event request at a certain point inside the event
-hooks, it has to set the stop_flag to TRUE and return TRUE from the hook
-function. Then return value will stop the process traceset. Then, the main
-window will look for the stop_flag and remove the EventRequests from its lists,
-calling the process_traceset_end for this request (it removes hooks from the
-context and calls the after hooks).
+If a viewer wants to stop the event request at a certain point inside the
+event hooks, it has to set the stop_flag to TRUE and return TRUE from the
+hook function. Then return value will stop the process traceset. Then,
+the main window will look for the stop_flag and remove the EventRequests
+from its lists, calling the process_traceset_end for this request (it
+removes hooks from the context and calls the after hooks).
-It no stop_flag is rose, the end timestamp, end position or number of events to
-read has to be reached to determine the end of the request. Otherwise,
-the end of traceset does determine it.
+It no stop_flag is risen, the end timestamp, end position or number
+of events to read has to be reached to determine the end of the
+request. Otherwise, the end of traceset does determine it.
GTK Events
Events and Signals
-GTK is quite different from the other graphical toolkits around there. The main
-difference resides in that there are many X Windows inside one GtkWindow,
-instead of just one. That means that X events are delivered by the glib main
-loop directly to the widget corresponding to the GdkWindow affected by the X
-event.
+GTK is quite different from the other graphical toolkits around
+there. The main difference resides in that there are many X Windows
+inside one GtkWindow, instead of just one. That means that X events are
+delivered by the glib main loop directly to the widget corresponding to
+the GdkWindow affected by the X event.
-Event delivery to a widget emits a signal on that widget. Then, if a handler
-is connected to this widget's signal, it will be executed. There are default
-handlers for signals, connected at class instantiation time. There is also
-the possibility to connect other handlers to these signals, which is what
-should be done in most cases when a viewer needs to interact with X in any
-way.
+Event delivery to a widget emits a signal on that widget. Then, if a
+handler is connected to this widget's signal, it will be executed. There
+are default handlers for signals, connected at class instantiation
+time. There is also the possibility to connect other handlers to these
+signals, which is what should be done in most cases when a viewer needs
+to interact with X in any way.
Provides the exposed region in the GdkEventExpose structure.
-There are two ways of dealing with exposures. The first one is to directly draw
-on the screen and the second one is to draw in a pixmap buffer, and then to
-update the screen when necessary.
+There are two ways of dealing with exposures. The first one is to directly
+draw on the screen and the second one is to draw in a pixmap buffer,
+and then to update the screen when necessary.
-In the first case, the expose event will be responsible for registering hooks to
-process_traceset and require time intervals to the main window. So, in this
-scenario, if a part of the screen is damaged, the trace has to be read to
-redraw the screen.
+In the first case, the expose event will be responsible for registering
+hooks to process_traceset and require time intervals to the main
+window. So, in this scenario, if a part of the screen is damaged, the
+trace has to be read to redraw the screen.
-In the second case, with a pixmap buffer, the expose handler is only responsible
-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.
+In the second case, with a pixmap buffer, the expose handler is only
+responsible 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.
+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).
+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.
#include <lttv/hook.h>
#include <lttv/tracecontext.h>
#include <lttv/stats.h>
-#include <lttvwindow/common.h>
+#include <lttvwindow/mainwindow.h>
+#include <lttvwindow/lttvfilter.h>
//FIXME (not ready yet) #include <lttv/filter.h>
-
/* Module Related API */
+/* GQuark containing constructors of viewers in global attributes */
+extern GQuark LTTV_VIEWER_CONSTRUCTORS;
/* constructor a the viewer */
-//FIXME explain LttvTracesetSelector and key
-typedef GtkWidget * (*lttvwindow_viewer_constructor)
- (Tab *tab, LttvTracesetSelector * s, char *key);
+typedef GtkWidget* (*lttvwindow_viewer_constructor)(Tab *tab);
/**
* window.
*
* It should be called by init function of the module.
- *
+ *
+ * @param name name of the viewer : mainly used as tag for constructor
* @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.
*/
void lttvwindow_register_constructor
- (char * menu_path,
+ (char * name,
+ char * menu_path,
char * menu_text,
char ** pixmap,
char * tooltip,
gpointer hook_data);
+/**
+ * Function to register a hook function for a viewer be completely redrawn.
+ *
+ * @param tab viewer's tab
+ * @param hook hook function of the viewer.
+ * @param hook_data hook data associated with the hook function.
+ */
+
+void lttvwindow_register_redraw_notify(Tab *tab,
+ LttvHook hook, gpointer hook_data);
+
+/**
+ * Function to unregister a hook function for a viewer be completely redrawn.
+ *
+ * @param tab viewer's tab
+ * @param hook hook function of the viewer.
+ * @param hook_data hook data associated with the hook function.
+ */
+
+void lttvwindow_unregister_redraw_notify(Tab *tab,
+ LttvHook hook, gpointer hook_data);
+
+
+/**
+ * Function to register a hook function for a viewer to re-do the events
+ * requests for the needed interval.
+ *
+ * This action is typically done after a "stop".
+ *
+ * The typical hook will remove all current requests for the viewer
+ * and make requests for missing information.
+ *
+ * @param tab viewer's tab
+ * @param hook hook function of the viewer.
+ * @param hook_data hook data associated with the hook function.
+ */
+
+void lttvwindow_register_continue_notify(Tab *tab,
+ LttvHook hook, gpointer hook_data);
+
+
+/**
+ * Function to unregister a hook function for a viewer to re-do the events
+ * requests for the needed interval.
+ *
+ * @param tab viewer's tab
+ * @param hook hook function of the viewer.
+ * @param hook_data hook data associated with the hook function.
+ */
+
+void lttvwindow_unregister_continue_notify(Tab *tab,
+ LttvHook hook, gpointer hook_data);
+
+
/**
* Function to register a hook function for a viewer to set/update its
* filter.
-/**
- * This method reports the information to show on the status bar in the
- * main window.
- *
- * @param tab the tab the viewer belongs to.
- * @param info the message which will be shown in the status bar.
- */
-
-void lttvwindow_report_status(Tab *tab, const char *info);
-
-
/**
* Function to set the time interval of the current tab.a
*
* @param tab the tab the viewer belongs to.
- * @param time_interval pointer to the time interval value.
+ * @param time_interval new time window.
*/
void lttvwindow_report_time_window(Tab *tab,
- const TimeWindow *time_window);
+ 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 tab the tab the viewer belongs to.
- * @param time a pointer where time is stored.
+ * @param new current time.
*/
void lttvwindow_report_current_time(Tab *tab,
- const LttTime *time);
+ LttTime time);
/**
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 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(Tab *tab,
- GtkWidget *top_widget);
-
/* Structure sent to the events request hook */
- /* Value considered as empty */
+ /* Value considered as empty*/
typedef struct _EventsRequest {
+ gpointer owner; /* Owner of the request */
gpointer viewer_data; /* Unset : NULL */
- gboolean servicing; /* service in progress: TRUE */
- LttTime start_time;/* Unset : { G_MAXUINT, G_MAXUINT }*/
+ gboolean servicing; /* service in progress: TRUE*/
+ LttTime start_time; /* Unset : ltt_time_infinite*/
LttvTracesetContextPosition *start_position; /* Unset : NULL */
gboolean stop_flag; /* Continue:TRUE Stop:FALSE */
- LttTime end_time;/* Unset : { G_MAXUINT, G_MAXUINT } */
+ LttTime end_time; /* Unset : ltt_time_infinite*/
guint num_events; /* Unset : G_MAXUINT */
LttvTracesetContextPosition *end_position; /* Unset : NULL */
+ gint trace; /* unset : -1 */
+ GArray *hooks; /* Unset : NULL */
LttvHooks *before_chunk_traceset; /* Unset : NULL */
LttvHooks *before_chunk_trace; /* Unset : NULL */
LttvHooks *before_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 */
+ LttvHooks *after_request; /* Unset : NULL */
} EventsRequest;
+/* Maximum number of events to proceed at once in a chunk */
+#define CHUNK_NUM_EVENTS 500
+
/**
* Function to request data in a specific time interval to the main window. The
*
* end_time, end_position and num_events can all be defined. The first one
* to occur will be used as end criterion.
+ *
+ * The events_request memory will be managed by the main window once its
+ * pointer is passed by this function.
*
* @param tab the tab the viewer belongs to.
* @param events_requested Details about the event request.
*/
void lttvwindow_events_request(Tab *tab,
- const EventsRequest *events_request);
+ EventsRequest *events_request);
/**
* Function to remove data requests related to a viewer.
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 tab the tab the viewer belongs to.
- * @return a pointer to the current tab's time interval.
+ * @return the current tab's time interval.
*/
-const TimeWindow *lttvwindow_get_time_window(Tab *tab);
+__inline TimeWindow lttvwindow_get_time_window(Tab *tab);
/**
* Function to get the current time of the current tab.
*
* @param tab the tab the viewer belongs to.
- * @return a pointer to the current tab's current time.
+ * @return the current tab's current time.
*/
-const LttTime *lttvwindow_get_current_time(Tab *tab);
+LttTime lttvwindow_get_current_time(Tab *tab);
/**
projects / lttv.git / blobdiff