Pileus Git - ~andy/gtk/blob - perf/README

   1 README for gtk+/perf
   2 --------------------
   3
   4 This is a framework for testing performance in GTK+.   For GTK+, being
   5 performant does not only mean "paint widgets fast".  It also means
   6 things like the time needed to set up widgets, to map and draw a
   7 window for the first time, and emitting/propagating signals.
   8
   9 The following is accurate as of 2005/07/26.
  10
  11
  12 Using the framework
  13 -------------------
  14
  15 Right now the framework is very simple; it just has utility functions
  16 to time widget creation, drawing, and destruction.  To run such a
  17 test, you use the functions in timers.h.  You can call this:
  18
  19   timer_time_widget (create_func, report_func, user_data);
  20
  21 You must provide the create_funcn and report_func callbacks.
  22
  23 The create_func:
  24
  25   This simply creates a toplevel window with some widgets inside it.
  26   It is important that you do not show any of the widgets; the
  27   framework will call gtk_widget_show_all() on the toplevel window
  28   automatically at the right time.
  29
  30 The report_func:
  31
  32   This function will get called when timer_time_widget() reaches an
  33   interesting point in the lifecycle of your widget.  See timers.h and
  34   the TimerReport enumeration; this is what gets passed as the
  35   "report" argument to your report_func.  Right now, your function
  36   will be called three times for each call to timer_time_widget():
  37
  38      1. With report = TIMER_REPORT_WIDGET_CREATION.  A timer gets
  39         started right before timer_time_widget() calls create_func,
  40         and it gets stopped when your create_func returns.  This
  41         measures the time it takes to set up a toplevel window (but
  42         not show it).
  43
  44      2. With report = TIMER_REPORT_WIDGET_SHOW.  A timer gets started
  45         right before timer_time_widget() calls gtk_widget_show_all()
  46         on your toplevel window, and it gets stopped when the window
  47         has been fully shown and painted to the screen.
  48
  49      3. With report = TIMER_REPORT_WIDGET_DESTRUCTION.  A timer gets
  50         started right before timer_time_widget() calls
  51         gtk_widget_destroy() on your toplevel window, and it gets
  52         stopped when gtk_widget_destroy() returns.
  53
  54 As a very basic example of using timer_time_widget(), you can use
  55 something like this:
  56
  57 ----------------------------------------------------------------------
  58 #include <stdio.h>
  59 #include <gtk/gtk.h>
  60 #include "timers.h"
  61
  62 #define ITERS 20
  63
  64 static GtkWidget *
  65 create_cb (gpointer data)
  66 {
  67   GtkWidget *window;
  68
  69   window = gtk_window_new (GTK_WINDOW_TOPLEVEL);
  70   /* ... fill the window with widgets, and don't show them ... */
  71
  72   return window;
  73 }
  74
  75 static void
  76 report_cb (TimerReport report, gdouble elapsed, gpointer data)
  77 {
  78   const char *type;
  79
  80   switch (report) {
  81   case TIMER_REPORT_WIDGET_CREATION:
  82     type = "widget creation";
  83     break;
  84
  85   case TIMER_REPORT_WIDGET_SHOW:
  86     type = "widget show";
  87     break;
  88
  89   case TIMER_REPORT_WIDGET_DESTRUCTION:
  90     type = "widget destruction";
  91     break;
  92   }
  93
  94   fprintf (stderr, "%s: %g sec\n", type, elapsed);
  95 }
  96
  97 int
  98 main (int argc, char **argv)
  99 {
 100   int i;
 101
 102   gtk_init (&argc, &argv);
 103
 104   for (i = 0; i < ITERS; i++)
 105     timer_time_widget (create_cb, report_cb, NULL);
 106
 107   return 0;
 108 }
 109 ----------------------------------------------------------------------
 110
 111
 112 Getting meaningful results
 113 --------------------------
 114
 115 Getting times for widget creation/drawing/destruction is interesting,
 116 but how do you actually find the places that need optimizing?
 117
 118 Why, you run the tests under a profiler, of course.
 119
 120 FIXME: document how to do this.
 121
 122
 123 Feedback
 124 --------
 125
 126 Please mail your feedback to Federico Mena-Quintero <federico@novell.com>.
 127 This performance framework is a work in progress.