~ubuntu-branches/ubuntu/karmic/gtk+2.0/karmic-proposed

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.

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.

Using the framework

-------------------

Right now the framework is very simple; it just has utility functions

to time widget creation, mapping, exposure, and destruction.  To run

such a test, you use the GtkWidgetProfiler object in

gtkwidgetprofiler.h.

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.

The "create-widget" signal:

  The handler has this form:

    GtkWidget *create_widget_callback (GtkWidgetProfiler *profiler, 

				       gpointer user_data);

  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.

The "report" signal:

  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:

    void report_callback (GtkWidgetProfiler      *profiler,

			  GtkWidgetProfilerReport report,

			  GtkWidget              *widget,

			  gdouble                 elapsed,

			  gpointer                user_data);

  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:

----------------------------------------------------------------------

#include <stdio.h>

#include <gtk/gtk.h>

#include "gtkwidgetprofiler.h"

static GtkWidget *

create_widget_cb (GtkWidgetProfiler *profiler, gpointer data)

{

  GtkWidget *window;

  window = gtk_window_new (GTK_WINDOW_TOPLEVEL);

  /* ... fill the window with widgets, and don't show them ... */

  return window;

}

static void

report_cb (GtkWidgetProfiler *profiler, GtkWidgetProfilerReport report, GtkWidget *widget, gdouble elapsed, gpointer data)

{

  const char *type;

  switch (report) {

  case GTK_WIDGET_PROFILER_REPORT_CREATE:

    type = "widget creation";

    break;

  case GTK_WIDGET_PROFILER_REPORT_MAP:

    type = "widget map";

    break;

  case GTK_WIDGET_PROFILER_REPORT_EXPOSE:

    type = "widget expose";

    break;

  case GTK_WIDGET_PROFILER_REPORT_DESTROY:

    type = "widget destruction";

    break;

  default:

    g_assert_not_reached ();

    type = NULL;

  }

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

  if (report == GTK_WIDGET_PROFILER_REPORT_DESTROY)

    fputs ("\n", stderr);

}

int

main (int argc, char **argv)

{

  GtkWidgetProfiler *profiler;

  gtk_init (&argc, &argv);

  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);

  gtk_widget_profiler_profile_expose (profiler);

  return 0;

}

----------------------------------------------------------------------

Getting meaningful results

--------------------------

Getting times for widget creation/mapping/exposing/destruction is

interesting, but how do you actually find the places that need

optimizing?

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.