README 6.58 KB
Newer Older
1 2 3 4 5 6 7 8
README for gtk+/perf
--------------------

This is a framework for testing performance in GTK+.   For GTK+, being
performant does not only mean "paint widgets fast".  It also means
things like the time needed to set up widgets, to map and draw a
window for the first time, and emitting/propagating signals.

9 10 11 12 13 14 15 16 17 18 19 20 21 22 23 24 25 26 27 28 29 30 31 32 33 34 35 36 37 38 39 40 41 42 43 44 45 46 47 48 49 50 51 52 53 54 55 56 57 58 59 60 61 62 63 64 65 66 67 68 69
The following is accurate as of 2006/Jun/14.


Background
----------

A widget's lifetime looks more or less like this:

	1. Instantiation
	2. Size request
	3. Size allocate
	5. Realize
	4. Map
	5. Expose
	6. Destroy

Some of these stages are particularly interesting:

- Instantiation means creating the widget.  This may be as simple as a
  few malloc()s and setting some fields.  It could also be a
  complicated operation if the widget needs to contact an external
  server to create itself, or if it needs to read data files.

- Size requisition is when GTK+ asks the widget, "how big do you want
  to be on the screen"?  This can be an expensive operation.  The
  widget has to measure its text, measure its icons (and thus load its
  icons), and generally run through its internal layout code.

- Realization is when the widget creates its GDK resources, like its
  GdkWindow and graphics contexts it may need.  This could be
  expensive if the widget needs to load data files for cursors or
  backgrounds.

- Expose is when the widget gets repainted.  This will happen many
  times throughout the lifetime of the widget:  every time you drag a
  window on top of it, every time its data changes and it needs to
  redraw, every time it gets resized.

GtkWidgetProfiler is a mechanism to let you get individual timings for
each of the stages in the lifetime of a widget.  It also lets you run
some stages many times in a sequence, so that you can run a real
profiler and get an adequate number of samples.  For example,
GtkWidgetProfiler lets you say "repaint this widget 1000 times".

Why is this not as simple as doing

	start_timer ();
	for (i = 0; i < 1000; i++) {
		gtk_widget_queue_draw (widget);
		while (gtk_events_pending ())
			gtk_main_iteration ();
	}
	stop_timer ();

Huh?

Because X is an asynchronous window system.  So, when you send the
"paint" commands, your program will regain control but it will take
some time for the X server to actually process those commands.
GtkWidgetProfiler has special code to wait for the X server and give
you accurate timings.
70 71 72 73 74 75


Using the framework
-------------------

Right now the framework is very simple; it just has utility functions
76 77 78
to time widget creation, mapping, exposure, and destruction.  To run
such a test, you use the GtkWidgetProfiler object in
gtkwidgetprofiler.h.
79

80 81 82 83
The gtk_widget_profiler_profile_boot() function will emit the
"create-widget" signal so that you can create your widget for
testing.  It will then take timings for the widget, and emit the
"report" signal as appropriate.
84

85
The "create-widget" signal:
86

87
  The handler has this form:
88

89 90
    GtkWidget *create_widget_callback (GtkWidgetProfiler *profiler, 
				       gpointer user_data);
91

92 93 94
  You need to create a widget in your handler, and return it.  Do not
  show the widget; the profiler will do that by itself at the right
  time, and will actually complain if you show the widget.
95 96


97
The "report" signal:
98

99 100 101
  This function will get called when the profiler wants to report that
  it finished timing an important stage in the lifecycle of your
  widget.  The handler has this form:
102

103 104 105 106 107
    void report_callback (GtkWidgetProfiler      *profiler,
			  GtkWidgetProfilerReport report,
			  GtkWidget              *widget,
			  gdouble                 elapsed,
			  gpointer                user_data);
108

109 110 111 112 113 114 115 116 117 118 119 120 121 122 123 124 125 126 127 128 129
  The "report" argument tells you what happened to your widget:

    GTK_WIDGET_PROFILER_REPORT_CREATE.  A timer gets started right
    before the profiler emits the "create-widget" signal,, and it gets
    stopped when your callback returns with the new widget.  This
    measures the time it takes to set up your widget, but not show it.

    GTK_WIDGET_PROFILER_REPORT_MAP.  A timer gets started right before
    the profiler calls gtk_widget_show_all() on your widget, and it
    gets stopped when the the widget has been mapped.

    GTK_WIDGET_PROFILER_REPORT_EXPOSE.  A timer gets started right before
    the profiler starts waiting for GTK+ and the X server to finish
    painting your widget, and it gets stopped when the widget is fully
    painted to the screen.

    GTK_WIDGET_PROFILER_REPORT_DESTROY.  A timer gets started right
    before the profiler calls gtk_widget_destroy() on your widget, and
    it gets stopped when gtk_widget_destroy() returns.

As a very basic example of using GtkWidgetProfiler is this:
130 131 132 133

----------------------------------------------------------------------
#include <stdio.h>
#include <gtk/gtk.h>
134
#include "gtkwidgetprofiler.h"
135 136

static GtkWidget *
137
create_widget_cb (GtkWidgetProfiler *profiler, gpointer data)
138 139 140 141 142 143 144 145 146 147
{
  GtkWidget *window;

  window = gtk_window_new (GTK_WINDOW_TOPLEVEL);
  /* ... fill the window with widgets, and don't show them ... */

  return window;
}

static void
148
report_cb (GtkWidgetProfiler *profiler, GtkWidgetProfilerReport report, GtkWidget *widget, gdouble elapsed, gpointer data)
149 150 151 152
{
  const char *type;

  switch (report) {
153
  case GTK_WIDGET_PROFILER_REPORT_CREATE:
154 155 156
    type = "widget creation";
    break;

157 158
  case GTK_WIDGET_PROFILER_REPORT_MAP:
    type = "widget map";
159 160
    break;

161 162 163 164 165
  case GTK_WIDGET_PROFILER_REPORT_EXPOSE:
    type = "widget expose";
    break;

  case GTK_WIDGET_PROFILER_REPORT_DESTROY:
166 167
    type = "widget destruction";
    break;
168 169 170 171

  default:
    g_assert_not_reached ();
    type = NULL;
172 173 174
  }

  fprintf (stderr, "%s: %g sec\n", type, elapsed);
175 176 177

  if (report == GTK_WIDGET_PROFILER_REPORT_DESTROY)
    fputs ("\n", stderr);
178 179 180 181 182
}

int
main (int argc, char **argv)
{
183
  GtkWidgetProfiler *profiler;
184 185 186

  gtk_init (&argc, &argv);

187 188 189 190 191 192 193 194
  profiler = gtk_widget_profiler_new ();
  g_signal_connect (profiler, "create-widget",
		    G_CALLBACK (create_widget_cb), NULL);
  g_signal_connect (profiler, "report",
		    G_CALLBACK (report_cb), NULL);

  gtk_widget_profiler_set_num_iterations (profiler, 100);
  gtk_widget_profiler_profile_boot (profiler);
195 196

  gtk_widget_profiler_profile_expose (profiler);
197 198
  
  return 0;
199 200
}

201 202 203 204 205 206
----------------------------------------------------------------------


Getting meaningful results
--------------------------

207 208 209
Getting times for widget creation/mapping/exposing/destruction is
interesting, but how do you actually find the places that need
optimizing?
210 211 212 213 214 215 216 217 218 219 220

Why, you run the tests under a profiler, of course.

FIXME: document how to do this.


Feedback
--------

Please mail your feedback to Federico Mena-Quintero <federico@novell.com>.
This performance framework is a work in progress.