request for review: description of GtkSignals

[David Benson <daveb idealab com>]

I am trying to write the signal section of the
Gtk+ Reference Doc.  I think I understand signals
fairly well (by reading the source code, primarily)
but I thought it would be good to post a preliminary
description.  Please point out any inaccuracies
or shortcomings of this description, but remember that
I'm trying to keep it brief.  (Also descriptions of each
individual function will help cope with the details.)

I know it is bad-form to crosspost, I am very sorry.
I am trying to solicit as much feedback as possible,
since I am taking the accuracy of this section
somewhat seriously.


			Thanks for your time,
			Dave Benson
			daveb@ffem.org

=====================================

Signals are a way to get notification when something happens.
Every GtkSignal is identified by a name (a string) and a GtkType
of a GtkObject.  When they are allocated initially
they are also assigned a unique unsigned integer.
Each is also tied to an array of types that describes
prototype of the function pointer(s) you may
connect to the signal.  Finally, every signal has
a default method that is given by a function pointer
in its class structure:  it is run every time the signal
is emitted.

Signals are used by everyone, but they are only
instantiated on a per class basis-- so you don't (and
probably can't) call gtk_signal_new unless you are writing
a new GtkObject type.

There are two basic actions in the signal handling game.
If you want notification of an event, you must _connect_
a function pointer/gpointer to that signal.  And if you
are the function which causes the event, you must _emit_
the signal.

A lot of the complexity in GtkSignal comes from the
parameter system.  When you define a GtkSignal (remember
that there is only one per class-instance/name pair),
you must specify the number of parameters and a list of
their GtkTypes; the return value is treated like a final
parameter which is a pointer to the return type.

The functions responsible for translating an array of GtkArgs
to your C compilers normal semantics are called Marshallers.
They are identified by return_value__parameter_list,
for example a C function returning a gboolean and taking a gint
can be invoked by the gtk_marshal_BOOL__INT function.

Finally, signals provide some reentrance protection.
This means that if you specify GTK_RUN_NO_RECURSE and you
are handling a signal and you somehow emit that signal
again, the call won't happen until the after the function
returns (also if you emit it multiple times, it is only
re-invoked once, in this mode).