gtk2/perf/README

159 lines
4.5 KiB
Plaintext
Raw Normal View History

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 2005/07/28.
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);
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.