gtk/perf/README
Federico Mena Quintero b4f52020f0 Update for the new API of the profiler.
2005-07-28  Federico Mena Quintero  <federico@ximian.com>

	* perf/README: Update for the new API of the profiler.

	* perf/gtkwidgetprofiler.[ch]: New files with a widget profiler
	object.  This is the old content of timers.[ch] turned into a nice
	object, with signals for creation and reporting.  The profiler
	needs to maintain some state when reusing the widget, so it's
	useful to turn it into a real object.

	Break down timing show_all into GTK_WIDGET_PROFILER_REPORT_MAP and
	GTK_WIDGET_PROFILER_REPORT_EXPOSE.

	* perf/main.c: Refactor to use GtkWidgetProfiler.

	* perf/appwindow.c (content_area_new): Make this just create a
	notebook, instead of a complex arrangement of panes.

	* perf/widgets.h: New header file for all the "create a widget"
	utility functions.

	* perf/treeview.c: New file.  Moved the tree view part from
	appwindow.c over to here; GtkTreeView really needs its own tests.
	(tree_view_new): Set the shadow type to IN.

	* perf/textview.c: Likewise moved over from appwindow.c, but for
	GtkTextView.
	(text_view_new): Set the shadow type to IN.

	* perf/Makefile.am (testperf_SOURCES): Add the new source files;
	remove appwindow.h and timers.[ch].

	* perf/timers.[ch]: Removed.

	* perf/appwindow.h: Removed.
2005-07-29 00:38:51 +00:00

159 lines
4.5 KiB
Plaintext

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.