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