docs/reference/gobject/tut_gsignal.xml

   1 <?xml version='1.0' encoding="ISO-8859-1"?>
   2   <chapter id="chapter-signal">
   3     <title>The GObject messaging system</title>
   4
   5     <sect1 id="closure">
   6       <title>Closures</title>
   7
   8       <para>
   9         Closures are central to the concept of asynchronous signal delivery
  10         which is widely used throughout GTK+ and GNOME applications. A Closure is an
  11         abstraction, a generic representation of a callback. It is a small structure
  12         which contains three objects:
  13         <itemizedlist>
  14           <listitem><para>a function pointer (the callback itself) whose prototype looks like:
  15 <programlisting>
  16 return_type function_callback (... , gpointer user_data);
  17 </programlisting>
  18           </para></listitem>
  19           <listitem><para>
  20              the user_data pointer which is passed to the callback upon invocation of the closure
  21             </para></listitem>
  22           <listitem><para>
  23              a function pointer which represents the destructor of the closure: whenever the
  24              closure's refcount reaches zero, this function will be called before the closure
  25              structure is freed.
  26             </para></listitem>
  27         </itemizedlist>
  28       </para>
  29
  30       <para>
  31         The <type><link linkend="GClosure">GClosure</link></type> structure represents the common functionality of all
  32         closure implementations: there exists a different Closure implementation for
  33         each separate runtime which wants to use the GObject type system.
  34         <footnote><para>
  35             In Practice, Closures sit at the boundary of language runtimes: if you are
  36             writing python code and one of your Python callback receives a signal from
  37             one of GTK+ widgets, the C code in GTK+ needs to execute your Python
  38             code. The Closure invoked by the GTK+ object invokes the Python callback:
  39             it behaves as a normal C object for GTK+ and as a normal Python object for
  40             python code.
  41           </para></footnote>
  42         The GObject library provides a simple <type><link linkend="GCClosure">GCClosure</link></type> type which
  43         is a specific implementation of closures to be used with C/C++ callbacks.
  44       </para>
  45       <para>
  46         A <type><link linkend="GClosure">GClosure</link></type> provides simple services:
  47         <itemizedlist>
  48           <listitem><para>
  49               Invocation (<function><link linkend="g-closure-invoke">g_closure_invoke</link></function>): this is what closures
  50               were created for: they hide the details of callback invocation from the
  51               callback invocator.
  52             </para></listitem>
  53           <listitem><para>
  54               Notification: the closure notifies listeners of certain events such as
  55               closure invocation, closure invalidation and closure finalization. Listeners
  56               can be registered with <function><link linkend="g-closure-add-finalize-notifier">g_closure_add_finalize_notifier</link></function>
  57               (finalization notification), <function><link linkend="g-closure-add-invalidate-notifier">g_closure_add_invalidate_notifier</link></function>
  58               (invalidation notification) and
  59               <function><link linkend="g-closure-add-marshal-guards">g_closure_add_marshal_guards</link></function> (invocation notification).
  60               There exist symmetric de-registration functions for finalization and invalidation
  61               events (<function><link linkend="g-closure-remove-finalize-notifier">g_closure_remove_finalize_notifier</link></function> and
  62               <function><link linkend="g-closure-remove-invalidate-notifier">g_closure_remove_invalidate_notifier</link></function>) but not for the invocation
  63               process.
  64               <footnote><para>
  65                   Closures are refcounted and notify listeners of their destruction in a two-stage
  66                   process: the invalidation notifiers are invoked before the finalization notifiers.
  67                 </para></footnote>
  68             </para></listitem>
  69         </itemizedlist>
  70       </para>
  71
  72       <sect2>
  73         <title>C Closures</title>
  74
  75         <para>
  76           If you are using C or C++
  77           to connect a callback to a given event, you will either use the simple <type><link linkend="GCClosure">GCClosure</link></type>s
  78           which have a pretty minimal API or the even simpler <function><link linkend="g-signal-connect">g_signal_connect</link></function>
  79           functions (which will be presented a bit later :).
  80           <programlisting>
  81 GClosure* g_cclosure_new (GCallback        callback_func,
  82                           gpointer         user_data,
  83                           GClosureNotify   destroy_data);
  84 GClosure* g_cclosure_new_swap (GCallback        callback_func,
  85                                gpointer         user_data,
  86                                GClosureNotify   destroy_data);
  87 GClosure* g_signal_type_cclosure_new (GType  itype,
  88                                       guint  struct_offset);
  89           </programlisting>
  90         </para>
  91
  92         <para>
  93           <function><link linkend="g-cclosure-new">g_cclosure_new</link></function> will create a new closure which can invoke the
  94           user-provided callback_func with the user-provided user_data as last parameter. When the closure
  95           is finalized (second stage of the destruction process), it will invoke the destroy_data function
  96           if the user has supplied one.
  97         </para>
  98
  99         <para>
 100           <function><link linkend="g-cclosure-new-swap">g_cclosure_new_swap</link></function> will create a new closure which can invoke the
 101           user-provided callback_func with the user-provided user_data as first parameter (instead of being the
 102     last parameter as with <function><link linkend="g-cclosure-new">g_cclosure_new</link></function>). When the closure
 103           is finalized (second stage of the destruction process), it will invoke the destroy_data
 104           function if the user has supplied one.
 105         </para>
 106       </sect2>
 107
 108       <sect2>
 109         <title>non-C closures (for the fearless).</title>
 110
 111         <para>
 112           As was explained above, Closures hide the details of callback invocation. In C,
 113           callback invocation is just like function invocation: it is a matter of creating
 114           the correct stack frame for the called function and executing a <emphasis>call</emphasis>
 115           assembly instruction.
 116         </para>
 117
 118         <para>
 119           C closure marshallers transform the array of GValues which represent
 120           the parameters to the target function into a C-style function parameter list, invoke
 121           the user-supplied C function with this new parameter list, get the return value of the
 122           function, transform it into a GValue and return this GValue to the marshaller caller.
 123         </para>
 124
 125         <para>
 126           The following code implements a simple marshaller in C for a C function which takes an
 127           integer as first parameter and returns void.
 128           <programlisting>
 129 g_cclosure_marshal_VOID__INT (GClosure     *closure,
 130                               GValue       *return_value,
 131                               guint         n_param_values,
 132                               const GValue *param_values,
 133                               gpointer      invocation_hint,
 134                               gpointer      marshal_data)
 135 {
 136   typedef void (*GMarshalFunc_VOID__INT) (gpointer     data1,
 137                                           gint         arg_1,
 138                                           gpointer     data2);
 139   register GMarshalFunc_VOID__INT callback;
 140   register GCClosure *cc = (GCClosure*) closure;
 141   register gpointer data1, data2;
 142
 143   g_return_if_fail (n_param_values == 2);
 144
 145   data1 = g_value_peek_pointer (param_values + 0);
 146   data2 = closure->data;
 147
 148   callback = (GMarshalFunc_VOID__INT) (marshal_data ? marshal_data : cc->callback);
 149
 150   callback (data1,
 151             g_marshal_value_peek_int (param_values + 1),
 152             data2);
 153 }
 154           </programlisting>
 155         </para>
 156
 157         <para>
 158           Of course, there exist other kinds of marshallers. For example, James Henstridge
 159           wrote a generic Python marshaller which is used by all python Closures (a python closure
 160           is used to have python-based callback be invoked by the closure invocation process).
 161           This python marshaller transforms the input GValue list representing the function
 162           parameters into a Python tuple which is the equivalent structure in python (you can
 163           look in <function>pyg_closure_marshal</function> in <filename>pygtype.c</filename>
 164           in the <emphasis>pygobject</emphasis> module in GNOME cvs server).
 165         </para>
 166
 167       </sect2>
 168     </sect1>
 169
 170     <sect1 id="signal">
 171       <title>Signals</title>
 172
 173       <para>
 174         GObject's signals have nothing to do with standard UNIX signals: they connect
 175         arbitrary application-specific events with any number of listeners.
 176         For example, in GTK+, every user event (keystroke or mouse move) is received
 177         from the X server and generates a GTK+ event under the form of a signal emission
 178         on a given object instance.
 179       </para>
 180
 181       <para>
 182         Each signal is registered in the type system together with the type on which
 183         it can be emitted: users of the type are said to <emphasis>connect</emphasis>
 184         to the signal on a given type instance when they register a closure to be
 185         invoked upon the signal emission. Users can also emit the signal by themselves
 186         or stop the emission of the signal from within one of the closures connected
 187         to the signal.
 188       </para>
 189
 190       <para>
 191         When a signal is emitted on a given type instance, all the closures
 192         connected to this signal on this type instance will be invoked. All the closures
 193         connected to such a signal represent callbacks whose signature looks like:
 194 <programlisting>
 195 return_type function_callback (gpointer instance, ... , gpointer user_data);
 196 </programlisting>
 197       </para>
 198
 199       <sect2 id="signal-registration">
 200         <title>Signal registration</title>
 201
 202         <para>
 203           To register a new signal on an existing type, we can use any of <function><link linkend="g-signal-newv">g_signal_newv</link></function>,
 204           <function><link linkend="g-signal-new-valist">g_signal_new_valist</link></function> or <function><link linkend="g-signal-new">g_signal_new</link></function> functions:
 205 <programlisting>
 206 guint                 g_signal_newv         (const gchar        *signal_name,
 207                                              GType               itype,
 208                                              GSignalFlags        signal_flags,
 209                                              GClosure           *class_closure,
 210                                              GSignalAccumulator  accumulator,
 211                                              gpointer            accu_data,
 212                                              GSignalCMarshaller  c_marshaller,
 213                                              GType               return_type,
 214                                              guint               n_params,
 215                                              GType              *param_types);
 216 </programlisting>
 217         The number of parameters to these functions is a bit intimidating but they are relatively
 218         simple:
 219         <itemizedlist>
 220           <listitem><para>
 221               signal_name: is a string which can be used to uniquely identify a given signal.
 222             </para></listitem>
 223           <listitem><para>
 224               itype: is the instance type on which this signal can be emitted.
 225             </para></listitem>
 226           <listitem><para>
 227               signal_flags: partly defines the order in which closures which were connected to the
 228               signal are invoked.
 229             </para></listitem>
 230           <listitem><para>
 231               class_closure: this is the default closure for the signal: if it is not NULL upon
 232               the signal emission, it will be invoked upon this emission of the signal. The
 233               moment where this closure is invoked compared to other closures connected to that
 234               signal depends partly on the signal_flags.
 235             </para></listitem>
 236             <listitem><para>
 237               accumulator: this is a function pointer which is invoked after each closure
 238               has been invoked. If it returns FALSE, signal emission is stopped. If it returns
 239               TRUE, signal emission proceeds normally. It is also used to compute the return
 240               value of the signal based on the return value of all the invoked closures.
 241             </para></listitem>
 242           <listitem><para>
 243               accumulator_data: this pointer will be passed down to each invocation of the
 244               accumulator during emission.
 245             </para></listitem>
 246           <listitem><para>
 247               c_marshaller: this is the default C marshaller for any closure which is connected to
 248                 this signal.
 249             </para></listitem>
 250           <listitem><para>
 251               return_type: this is the type of the return value of the signal.
 252             </para></listitem>
 253           <listitem><para>
 254               n_params: this is the number of parameters this signal takes.
 255             </para></listitem>
 256           <listitem><para>
 257               param_types: this is an array of GTypes which indicate the type of each parameter
 258               of the signal. The length of this array is indicated by n_params.
 259             </para></listitem>
 260         </itemizedlist>
 261       </para>
 262
 263         <para>
 264           As you can see from the above definition, a signal is basically a description
 265           of the closures which can be connected to this signal and a description of the
 266           order in which the closures connected to this signal will be invoked.
 267         </para>
 268
 269       </sect2>
 270
 271       <sect2 id="signal-connection">
 272         <title>Signal connection</title>
 273
 274         <para>
 275           If you want to connect to a signal with a closure, you have three possibilities:
 276           <itemizedlist>
 277             <listitem><para>
 278                 You can register a class closure at signal registration: this is a
 279                 system-wide operation. i.e.: the class_closure will be invoked during each emission
 280                 of a given signal on all the instances of the type which supports that signal.
 281               </para></listitem>
 282             <listitem><para>
 283                 You can use <function><link linkend="g-signal-override-class-closure">g_signal_override_class_closure</link></function> which
 284                 overrides the class_closure of a given type. It is possible to call this function
 285                 only on a derived type of the type on which the signal was registered.
 286                 This function is of use only to language bindings.
 287               </para></listitem>
 288             <listitem><para>
 289                 You can register a closure with the <function><link linkend="g-signal-connect">g_signal_connect</link></function>
 290                 family of functions. This is an instance-specific operation: the closure
 291                 will be invoked only during emission of a given signal on a given instance.
 292               </para></listitem>
 293           </itemizedlist>
 294           It is also possible to connect a different kind of callback on a given signal:
 295           emission hooks are invoked whenever a given signal is emitted whatever the instance on
 296           which it is emitted. Emission hooks are used for example to get all mouse_clicked
 297           emissions in an application to be able to emit the small mouse click sound.
 298           Emission hooks are connected with <function><link linkend="g-signal-add-emission-hook">g_signal_add_emission_hook</link></function>
 299           and removed with <function><link linkend="g-signal-remove-emission-hook">g_signal_remove_emission_hook</link></function>.
 300         </para>
 301
 302         <para>
 303         </para>
 304
 305       </sect2>
 306
 307       <sect2 id="signal-emission">
 308         <title>Signal emission</title>
 309
 310         <para>
 311           Signal emission is done through the use of the <function><link linkend="g-signal-emit">g_signal_emit</link></function> family
 312           of functions.
 313 <programlisting>
 314 void                  g_signal_emitv        (const GValue       *instance_and_params,
 315                                              guint               signal_id,
 316                                              GQuark              detail,
 317                                              GValue             *return_value);
 318 </programlisting>
 319           <itemizedlist>
 320             <listitem><para>
 321                 The instance_and_params array of GValues contains the list of input
 322                 parameters to the signal. The first element of the array is the
 323                 instance pointer on which to invoke the signal. The following elements of
 324                 the array contain the list of parameters to the signal.
 325               </para></listitem>
 326             <listitem><para>
 327                 signal_id identifies the signal to invoke.
 328               </para></listitem>
 329             <listitem><para>
 330                 detail identifies the specific detail of the signal to invoke. A detail is a kind of
 331                 magic token/argument which is passed around during signal emission and which is used
 332                 by closures connected to the signal to filter out unwanted signal emissions. In most
 333                 cases, you can safely set this value to zero. See <xref linkend="signal-detail"/> for
 334                 more details about this parameter.
 335               </para></listitem>
 336             <listitem><para>
 337                 return_value holds the return value of the last closure invoked during emission if
 338                 no accumulator was specified. If an accumulator was specified during signal creation,
 339                 this accumulator is used to calculate the return_value as a function of the return
 340                 values of all the closures invoked during emission.
 341                 <footnote><para>
 342                     James (again!!) gives a few non-trivial examples of accumulators:
 343                     <quote>
 344                       For instance, you may have an accumulator that ignores NULL returns from
 345                       closures, and only accumulates the non-NULL ones. Another accumulator may try
 346                       to return the list of values returned by the closures.
 347                     </quote>
 348                   </para></footnote>
 349                 If no closure is invoked during
 350                 emission, the return_value is nonetheless initialized to zero/null.
 351               </para></listitem>
 352             </itemizedlist>
 353         </para>
 354
 355         <para>
 356           Internally, the GValue array is passed to the emission function proper,
 357           <function>signal_emit_unlocked_R</function> (implemented in <filename>gsignal.c</filename>).
 358           Signal emission can be decomposed in 5 steps:
 359           <itemizedlist>
 360             <listitem><para>
 361                 <emphasis>RUN_FIRST</emphasis>: if the G_SIGNAL_RUN_FIRST flag was used
 362                 during signal registration and if there exist a class_closure for this signal,
 363                 the class_closure is invoked. Jump to <emphasis>EMISSION_HOOK</emphasis> state.
 364               </para></listitem>
 365             <listitem><para>
 366                 <emphasis>EMISSION_HOOK</emphasis>: if any emission hook was added to
 367                 the signal, they are invoked from first to last added. Accumulate return values
 368                 and jump to <emphasis>HANDLER_RUN_FIRST</emphasis> state.
 369               </para></listitem>
 370             <listitem><para>
 371                 <emphasis>HANDLER_RUN_FIRST</emphasis>: if any closure were connected
 372                 with the <function><link linkend="g-signal-connect">g_signal_connect</link></function> family of
 373                 functions, and if they are not blocked (with the <function><link linkend="g-signal-handler-block">g_signal_handler_block</link></function>
 374                 family of functions) they are run here, from first to last connected.
 375                 Jump to <emphasis>RUN_LAST</emphasis> state.
 376               </para></listitem>
 377             <listitem><para>
 378                 <emphasis>RUN_LAST</emphasis>: if the G_SIGNAL_RUN_LAST
 379                 flag was set during registration and if a class_closure
 380                 was set, it is invoked here. Jump to
 381                 <emphasis>HANDLER_RUN_LAST</emphasis> state.
 382               </para></listitem>
 383             <listitem><para>
 384                 <emphasis>HANDLER_RUN_LAST</emphasis>: if any closure were connected
 385                 with the <function>g_signal_connect_after</function> family of
 386                 functions, if they were not invoked during HANDLER_RUN_FIRST and if they
 387                 are not blocked, they are run here, from first to last connected.
 388                 Jump to  <emphasis>RUN_CLEANUP</emphasis> state.
 389               </para></listitem>
 390             <listitem><para>
 391                 <emphasis>RUN_CLEANUP</emphasis>: if the G_SIGNAL_RUN_CLEANUP flag
 392                 was set during registration and if a class_closure was set,
 393                 it is invoked here. Signal emission is completed here.
 394               </para></listitem>
 395           </itemizedlist>
 396         </para>
 397
 398         <para>
 399           If, at any point during emission (except in RUN_CLEANUP state), one of the
 400           closures or emission hook stops the signal emission with
 401           <function><link linkend="g-signal-stop">g_signal_stop</link></function>, emission jumps to CLEANUP state.
 402         </para>
 403
 404         <para>
 405           If, at any point during emission, one of the closures or emission hook
 406           emits the same signal on the same instance, emission is restarted from
 407           the RUN_FIRST state.
 408         </para>
 409
 410         <para>
 411           The accumulator function is invoked in all states, after invocation
 412           of each closure (except in EMISSION_HOOK and CLEANUP). It accumulates
 413           the closure return value into the signal return value and returns TRUE or
 414           FALSE. If, at any point, it does not return TRUE, emission jumps to CLEANUP state.
 415         </para>
 416
 417         <para>
 418           If no accumulator function was provided, the value returned by the last handler
 419           run will be returned by <function><link linkend="g-signal-emit">g_signal_emit</link></function>.
 420         </para>
 421
 422       </sect2>
 423
 424
 425       <sect2 id="signal-detail">
 426         <title>The <emphasis>detail</emphasis> argument</title>
 427
 428         <para>All the functions related to signal emission or signal connection have a parameter
 429           named the <emphasis>detail</emphasis>. Sometimes, this parameter is hidden by the API
 430           but it is always there, under one form or another.
 431         </para>
 432
 433         <para>
 434          Of the three main connection functions,
 435           only one has an explicit detail parameter as a <type><link linkend="GQuark">GQuark</link></type>
 436           <footnote>
 437             <para>A GQuark is an integer which uniquely represents a string. It is possible to transform
 438              back and forth between the integer and string representations with the functions
 439              <function><link linkend="g-quark-from-string">g_quark_from_string</link></function> and <function><link linkend="g-quark-to-string">g_quark_to_string</link></function>.
 440             </para>
 441           </footnote>:
 442 <programlisting>
 443 gulong   g_signal_connect_closure_by_id       (gpointer           instance,
 444                                                guint              signal_id,
 445                                                GQuark             detail,
 446                                                GClosure          *closure,
 447                                                gboolean           after);
 448 </programlisting>
 449          The two other functions hide the detail parameter in the signal name identification:
 450 <programlisting>
 451 gulong   g_signal_connect_closure             (gpointer           instance,
 452                                                const gchar       *detailed_signal,
 453                                                GClosure          *closure,
 454                                                gboolean           after);
 455 gulong   g_signal_connect_data                (gpointer           instance,
 456                                                const gchar       *detailed_signal,
 457                                                GCallback          c_handler,
 458                                                gpointer           data,
 459                                                GClosureNotify     destroy_data,
 460                                                GConnectFlags      connect_flags);
 461 </programlisting>
 462           Their detailed_signal parameter is a string which identifies the name of the signal
 463           to connect to. However, the format of this string is structured to look like
 464           <emphasis>signal_name::detail_name</emphasis>. Connecting to the signal
 465           named <emphasis>notify::cursor_position</emphasis> will actually connect to the signal
 466           named <emphasis>notify</emphasis> with the <emphasis>cursor_position</emphasis> name.
 467           Internally, the detail string is transformed to a GQuark if it is present.
 468         </para>
 469
 470         <para>
 471           Of the four main signal emission functions, three have an explicit detail parameter as a
 472           <type><link linkend="GQuark">GQuark</link></type> again:
 473 <programlisting>
 474 void                  g_signal_emitv        (const GValue       *instance_and_params,
 475                                              guint               signal_id,
 476                                              GQuark              detail,
 477                                              GValue             *return_value);
 478 void                  g_signal_emit_valist  (gpointer            instance,
 479                                              guint               signal_id,
 480                                              GQuark              detail,
 481                                              va_list             var_args);
 482 void                  g_signal_emit         (gpointer            instance,
 483                                              guint               signal_id,
 484                                              GQuark              detail,
 485                                              ...);
 486 </programlisting>
 487          The fourth function hides it in its signal name parameter:
 488 <programlisting>
 489 void                  g_signal_emit_by_name (gpointer            instance,
 490                                              const gchar        *detailed_signal,
 491                                              ...);
 492 </programlisting>
 493          The format of the detailed_signal parameter is exactly the same as the format used by
 494          the <function><link linkend="g-signal-connect">g_signal_connect</link></function> functions: <emphasis>signal_name::detail_name</emphasis>.
 495         </para>
 496
 497         <para>
 498          If a detail is provided by the user to the emission function, it is used during emission to match
 499          against the closures which also provide a detail.
 500          If the closures' detail does not match the detail provided by the user, they will not be invoked
 501          (even though they are connected to a signal which is being emitted).
 502         </para>
 503
 504         <para>This completely optional filtering mechanism is mainly used as an optimization for signals
 505          which are often emitted for many different reasons: the clients can filter out which events they are
 506          interested into before the closure's marshalling code runs. For example, this is used extensively
 507          by the <emphasis>notify</emphasis> signal of GObject: whenever a property is modified on a GObject,
 508          instead of just emitting the <emphasis>notify</emphasis> signal, GObject associates as a detail to this
 509          signal emission the name of the property modified. This allows clients who wish to be notified of changes
 510          to only one property to filter most events before receiving them.
 511         </para>
 512
 513         <para>As a simple rule, users can and should set the detail parameter to zero: this will disable completely
 514          this optional filtering.
 515         </para>
 516
 517       </sect2>
 518
 519     </sect1>
 520   </chapter>