docs/reference/glib/tmpl/threads.sgml

   1 <!-- ##### SECTION Title ##### -->
   2
   3 Threads
   4
   5 <!-- ##### SECTION Short_Description ##### -->
   6
   7 thread abstraction; including mutexes, conditions and thread private data.
   8
   9 <!-- ##### SECTION Long_Description ##### -->
  10
  11 <para>
  12 Threads act almost like processes, but unlike processes all threads of
  13 one process share the same memory. This is good, as it provides easy
  14 communication between the involved threads via this shared memory, and
  15 it is bad, because strange things (so called Heisenbugs) might happen,
  16 when the program is not carefully designed. Especially bad is, that due
  17 to the concurrent nature of threads no assumptions on the order of
  18 execution of different threads can be done unless explictly forced by
  19 the programmer through synchronization primitives.
  20 </para>
  21
  22 <para>
  23 The aim of the thread related functions in GLib is to provide a
  24 portable means for writing multithread safe software. There are
  25 primitives for mutexes to protect the access to portions of memory
  26 (#GMutex, #GStaticMutex, #G_LOCK_DEFINE and friends), there are
  27 primitives for condition variables to allow synchronization of threads
  28 (#GCond) and finally there are primitives for thread-private data,
  29 that every thread has a private instance of (#GPrivate,
  30 #GStaticPrivate).
  31 </para>
  32
  33 <!-- ##### SECTION See_Also ##### -->
  34 <para>
  35
  36 </para>
  37
  38 <!-- ##### MACRO G_THREADS_ENABLED ##### -->
  39
  40 <para>
  41 This macro is defined, if GLib was compiled with thread support. This
  42 does not necessarily mean, that there is a thread implementation
  43 available, but the infrastructure is in place and once you provide a
  44 thread implementation to g_thread_init(), GLib will be multithread
  45 safe. It isn't and cannot be, if #G_THREADS_ENABLED is not defined.
  46 </para>
  47
  48
  49
  50 <!-- ##### MACRO G_THREADS_IMPL_POSIX ##### -->
  51
  52 <para>
  53 This macro is defined, if POSIX style threads are used.
  54 </para>
  55
  56
  57
  58 <!-- ##### MACRO G_THREADS_IMPL_SOLARIS ##### -->
  59
  60 <para>
  61 This macro is defined, if the SOLARIS thread system is used.
  62 </para>
  63
  64
  65
  66 <!-- ##### MACRO G_THREADS_IMPL_NONE ##### -->
  67
  68 <para>
  69 This macro is defined, if no thread implementation is used. You can
  70 however provide one to g_thread_init() to make GLib multithread safe.
  71 </para>
  72
  73
  74
  75 <!-- ##### MACRO G_THREAD_ERROR ##### -->
  76 <para>
  77
  78 </para>
  79
  80
  81
  82 <!-- ##### ENUM GThreadError ##### -->
  83 <para>
  84
  85 </para>
  86
  87 @G_THREAD_ERROR_AGAIN:
  88
  89 <!-- ##### STRUCT GThreadFunctions ##### -->
  90
  91 <para>
  92 This function table is used by g_thread_init() to initialize the
  93 thread system. The functions in that table are directly used by their
  94 g_* prepended counterparts, that are described here, e.g. if you call
  95 g_mutex_new() then mutex_new() from the table provided to
  96 g_thread_init() will be called.
  97 </para>
  98
  99 <note>
 100 <para>
 101 This struct should only be used, if you know, what you are doing.
 102 </para>
 103 </note>
 104
 105 @mutex_new:
 106 @mutex_lock:
 107 @mutex_trylock:
 108 @mutex_unlock:
 109 @mutex_free:
 110 @cond_new:
 111 @cond_signal:
 112 @cond_broadcast:
 113 @cond_wait:
 114 @cond_timed_wait:
 115 @cond_free:
 116 @private_new:
 117 @private_get:
 118 @private_set:
 119 @thread_create:
 120 @thread_yield:
 121 @thread_join:
 122 @thread_exit:
 123 @thread_set_priority:
 124 @thread_self:
 125
 126 <!-- ##### FUNCTION g_thread_init ##### -->
 127
 128 <para>
 129 Before you use a thread related function in GLib, you should
 130 initialize the thread system. This is done by calling
 131 g_thread_init(). Most of the time you will only have to call
 132 g_thread_init(NULL).
 133 </para>
 134
 135 <note>
 136 <para>
 137 You should only call g_thread_init() with a non-NULL parameter, if you
 138 really know, what you are doing.
 139 </para>
 140 </note>
 141
 142 <note>
 143 <para>
 144 g_thread_init() must not be called directly or indirectly as a
 145 callback from GLib.
 146 </para>
 147 </note>
 148
 149 <para>
 150 g_thread_init() might only be called once. On the second call
 151 it will abort with an error. If you want to make sure, that the thread
 152 system is initialized, you can do that too:
 153 </para>
 154
 155 <para>
 156 <informalexample>
 157 <programlisting>
 158 if (!g_thread_supported ()) g_thread_init (NULL);
 159 </programlisting>
 160 </informalexample>
 161 </para>
 162
 163 <para>
 164 After that line either the thread system is initialized or the program
 165 will abort, if no thread system is available in GLib, i.e. either
 166 #G_THREADS_ENABLED is not defined or #G_THREADS_IMPL_NONE is defined.
 167 </para>
 168
 169 <para>
 170 If no thread system is available and @vtable is NULL or if not all
 171 elements of @vtable are non-NULL, then g_thread_init() will abort.
 172 </para>
 173
 174 <note>
 175 <para>
 176 To use g_thread_init() in your program, you have to link with the
 177 libraries, that the command "glib-config --libs gthread" outputs. This
 178 is not the case for all the other thread related functions of
 179 GLib. Those can be used without having to link with the thread
 180 libraries.
 181 </para>
 182 </note>
 183
 184 @vtable: a function table of type #GThreadFunctions, that provides the
 185 entry points to the thread system to be used.
 186
 187
 188 <!-- ##### FUNCTION g_thread_supported ##### -->
 189 <para>
 190 This function returns, whether the thread system is initialized or
 191 not.
 192 </para>
 193
 194 <note>
 195 <para>
 196 This function is actually a macro. Apart from taking the address of it
 197 you can however use it as if it was a function.
 198 </para>
 199 </note>
 200
 201 @Returns: TRUE, if the thread system is initialized.
 202
 203
 204 <!-- ##### USER_FUNCTION GThreadFunc ##### -->
 205 <para>
 206
 207 </para>
 208
 209 @value:
 210
 211
 212 <!-- ##### ENUM GThreadPriority ##### -->
 213 <para>
 214
 215 </para>
 216
 217 @G_THREAD_PRIORITY_LOW:
 218 @G_THREAD_PRIORITY_NORMAL:
 219 @G_THREAD_PRIORITY_HIGH:
 220 @G_THREAD_PRIORITY_URGENT:
 221
 222 <!-- ##### STRUCT GThread ##### -->
 223 <para>
 224
 225 </para>
 226
 227 @priority:
 228 @bound:
 229 @joinable:
 230
 231 <!-- ##### FUNCTION g_thread_create ##### -->
 232 <para>
 233
 234 </para>
 235
 236 @thread_func:
 237 @arg:
 238 @stack_size:
 239 @joinable:
 240 @bound:
 241 @priority:
 242 @error:
 243 @Returns:
 244
 245
 246 <!-- ##### FUNCTION g_thread_self ##### -->
 247 <para>
 248
 249 </para>
 250
 251 @Returns:
 252
 253
 254 <!-- ##### FUNCTION g_thread_join ##### -->
 255 <para>
 256
 257 </para>
 258
 259 @thread:
 260
 261
 262 <!-- ##### FUNCTION g_thread_set_priority ##### -->
 263 <para>
 264
 265 </para>
 266
 267 @thread:
 268 @priority:
 269
 270
 271 <!-- ##### MACRO g_thread_yield ##### -->
 272 <para>
 273
 274 </para>
 275
 276
 277
 278 <!-- ##### MACRO g_thread_exit ##### -->
 279 <para>
 280
 281 </para>
 282
 283
 284
 285 <!-- ##### STRUCT GMutex ##### -->
 286
 287 <para>
 288 The #GMutex struct is an opaque data structure to represent a mutex
 289 (mutual exclusion). It can be used to protect data against shared
 290 access. Take for example the following function:
 291
 292 <example>
 293 <title>A function which will not work in a threaded environment</title>
 294 <programlisting>
 295   int give_me_next_number ()
 296   {
 297     static int current_number = 0;
 298
 299     /* now do a very complicated calculation to calculate the new number,
 300        this might for example be a random number generator */
 301     current_number = calc_next_number (current_number);
 302     return current_number;
 303   }
 304 </programlisting>
 305 </example>
 306 </para>
 307
 308 <para>
 309 It is easy to see, that this won't work in a multithreaded
 310 application. There current_number must be protected against shared
 311 access. A first naive implementation would be:
 312 </para>
 313
 314 <para>
 315 <example>
 316 <title>The wrong way to write a thread-safe function</title>
 317 <programlisting>
 318   int give_me_next_number ()
 319   {
 320     static int current_number = 0;
 321     int ret_val;
 322     static GMutex * mutex = NULL;
 323
 324     if (!mutex)
 325       mutex = g_mutex_new ();
 326     g_mutex_lock (mutex);
 327     ret_val = current_number = calc_next_number (current_number);
 328     g_mutex_unlock (mutex);
 329     return ret_val;
 330   }
 331 </programlisting>
 332 </example>
 333 </para>
 334
 335 <para>
 336 This looks like it would work, but there is a race condition while
 337 constructing the mutex and this code cannot work reliable. So please do
 338 not use such constructs in your own programs. One working solution is:
 339 </para>
 340
 341 <para>
 342 <example>
 343 <title>A correct thread-safe function</title>
 344 <programlisting>
 345   static GMutex *give_me_next_number_mutex = NULL;
 346
 347   /* this function must be called before any call to give_me_next_number ()
 348      it must be called exactly once. */
 349   void init_give_me_next_number ()
 350   {
 351     g_assert (give_me_next_number_mutex == NULL);
 352     give_me_next_number_mutex = g_mutex_new ();
 353   }
 354
 355   int give_me_next_number ()
 356   {
 357     static int current_number = 0;
 358     int ret_val;
 359
 360     g_mutex_lock (give_me_next_number_mutex);
 361     ret_val = current_number = calc_next_number (current_number);
 362     g_mutex_unlock (give_me_next_number_mutex);
 363     return ret_val;
 364   }
 365 </programlisting>
 366 </example>
 367 </para>
 368
 369 <para>
 370 #GStaticMutex provides a simpler and safer way of doing this.
 371 </para>
 372
 373 <para>
 374 If you want to use a mutex, but your code should also work without
 375 calling g_thread_init() first, you can not use a #GMutex, as
 376 g_mutex_new() requires that. Use a #GStaticMutex instead.
 377 </para>
 378
 379 <para>
 380 A #GMutex should only be accessed via the following functions.
 381 </para>
 382
 383 <note>
 384 <para>
 385 All of the g_mutex_* functions are actually macros. Apart from taking
 386 the addresses of them, you can however use them as if they were functions.
 387 </para>
 388 </note>
 389
 390
 391 <!-- ##### FUNCTION g_mutex_new ##### -->
 392
 393 <para>
 394 Creates a new #GMutex.
 395 </para>
 396
 397 <note>
 398 <para>
 399 This function will abort, if g_thread_init() has not been called yet.
 400 </para>
 401 </note>
 402
 403 @Returns: a new #GMutex.
 404
 405
 406 <!-- ##### FUNCTION g_mutex_lock ##### -->
 407
 408 <para>
 409 Locks the #GMutex. If the #GMutex is already locked by another thread,
 410 the current thread will block until the #GMutex is unlocked by the
 411 other thread.
 412 </para>
 413
 414 <para>
 415 This function can also be used, if g_thread_init() has not yet been
 416 called and will do nothing then.
 417 </para>
 418
 419 <note>
 420 <para>
 421 #GMutex is not guaranteed to be recursive, i.e. a thread might block,
 422 if it already has locked the #GMutex. It will deadlock then, of
 423 course.
 424 </para>
 425 </note>
 426
 427 @mutex: a #GMutex.
 428
 429
 430 <!-- ##### FUNCTION g_mutex_trylock ##### -->
 431
 432 <para>
 433 Tries to lock the #GMutex. If the #GMutex is already locked by another
 434 thread, it immediately returns FALSE. Otherwise it locks the #GMutex
 435 and returns TRUE.
 436 </para>
 437
 438 <para>
 439 This function can also be used, if g_thread_init() has not yet been
 440 called and will immediately return TRUE then.
 441 </para>
 442
 443 @mutex: a #GMutex.
 444 @Returns: TRUE, if the #GMutex could be locked.
 445
 446
 447 <!-- ##### FUNCTION g_mutex_unlock ##### -->
 448
 449 <para>
 450 Unlocks the #GMutex. If another thread is blocked in a g_mutex_lock()
 451 call, it will be woken and can lock the #GMutex itself. This function
 452 can also be used, if g_thread_init() has not yet been called and will
 453 do nothing then.
 454 </para>
 455
 456 @mutex: a #GMutex.
 457
 458
 459 <!-- ##### FUNCTION g_mutex_free ##### -->
 460
 461 <para>
 462 Destroys the #GMutex.
 463 </para>
 464
 465 @mutex: a #GMutex.
 466
 467
 468 <!-- ##### STRUCT GStaticMutex ##### -->
 469
 470 <para>
 471 A #GStaticMutex works like a #GMutex, but it has one significant
 472 advantage. It doesn't need to be created at run-time like a #GMutex,
 473 but can be defined at compile-time. Here is a shorter, easier and
 474 safer version of our give_me_next_number() example:
 475 </para>
 476
 477 <para>
 478 Sometimes you would like to dynamically create a mutex. If you don't
 479 want to require prior calling to g_thread_init(), because your code
 480 should also be usable in non-threaded programs, you are not able to
 481 use g_mutex_new() and thus #GMutex, as that requires a prior call to
 482 g_thread_init(). In theses cases you can also use a #GStaticMutex. It
 483 must be initialized with g_static_mutex_init() before using it and
 484 freed with with g_static_mutex_free() when not needed anymore to free
 485 up any allocated recourses.
 486 </para>
 487
 488 <para>
 489 <example>
 490 <title>Using GStaticMutex to simplify thread-safe programming</title>
 491 <programlisting>
 492   int give_me_next_number ()
 493   {
 494     static int current_number = 0;
 495     int ret_val;
 496     static GStaticMutex mutex = G_STATIC_MUTEX_INIT;
 497
 498     g_static_mutex_lock (&amp;mutex);
 499     ret_val = current_number = calc_next_number (current_number);
 500     g_static_mutex_unlock (&amp;mutex);
 501     return ret_val;
 502   }
 503 </programlisting>
 504 </example>
 505 </para>
 506
 507 <para>
 508 Even though #GStaticMutex is not opaque, it should only be used with
 509 the following functions, as it is defined differently on different
 510 platforms.
 511 </para>
 512
 513 <para>All of the g_static_mutex_* functions can also be used, if
 514 g_thread_init() has not yet.
 515 </para>
 516
 517 <note>
 518 <para>
 519 All of the g_static_mutex_* functions are actually macros. Apart from
 520 taking the addresses of them, you can however use them as if they were
 521 functions.
 522 </para>
 523 </note>
 524
 525
 526 <!-- ##### MACRO G_STATIC_MUTEX_INIT ##### -->
 527
 528 <para>
 529 A #GStaticMutex must be initialized with this macro, before it can be
 530 used. This macro can used be to initialize a variable, but it cannot
 531 be assigned to a variable. In that case you have to use
 532 g_static_mutex_init().
 533 </para>
 534
 535 <para>
 536 <example>
 537 <title>Initializing a GStaticMutext</title>
 538 <programlisting>
 539 GStaticMutex my_mutex = G_STATIC_MUTEX_INIT;
 540 </programlisting>
 541 </example>
 542 </para>
 543
 544
 545
 546 <!-- ##### FUNCTION g_static_mutex_init ##### -->
 547 <para>
 548 A #GStaticMutex must be initialized with this function, before it can
 549 be used. Alternatively you can initialize it with
 550 #G_STATIC_MUTEX_INIT.
 551 </para>
 552
 553 @mutex: a #GStaticMutex to be initialized.
 554
 555
 556 <!-- ##### FUNCTION g_static_mutex_lock ##### -->
 557 <para>
 558 works like g_mutex_lock(), but for a #GStaticMutex.
 559 </para>
 560
 561 @mutex: a #GStaticMutex.
 562
 563
 564 <!-- ##### FUNCTION g_static_mutex_trylock ##### -->
 565
 566 <para>
 567 works like g_mutex_trylock(), but for a #GStaticMutex.
 568 </para>
 569
 570 @mutex: a #GStaticMutex.
 571 @Returns: TRUE, if the #GStaticMutex could be locked.
 572
 573
 574 <!-- ##### FUNCTION g_static_mutex_unlock ##### -->
 575
 576 <para>
 577 works like g_mutex_unlock(), but for a #GStaticMutex.
 578 </para>
 579
 580 @mutex: a #GStaticMutex.
 581
 582
 583 <!-- ##### FUNCTION g_static_mutex_get_mutex ##### -->
 584
 585 <para>
 586 For some operations (like g_cond_wait()) you must have a #GMutex
 587 instead of a #GStaticMutex. This function will return the
 588 corresponding #GMutex for every #GStaticMutex.
 589 </para>
 590
 591 @mutex: a #GStaticMutex.
 592 @Returns: the corresponding #GMutex.
 593
 594
 595 <!-- ##### FUNCTION g_static_mutex_free ##### -->
 596 <para>
 597 Releases all resources allocated to a #GStaticMutex. You don't have to
 598 call this functions for a #GStaticMutex with an unbounded lifetime,
 599 i.e. objects declared 'static', but if you have a #GStaticMutex as a
 600 member of a structure and the structure is freed, you should also free
 601 the #GStaticMutex.
 602 </para>
 603
 604 @mutex: a #GStaticMutex.
 605
 606
 607 <!-- ##### MACRO G_LOCK_DEFINE ##### -->
 608
 609 <para>
 610 The G_LOCK_* macros provide a convenient interface to #GStaticMutex
 611 with the advantage that they will expand to nothing in programs
 612 compiled against a thread-disabled GLib, saving code and memory
 613 there. #G_LOCK_DEFINE defines a lock. It can occur, where variable
 614 definitions may occur in programs, i.e. in the first block of a
 615 function or outside of functions. The @name parameter will be mangled
 616 to get the name of the #GStaticMutex. This means, that you can use
 617 names of existing variables as the parameter, e.g. the name of the
 618 variable you intent to protect with the lock. Look at our
 619 give_me_next_number() example using the G_LOCK_* macros:
 620 </para>
 621
 622 <para>
 623 <example>
 624 <title>Using the G_LOCK_* convenience macros</title>
 625 <programlisting>
 626 G_LOCK_DEFINE (current_number);
 627
 628 int give_me_next_number ()
 629   {
 630     static int current_number = 0;
 631     int ret_val;
 632
 633     G_LOCK (current_number);
 634     ret_val = current_number = calc_next_number (current_number);
 635     G_UNLOCK (current_number);
 636     return ret_val;
 637   }
 638 </programlisting>
 639 </example>
 640 </para>
 641
 642 @name: the name of the lock.
 643
 644
 645 <!-- ##### MACRO G_LOCK_DEFINE_STATIC ##### -->
 646
 647 <para>
 648 This works like #G_LOCK_DEFINE, but it creates a static object.
 649 </para>
 650
 651 @name: the name of the lock.
 652
 653
 654 <!-- ##### MACRO G_LOCK_EXTERN ##### -->
 655
 656 <para>
 657 This declares a lock, that is defined with #G_LOCK_DEFINE in another module.
 658 </para>
 659
 660 @name: the name of the lock.
 661
 662
 663 <!-- ##### MACRO G_LOCK ##### -->
 664
 665 <para>
 666 works like g_mutex_lock(), but for a lock defined with #G_LOCK_DEFINE.
 667 </para>
 668
 669 @name: the name of the lock.
 670
 671
 672 <!-- ##### MACRO G_TRYLOCK ##### -->
 673
 674 <para>
 675 works like g_mutex_trylock(), but for a lock defined with #G_LOCK_DEFINE.
 676 </para>
 677
 678 @name: the name of the lock.
 679 @Returns: TRUE, if the lock could be locked.
 680
 681
 682 <!-- ##### MACRO G_UNLOCK ##### -->
 683
 684 <para>
 685 works like g_mutex_unlock(), but for a lock defined with #G_LOCK_DEFINE.
 686 </para>
 687
 688 @name: the name of the lock.
 689
 690
 691 <!-- ##### STRUCT GStaticRecMutex ##### -->
 692 <para>
 693
 694 </para>
 695
 696 @mutex:
 697 @depth:
 698 @owner:
 699
 700 <!-- ##### MACRO G_STATIC_REC_MUTEX_INIT ##### -->
 701 <para>
 702
 703 </para>
 704
 705
 706
 707 <!-- ##### FUNCTION g_static_rec_mutex_lock ##### -->
 708 <para>
 709
 710 </para>
 711
 712 @mutex:
 713
 714
 715 <!-- ##### FUNCTION g_static_rec_mutex_trylock ##### -->
 716 <para>
 717
 718 </para>
 719
 720 @mutex:
 721 @Returns:
 722
 723
 724 <!-- ##### FUNCTION g_static_rec_mutex_unlock ##### -->
 725 <para>
 726
 727 </para>
 728
 729 @mutex:
 730
 731
 732 <!-- ##### FUNCTION g_static_rec_mutex_lock_full ##### -->
 733 <para>
 734
 735 </para>
 736
 737 @mutex:
 738 @depth:
 739
 740
 741 <!-- ##### FUNCTION g_static_rec_mutex_unlock_full ##### -->
 742 <para>
 743
 744 </para>
 745
 746 @mutex:
 747 @Returns:
 748
 749
 750 <!-- ##### STRUCT GStaticRWLock ##### -->
 751 <para>
 752
 753 </para>
 754
 755 @mutex:
 756 @read_cond:
 757 @write_cond:
 758 @read_counter:
 759 @write:
 760 @want_to_write:
 761
 762 <!-- ##### MACRO G_STATIC_RW_LOCK_INIT ##### -->
 763 <para>
 764
 765 </para>
 766
 767
 768
 769 <!-- ##### FUNCTION g_static_rw_lock_reader_lock ##### -->
 770 <para>
 771
 772 </para>
 773
 774 @lock:
 775
 776
 777 <!-- ##### FUNCTION g_static_rw_lock_reader_trylock ##### -->
 778 <para>
 779
 780 </para>
 781
 782 @lock:
 783 @Returns:
 784
 785
 786 <!-- ##### FUNCTION g_static_rw_lock_reader_unlock ##### -->
 787 <para>
 788
 789 </para>
 790
 791 @lock:
 792
 793
 794 <!-- ##### FUNCTION g_static_rw_lock_writer_lock ##### -->
 795 <para>
 796
 797 </para>
 798
 799 @lock:
 800
 801
 802 <!-- ##### FUNCTION g_static_rw_lock_writer_trylock ##### -->
 803 <para>
 804
 805 </para>
 806
 807 @lock:
 808 @Returns:
 809
 810
 811 <!-- ##### FUNCTION g_static_rw_lock_writer_unlock ##### -->
 812 <para>
 813
 814 </para>
 815
 816 @lock:
 817
 818
 819 <!-- ##### FUNCTION g_static_rw_lock_free ##### -->
 820 <para>
 821
 822 </para>
 823
 824 @lock:
 825
 826
 827 <!-- ##### STRUCT GCond ##### -->
 828
 829 <para>
 830 The #GCond struct is an opaque data structure to represent a
 831 condition. A #GCond is an object, that threads can block on, if they
 832 find a certain condition to be false. If other threads change the
 833 state of this condition they can signal the #GCond, such that the
 834 waiting thread is woken up.
 835 </para>
 836
 837 <para>
 838 <example>
 839 <title>Using GCond to block a thread until a condition is satisfied</title>
 840 <programlisting>
 841 GCond* data_cond = NULL;   /* Must be initialized somewhere */
 842 GMutex* data_mutex = NULL; /* Must be initialized somewhere */
 843 gpointer current_data = NULL;
 844
 845 void push_data (gpointer data)
 846 {
 847   g_mutex_lock (data_mutex);
 848   current_data = data;
 849   g_cond_signal (data_cond);
 850   g_mutex_unlock (data_mutex);
 851 }
 852
 853 gpointer pop_data ()
 854 {
 855   gpointer data;
 856
 857   g_mutex_lock (data_mutex);
 858   while (!current_data)
 859       g_cond_wait (data_cond, data_mutex);
 860   data = current_data;
 861   current_data = NULL;
 862   g_mutex_unlock (data_mutex);
 863   return data;
 864 }
 865 </programlisting>
 866 </example>
 867 </para>
 868
 869 <para>
 870 Whenever a thread calls pop_data() now, it will wait until
 871 current_data is non-NULL, i.e. until some other thread has called
 872 push_data().
 873 </para>
 874
 875 <note>
 876 <para>
 877 It is important to use the g_cond_wait() and g_cond_timed_wait()
 878 functions only inside a loop, which checks for the condition to be
 879 true as it is not guaranteed that the waiting thread will find it
 880 fulfilled, even if the signaling thread left the condition
 881 in that state. This is because another thread can have altered the
 882 condition, before the waiting thread got the chance to be woken up,
 883 even if the condition itself is protected by a #GMutex, like above.
 884 </para>
 885 </note>
 886
 887 <para>
 888 A #GCond should only be accessed via the following functions.
 889 </para>
 890
 891 <note>
 892 <para>
 893 All of the g_cond_* functions are actually macros. Apart from taking
 894 the addresses of them, you can however use them as if they were functions.
 895 </para>
 896 </note>
 897
 898
 899 <!-- ##### FUNCTION g_cond_new ##### -->
 900
 901 <para>
 902 Creates a new #GCond. This function will abort, if g_thread_init()
 903 has not been called yet.
 904 </para>
 905
 906 @Returns: a new #GCond.
 907
 908
 909 <!-- ##### FUNCTION g_cond_signal ##### -->
 910 <para>
 911 If threads are waiting for @cond, exactly one of them is woken up. It
 912 is good practice to hold the same lock as the waiting thread, while
 913 calling this function, though not required.
 914 </para>
 915
 916 <para>
 917 This function can also be used, if g_thread_init() has
 918 not yet been called and will do nothing then.
 919 </para>
 920
 921 @cond: a #GCond.
 922
 923
 924 <!-- ##### FUNCTION g_cond_broadcast ##### -->
 925
 926 <para>
 927 If threads are waiting for @cond, all of them are woken up. It is good
 928 practice to lock the same mutex as the waiting threads, while calling
 929 this function, though not required.
 930 </para>
 931
 932 <para>
 933 This function can also be used, if g_thread_init() has
 934 not yet been called and will do nothing then.
 935 </para>
 936
 937 @cond: a #GCond.
 938
 939
 940 <!-- ##### FUNCTION g_cond_wait ##### -->
 941
 942 <para>
 943 Waits until this thread is woken up on the #GCond. The #GMutex is
 944 unlocked before falling asleep and locked again before resuming.
 945 </para>
 946
 947 <para>
 948 This function can also be used, if g_thread_init() has not yet been
 949 called and will immediately return then.
 950 </para>
 951
 952 @cond: a #GCond.
 953 @mutex: the #GMutex, that is currently locked.
 954
 955
 956 <!-- ##### FUNCTION g_cond_timed_wait ##### -->
 957
 958 <para>
 959 Waits until this thread is woken up on the #GCond, but not longer than
 960 until the time, that is specified by @abs_time. The #GMutex is
 961 unlocked before falling asleep and locked again before resuming.
 962 </para>
 963
 964 <para>
 965 If @abs_time is NULL, g_cond_timed_wait() acts like g_cond_wait().
 966 </para>
 967
 968 <para>
 969 This function can also be used, if g_thread_init() has not yet been
 970 called and will immediately return TRUE then.
 971 </para>
 972
 973 @cond: a #GCond.
 974 @mutex: the #GMutex, that is currently locked.
 975 @abs_time: a #GTimeVal, determining the final time.
 976 @Returns: TRUE, if the thread is woken up in time.
 977
 978
 979 <!-- ##### FUNCTION g_cond_free ##### -->
 980
 981 <para>
 982 Destroys the #GCond.
 983 </para>
 984
 985 @cond: a #GCond.
 986
 987
 988 <!-- ##### STRUCT GPrivate ##### -->
 989 <para>
 990 The #GPrivate struct is an opaque data structure to represent a thread
 991 private data key. Threads can thereby obtain and set a pointer, which
 992 is private to the current thread. Take our give_me_next_number()
 993 example from above.  Now we don't want current_number to be shared
 994 between the threads, but to be private to each thread. This can be
 995 done as follows:
 996
 997 <example>
 998 <title>Using GPrivate for per-thread data</title>
 999 <programlisting>
1000   GPrivate* current_number_key = NULL; /* Must be initialized somewhere */
1001                                        /* with g_private_new (g_free); */
1002
1003   int give_me_next_number ()
1004   {
1005     int *current_number = g_private_get (current_number_key);
1006
1007     if (!current_number)
1008     {
1009       current_number = g_new (int,1);
1010       *current_number = 0;
1011       g_private_set (current_number_key, current_number);
1012     }
1013     *current_number = calc_next_number (*current_number);
1014     return *current_number;
1015   }
1016 </programlisting>
1017 </example>
1018 </para>
1019
1020 <para>
1021 Here the pointer belonging to the key current_number_key is read. If
1022 it is NULL, it has not been set yet. Then get memory for an integer
1023 value, assign this memory to the pointer and write the pointer
1024 back. Now we have an integer value, that is private to the current
1025 thread.
1026 </para>
1027
1028 <para>
1029 The #GPrivate struct should only be accessed via the following functions.
1030 </para>
1031
1032 <note>
1033 <para>
1034 All of the g_private_* functions are actually macros. Apart from taking
1035 the addresses of them, you can however use them as if they were functions.
1036 </para>
1037 </note>
1038
1039
1040 <!-- ##### FUNCTION g_private_new ##### -->
1041
1042 <para>
1043 Creates a new #GPrivate. If @destructor is non-NULL, it is a pointer
1044 to a destructor function. Whenever a thread ends and the corresponding
1045 pointer keyed to this instance of #GPrivate is non-NULL, the
1046 destructor is called with this pointer as the argument.
1047 </para>
1048
1049 <note>
1050 <para>
1051 The @destructor is working quite differently from @notify in
1052 g_static_private_set().
1053 </para>
1054 </note>
1055
1056 <note>
1057 <para>
1058 A #GPrivate can not be destroyed. Reuse it instead, if you can to
1059 avoid shortage.
1060 </para>
1061 </note>
1062
1063 <note>
1064 <para>
1065 This function will abort, if g_thread_init() has not been called yet.
1066 </para>
1067 </note>
1068
1069 @destructor: a function to handle the data keyed to #GPrivate, when a
1070 thread ends.
1071 @Returns:
1072
1073
1074 <!-- ##### FUNCTION g_private_get ##### -->
1075
1076 <para>
1077 Returns the pointer keyed to @private_key for the current thread. This
1078 pointer is NULL, when g_private_set() hasn't been called for the
1079 current @private_key and thread yet.
1080 </para>
1081
1082 <para>
1083 This function can also be used, if g_thread_init() has not yet been
1084 called and will return the value of @private_key casted to #gpointer then.
1085 </para>
1086
1087 @private_key: a #GPrivate.
1088 @Returns: the corresponding pointer.
1089
1090
1091 <!-- ##### FUNCTION g_private_set ##### -->
1092
1093 <para>
1094 Sets the pointer keyed to @private_key for the current thread.
1095 </para>
1096
1097 <para>
1098 This function can also be used, if g_thread_init() has not yet been
1099 called and will set @private_key to @data casted to #GPrivate* then.
1100 </para>
1101
1102 @private_key: a #GPrivate.
1103 @data: the new pointer.
1104
1105
1106 <!-- ##### STRUCT GStaticPrivate ##### -->
1107
1108 <para>
1109 A #GStaticPrivate works almost like a #GPrivate, but it has one
1110 significant advantage. It doesn't need to be created at run-time like
1111 a #GPrivate, but can be defined at compile-time. This is similar to
1112 the difference between #GMutex and #GStaticMutex. Now look at our
1113 give_me_next_number() example with #GStaticPrivate:
1114 </para>
1115
1116 <para>
1117 <example>
1118 <title>Using GStaticPrivate for per-thread data</title>
1119 <programlisting>
1120   int give_me_next_number ()
1121   {
1122     static GStaticPrivate current_number_key = G_STATIC_PRIVATE_INIT;
1123     int *current_number = g_static_private_get (&amp;current_number_key);
1124
1125     if (!current_number)
1126     {
1127       current_number = g_new (int,1);
1128       *current_number = 0;
1129       g_static_private_set (&amp;current_number_key, current_number, g_free);
1130     }
1131     *current_number = calc_next_number (*current_number);
1132     return *current_number;
1133   }
1134 </programlisting>
1135 </example>
1136 </para>
1137
1138 @index:
1139
1140 <!-- ##### MACRO G_STATIC_PRIVATE_INIT ##### -->
1141 <para>
1142 Every #GStaticPrivate must be initialized with this macro, before it can
1143 be used.
1144 </para>
1145
1146 <para>
1147 <informalexample>
1148 <programlisting>
1149 GStaticPrivate my_private = G_STATIC_PRIVATE_INIT;
1150 </programlisting>
1151 </informalexample>
1152 </para>
1153
1154
1155
1156 <!-- ##### FUNCTION g_static_private_get ##### -->
1157 <para>
1158 Works like g_private_get() only for a #GStaticPrivate.
1159 </para>
1160
1161 <para>
1162 This function also works, if g_thread_init() has not yet been called.
1163 </para>
1164
1165 @private_key: a #GStaticPrivate.
1166 @Returns: the corresponding pointer.
1167
1168
1169 <!-- ##### FUNCTION g_static_private_get_for_thread ##### -->
1170 <para>
1171
1172 </para>
1173
1174 @private_key:
1175 @thread:
1176 @Returns:
1177
1178
1179 <!-- ##### FUNCTION g_static_private_set ##### -->
1180 <para>
1181 Sets the pointer keyed to @private_key for the current thread and the
1182 function @notify to be called with that pointer (NULL or non-NULL),
1183 whenever the pointer is set again or whenever the current thread ends.
1184 </para>
1185
1186 <para>
1187 This function also works, if g_thread_init() has not yet been
1188 called. If g_thread_init() is called later, the @data keyed to
1189 @private_key will be inherited only by the main thread, i.e. the one that
1190 called g_thread_init().
1191 </para>
1192
1193 <note>
1194 <para>
1195 The @notify is working quite differently from @destructor in
1196 g_private_new().
1197 </para>
1198 </note>
1199
1200 @private_key: a #GStaticPrivate.
1201 @data: the new pointer.
1202 @notify: a function to be called with the pointer, whenever the
1203 current thread ends or sets this pointer again.
1204
1205
1206 <!-- ##### FUNCTION g_static_private_set_for_thread ##### -->
1207 <para>
1208
1209 </para>
1210
1211 @private_key:
1212 @thread:
1213 @data:
1214 @notify:
1215
1216