glib/deprecated/gthread-deprecated.c

   1 /* GLIB - Library of useful routines for C programming
   2  * Copyright (C) 1995-1997  Peter Mattis, Spencer Kimball and Josh MacDonald
   3  *
   4  * gthread.c: MT safety related functions
   5  * Copyright 1998 Sebastian Wilhelmi; University of Karlsruhe
   6  *                Owen Taylor
   7  *
   8  * This library is free software; you can redistribute it and/or
   9  * modify it under the terms of the GNU Lesser General Public
  10  * License as published by the Free Software Foundation; either
  11  * version 2 of the License, or (at your option) any later version.
  12  *
  13  * This library is distributed in the hope that it will be useful,
  14  * but WITHOUT ANY WARRANTY; without even the implied warranty of
  15  * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the GNU
  16  * Lesser General Public License for more details.
  17  *
  18  * You should have received a copy of the GNU Lesser General Public
  19  * License along with this library; if not, write to the
  20  * Free Software Foundation, Inc., 59 Temple Place - Suite 330,
  21  * Boston, MA 02111-1307, USA.
  22  */
  23
  24 #include "config.h"
  25
  26 #include "gmessages.h"
  27 #include "gmain.h"
  28 #include "gthread.h"
  29 #include "gthreadprivate.h"
  30 #include "deprecated/gthread.h"
  31
  32 /* {{{1 Documentation */
  33
  34 /**
  35  * GThreadPriority:
  36  * @G_THREAD_PRIORITY_LOW: a priority lower than normal
  37  * @G_THREAD_PRIORITY_NORMAL: the default priority
  38  * @G_THREAD_PRIORITY_HIGH: a priority higher than normal
  39  * @G_THREAD_PRIORITY_URGENT: the highest priority
  40  *
  41  * Deprecated:2.32: thread priorities no longer have any effect.
  42  */
  43
  44 /**
  45  * GThreadFunctions:
  46  * @mutex_new: virtual function pointer for g_mutex_new()
  47  * @mutex_lock: virtual function pointer for g_mutex_lock()
  48  * @mutex_trylock: virtual function pointer for g_mutex_trylock()
  49  * @mutex_unlock: virtual function pointer for g_mutex_unlock()
  50  * @mutex_free: virtual function pointer for g_mutex_free()
  51  * @cond_new: virtual function pointer for g_cond_new()
  52  * @cond_signal: virtual function pointer for g_cond_signal()
  53  * @cond_broadcast: virtual function pointer for g_cond_broadcast()
  54  * @cond_wait: virtual function pointer for g_cond_wait()
  55  * @cond_timed_wait: virtual function pointer for g_cond_timed_wait()
  56  * @cond_free: virtual function pointer for g_cond_free()
  57  * @private_new: virtual function pointer for g_private_new()
  58  * @private_get: virtual function pointer for g_private_get()
  59  * @private_set: virtual function pointer for g_private_set()
  60  * @thread_create: virtual function pointer for g_thread_create()
  61  * @thread_yield: virtual function pointer for g_thread_yield()
  62  * @thread_join: virtual function pointer for g_thread_join()
  63  * @thread_exit: virtual function pointer for g_thread_exit()
  64  * @thread_set_priority: virtual function pointer for
  65  *                       g_thread_set_priority()
  66  * @thread_self: virtual function pointer for g_thread_self()
  67  * @thread_equal: used internally by recursive mutex locks and by some
  68  *                assertion checks
  69  *
  70  * This function table is no longer used by g_thread_init()
  71  * to initialize the thread system.
  72  */
  73
  74 /* {{{1 Exported Variables */
  75
  76 gboolean g_thread_use_default_impl = TRUE;
  77
  78 GThreadFunctions g_thread_functions_for_glib_use =
  79 {
  80   g_mutex_new,
  81   g_mutex_lock,
  82   g_mutex_trylock,
  83   g_mutex_unlock,
  84   g_mutex_free,
  85   g_cond_new,
  86   g_cond_signal,
  87   g_cond_broadcast,
  88   g_cond_wait,
  89   g_cond_timed_wait,
  90   g_cond_free,
  91   g_private_new,
  92   g_private_get,
  93   g_private_set,
  94   NULL,
  95   g_thread_yield,
  96   NULL,
  97   NULL,
  98   NULL,
  99   NULL,
 100   NULL,
 101 };
 102
 103 static guint64
 104 gettime (void)
 105 {
 106   return g_get_monotonic_time () * 1000;
 107 }
 108
 109 guint64 (*g_thread_gettime) (void) = gettime;
 110
 111 /* Misc. GThread functions {{{1 */
 112
 113 /**
 114  * g_thread_set_priority:
 115  * @thread: a #GThread.
 116  * @priority: ignored
 117  *
 118  * This function does nothing.
 119  *
 120  * Deprecated:2.32: Thread priorities no longer have any effect.
 121  */
 122 void
 123 g_thread_set_priority (GThread         *thread,
 124                        GThreadPriority  priority)
 125 {
 126 }
 127
 128 /**
 129  * g_thread_create_full:
 130  * @func: a function to execute in the new thread.
 131  * @data: an argument to supply to the new thread.
 132  * @stack_size: a stack size for the new thread.
 133  * @joinable: should this thread be joinable?
 134  * @bound: ignored
 135  * @priority: ignored
 136  * @error: return location for error.
 137  * @Returns: the new #GThread on success.
 138  *
 139  * This function creates a new thread.
 140  *
 141  * Deprecated:2.32: The @bound and @priority arguments are now ignored.
 142  * Use g_thread_create() or g_thread_create_with_stack_size() instead.
 143  */
 144 GThread *
 145 g_thread_create_full (GThreadFunc       func,
 146                       gpointer          data,
 147                       gulong            stack_size,
 148                       gboolean          joinable,
 149                       gboolean          bound,
 150                       GThreadPriority   priority,
 151                       GError          **error)
 152 {
 153   return g_thread_create_with_stack_size (func, data, joinable, stack_size, error);
 154 }
 155
 156 /* GStaticMutex {{{1 ------------------------------------------------------ */
 157
 158 /**
 159  * GStaticMutex:
 160  *
 161  * A #GStaticMutex works like a #GMutex.
 162  *
 163  * Prior to GLib 2.32, GStaticMutex had the significant advantage
 164  * that it doesn't need to be created at run-time, but can be defined
 165  * at compile-time. Since 2.32, #GMutex can be statically allocated
 166  * as well, and GStaticMutex has been deprecated.
 167  *
 168  * Here is a version of our give_me_next_number() example using
 169  * a GStaticMutex.
 170  *
 171  * <example>
 172  *  <title>
 173  *   Using <structname>GStaticMutex</structname>
 174  *   to simplify thread-safe programming
 175  *  </title>
 176  *  <programlisting>
 177  *   int
 178  *   give_me_next_number (void)
 179  *   {
 180  *     static int current_number = 0;
 181  *     int ret_val;
 182  *     static GStaticMutex mutex = G_STATIC_MUTEX_INIT;
 183  *
 184  *     g_static_mutex_lock (&amp;mutex);
 185  *     ret_val = current_number = calc_next_number (current_number);
 186  *     g_static_mutex_unlock (&amp;mutex);
 187  *
 188  *     return ret_val;
 189  *   }
 190  *  </programlisting>
 191  * </example>
 192  *
 193  * Sometimes you would like to dynamically create a mutex. If you don't
 194  * want to require prior calling to g_thread_init(), because your code
 195  * should also be usable in non-threaded programs, you are not able to
 196  * use g_mutex_new() and thus #GMutex, as that requires a prior call to
 197  * g_thread_init(). In theses cases you can also use a #GStaticMutex.
 198  * It must be initialized with g_static_mutex_init() before using it
 199  * and freed with with g_static_mutex_free() when not needed anymore to
 200  * free up any allocated resources.
 201  *
 202  * Even though #GStaticMutex is not opaque, it should only be used with
 203  * the following functions, as it is defined differently on different
 204  * platforms.
 205  *
 206  * All of the <function>g_static_mutex_*</function> functions apart
 207  * from <function>g_static_mutex_get_mutex</function> can also be used
 208  * even if g_thread_init() has not yet been called. Then they do
 209  * nothing, apart from <function>g_static_mutex_trylock</function>,
 210  * which does nothing but returning %TRUE.
 211  *
 212  * <note><para>All of the <function>g_static_mutex_*</function>
 213  * functions are actually macros. Apart from taking their addresses, you
 214  * can however use them as if they were functions.</para></note>
 215  **/
 216
 217 /**
 218  * G_STATIC_MUTEX_INIT:
 219  *
 220  * A #GStaticMutex must be initialized with this macro, before it can
 221  * be used. This macro can used be to initialize a variable, but it
 222  * cannot be assigned to a variable. In that case you have to use
 223  * g_static_mutex_init().
 224  *
 225  * |[
 226  * GStaticMutex my_mutex = G_STATIC_MUTEX_INIT;
 227  * ]|
 228  **/
 229
 230 /**
 231  * g_static_mutex_init:
 232  * @mutex: a #GStaticMutex to be initialized.
 233  *
 234  * Initializes @mutex.
 235  * Alternatively you can initialize it with #G_STATIC_MUTEX_INIT.
 236  *
 237  * Deprecated: 2.32: Use g_mutex_init()
 238  */
 239 void
 240 g_static_mutex_init (GStaticMutex *mutex)
 241 {
 242   static const GStaticMutex init_mutex = G_STATIC_MUTEX_INIT;
 243
 244   g_return_if_fail (mutex);
 245
 246   *mutex = init_mutex;
 247 }
 248
 249 /* IMPLEMENTATION NOTE:
 250  *
 251  * On some platforms a GStaticMutex is actually a normal GMutex stored
 252  * inside of a structure instead of being allocated dynamically.  We can
 253  * only do this for platforms on which we know, in advance, how to
 254  * allocate (size) and initialise (value) that memory.
 255  *
 256  * On other platforms, a GStaticMutex is nothing more than a pointer to
 257  * a GMutex.  In that case, the first access we make to the static mutex
 258  * must first allocate the normal GMutex and store it into the pointer.
 259  *
 260  * configure.ac writes macros into glibconfig.h to determine if
 261  * g_static_mutex_get_mutex() accesses the structure in memory directly
 262  * (on platforms where we are able to do that) or if it ends up here,
 263  * where we may have to allocate the GMutex before returning it.
 264  */
 265
 266 /**
 267  * g_static_mutex_get_mutex:
 268  * @mutex: a #GStaticMutex.
 269  * @Returns: the #GMutex corresponding to @mutex.
 270  *
 271  * For some operations (like g_cond_wait()) you must have a #GMutex
 272  * instead of a #GStaticMutex. This function will return the
 273  * corresponding #GMutex for @mutex.
 274  *
 275  * Deprecated: 2.32: Just use a #GMutex
 276  */
 277 GMutex *
 278 g_static_mutex_get_mutex_impl (GMutex** mutex)
 279 {
 280   GMutex *result;
 281
 282   if (!g_thread_supported ())
 283     return NULL;
 284
 285   result = g_atomic_pointer_get (mutex);
 286
 287   if (!result)
 288     {
 289       g_mutex_lock (&g_once_mutex);
 290
 291       result = *mutex;
 292       if (!result)
 293         {
 294           result = g_mutex_new ();
 295           g_atomic_pointer_set (mutex, result);
 296         }
 297
 298       g_mutex_unlock (&g_once_mutex);
 299     }
 300
 301   return result;
 302 }
 303
 304 /* IMPLEMENTATION NOTE:
 305  *
 306  * g_static_mutex_lock(), g_static_mutex_trylock() and
 307  * g_static_mutex_unlock() are all preprocessor macros that wrap the
 308  * corresponding g_mutex_*() function around a call to
 309  * g_static_mutex_get_mutex().
 310  */
 311
 312 /**
 313  * g_static_mutex_lock:
 314  * @mutex: a #GStaticMutex.
 315  *
 316  * Works like g_mutex_lock(), but for a #GStaticMutex.
 317  *
 318  * Deprecated: 2.32: Use g_mutex_lock()
 319  */
 320
 321 /**
 322  * g_static_mutex_trylock:
 323  * @mutex: a #GStaticMutex.
 324  * @Returns: %TRUE, if the #GStaticMutex could be locked.
 325  *
 326  * Works like g_mutex_trylock(), but for a #GStaticMutex.
 327  *
 328  * Deprecated: 2.32: Use g_mutex_trylock()
 329  */
 330
 331 /**
 332  * g_static_mutex_unlock:
 333  * @mutex: a #GStaticMutex.
 334  *
 335  * Works like g_mutex_unlock(), but for a #GStaticMutex.
 336  *
 337  * Deprecated: 2.32: Use g_mutex_unlock()
 338  */
 339
 340 /**
 341  * g_static_mutex_free:
 342  * @mutex: a #GStaticMutex to be freed.
 343  *
 344  * Releases all resources allocated to @mutex.
 345  *
 346  * You don't have to call this functions for a #GStaticMutex with an
 347  * unbounded lifetime, i.e. objects declared 'static', but if you have
 348  * a #GStaticMutex as a member of a structure and the structure is
 349  * freed, you should also free the #GStaticMutex.
 350  *
 351  * <note><para>Calling g_static_mutex_free() on a locked mutex may
 352  * result in undefined behaviour.</para></note>
 353  *
 354  * Deprecated: 2.32: Use g_mutex_free()
 355  */
 356 void
 357 g_static_mutex_free (GStaticMutex* mutex)
 358 {
 359   GMutex **runtime_mutex;
 360
 361   g_return_if_fail (mutex);
 362
 363   /* The runtime_mutex is the first (or only) member of GStaticMutex,
 364    * see both versions (of glibconfig.h) in configure.ac. Note, that
 365    * this variable is NULL, if g_thread_init() hasn't been called or
 366    * if we're using the default thread implementation and it provides
 367    * static mutexes. */
 368   runtime_mutex = ((GMutex**)mutex);
 369
 370   if (*runtime_mutex)
 371     g_mutex_free (*runtime_mutex);
 372
 373   *runtime_mutex = NULL;
 374 }
 375
 376 /* {{{1 GStaticRecMutex */
 377
 378 /**
 379  * GStaticRecMutex:
 380  *
 381  * A #GStaticRecMutex works like a #GStaticMutex, but it can be locked
 382  * multiple times by one thread. If you enter it n times, you have to
 383  * unlock it n times again to let other threads lock it. An exception
 384  * is the function g_static_rec_mutex_unlock_full(): that allows you to
 385  * unlock a #GStaticRecMutex completely returning the depth, (i.e. the
 386  * number of times this mutex was locked). The depth can later be used
 387  * to restore the state of the #GStaticRecMutex by calling
 388  * g_static_rec_mutex_lock_full(). In GLib 2.32, #GStaticRecMutex has
 389  * been deprecated in favor of #GRecMutex.
 390  *
 391  * Even though #GStaticRecMutex is not opaque, it should only be used
 392  * with the following functions.
 393  *
 394  * All of the <function>g_static_rec_mutex_*</function> functions can
 395  * be used even if g_thread_init() has not been called. Then they do
 396  * nothing, apart from <function>g_static_rec_mutex_trylock</function>,
 397  * which does nothing but returning %TRUE.
 398  **/
 399
 400 /**
 401  * G_STATIC_REC_MUTEX_INIT:
 402  *
 403  * A #GStaticRecMutex must be initialized with this macro before it can
 404  * be used. This macro can used be to initialize a variable, but it
 405  * cannot be assigned to a variable. In that case you have to use
 406  * g_static_rec_mutex_init().
 407  *
 408  * |[
 409  *   GStaticRecMutex my_mutex = G_STATIC_REC_MUTEX_INIT;
 410  * ]|
 411  */
 412
 413 /**
 414  * g_static_rec_mutex_init:
 415  * @mutex: a #GStaticRecMutex to be initialized.
 416  *
 417  * A #GStaticRecMutex must be initialized with this function before it
 418  * can be used. Alternatively you can initialize it with
 419  * #G_STATIC_REC_MUTEX_INIT.
 420  *
 421  * Deprecated: 2.32: Use g_rec_mutex_init()
 422  */
 423 void
 424 g_static_rec_mutex_init (GStaticRecMutex *mutex)
 425 {
 426   static const GStaticRecMutex init_mutex = G_STATIC_REC_MUTEX_INIT;
 427
 428   g_return_if_fail (mutex);
 429
 430   *mutex = init_mutex;
 431 }
 432
 433 /**
 434  * g_static_rec_mutex_lock:
 435  * @mutex: a #GStaticRecMutex to lock.
 436  *
 437  * Locks @mutex. If @mutex is already locked by another thread, the
 438  * current thread will block until @mutex is unlocked by the other
 439  * thread. If @mutex is already locked by the calling thread, this
 440  * functions increases the depth of @mutex and returns immediately.
 441  *
 442  * Deprecated: 2.32: Use g_rec_mutex_lock()
 443  */
 444 void
 445 g_static_rec_mutex_lock (GStaticRecMutex* mutex)
 446 {
 447   GSystemThread self;
 448
 449   g_return_if_fail (mutex);
 450
 451   if (!g_thread_supported ())
 452     return;
 453
 454   g_system_thread_self (&self);
 455
 456   if (g_system_thread_equal (&self, &mutex->owner))
 457     {
 458       mutex->depth++;
 459       return;
 460     }
 461   g_static_mutex_lock (&mutex->mutex);
 462   g_system_thread_assign (mutex->owner, self);
 463   mutex->depth = 1;
 464 }
 465
 466 /**
 467  * g_static_rec_mutex_trylock:
 468  * @mutex: a #GStaticRecMutex to lock.
 469  * @Returns: %TRUE, if @mutex could be locked.
 470  *
 471  * Tries to lock @mutex. If @mutex is already locked by another thread,
 472  * it immediately returns %FALSE. Otherwise it locks @mutex and returns
 473  * %TRUE. If @mutex is already locked by the calling thread, this
 474  * functions increases the depth of @mutex and immediately returns
 475  * %TRUE.
 476  *
 477  * Deprecated: 2.32: Use g_rec_mutex_trylock()
 478  */
 479 gboolean
 480 g_static_rec_mutex_trylock (GStaticRecMutex* mutex)
 481 {
 482   GSystemThread self;
 483
 484   g_return_val_if_fail (mutex, FALSE);
 485
 486   if (!g_thread_supported ())
 487     return TRUE;
 488
 489   g_system_thread_self (&self);
 490
 491   if (g_system_thread_equal (&self, &mutex->owner))
 492     {
 493       mutex->depth++;
 494       return TRUE;
 495     }
 496
 497   if (!g_static_mutex_trylock (&mutex->mutex))
 498     return FALSE;
 499
 500   g_system_thread_assign (mutex->owner, self);
 501   mutex->depth = 1;
 502   return TRUE;
 503 }
 504
 505 /**
 506  * g_static_rec_mutex_unlock:
 507  * @mutex: a #GStaticRecMutex to unlock.
 508  *
 509  * Unlocks @mutex. Another thread will be allowed to lock @mutex only
 510  * when it has been unlocked as many times as it had been locked
 511  * before. If @mutex is completely unlocked and another thread is
 512  * blocked in a g_static_rec_mutex_lock() call for @mutex, it will be
 513  * woken and can lock @mutex itself.
 514  *
 515  * Deprecated: 2.32: Use g_rec_mutex_unlock()
 516  */
 517 void
 518 g_static_rec_mutex_unlock (GStaticRecMutex* mutex)
 519 {
 520   g_return_if_fail (mutex);
 521
 522   if (!g_thread_supported ())
 523     return;
 524
 525   if (mutex->depth > 1)
 526     {
 527       mutex->depth--;
 528       return;
 529     }
 530   g_system_thread_assign (mutex->owner, zero_thread);
 531   g_static_mutex_unlock (&mutex->mutex);
 532 }
 533
 534 /**
 535  * g_static_rec_mutex_lock_full:
 536  * @mutex: a #GStaticRecMutex to lock.
 537  * @depth: number of times this mutex has to be unlocked to be
 538  *         completely unlocked.
 539  *
 540  * Works like calling g_static_rec_mutex_lock() for @mutex @depth times.
 541  *
 542  * Deprecated: 2.32: Use g_rec_mutex_lock()
 543  */
 544 void
 545 g_static_rec_mutex_lock_full (GStaticRecMutex *mutex,
 546                               guint            depth)
 547 {
 548   GSystemThread self;
 549   g_return_if_fail (mutex);
 550
 551   if (!g_thread_supported ())
 552     return;
 553
 554   if (depth == 0)
 555     return;
 556
 557   g_system_thread_self (&self);
 558
 559   if (g_system_thread_equal (&self, &mutex->owner))
 560     {
 561       mutex->depth += depth;
 562       return;
 563     }
 564   g_static_mutex_lock (&mutex->mutex);
 565   g_system_thread_assign (mutex->owner, self);
 566   mutex->depth = depth;
 567 }
 568
 569 /**
 570  * g_static_rec_mutex_unlock_full:
 571  * @mutex: a #GStaticRecMutex to completely unlock.
 572  * @Returns: number of times @mutex has been locked by the current
 573  *           thread.
 574  *
 575  * Completely unlocks @mutex. If another thread is blocked in a
 576  * g_static_rec_mutex_lock() call for @mutex, it will be woken and can
 577  * lock @mutex itself. This function returns the number of times that
 578  * @mutex has been locked by the current thread. To restore the state
 579  * before the call to g_static_rec_mutex_unlock_full() you can call
 580  * g_static_rec_mutex_lock_full() with the depth returned by this
 581  * function.
 582  *
 583  * Deprecated: 2.32: Use g_rec_mutex_unlock()
 584  */
 585 guint
 586 g_static_rec_mutex_unlock_full (GStaticRecMutex *mutex)
 587 {
 588   guint depth;
 589
 590   g_return_val_if_fail (mutex, 0);
 591
 592   if (!g_thread_supported ())
 593     return 1;
 594
 595   depth = mutex->depth;
 596
 597   g_system_thread_assign (mutex->owner, zero_thread);
 598   mutex->depth = 0;
 599   g_static_mutex_unlock (&mutex->mutex);
 600
 601   return depth;
 602 }
 603
 604 /**
 605  * g_static_rec_mutex_free:
 606  * @mutex: a #GStaticRecMutex to be freed.
 607  *
 608  * Releases all resources allocated to a #GStaticRecMutex.
 609  *
 610  * You don't have to call this functions for a #GStaticRecMutex with an
 611  * unbounded lifetime, i.e. objects declared 'static', but if you have
 612  * a #GStaticRecMutex as a member of a structure and the structure is
 613  * freed, you should also free the #GStaticRecMutex.
 614  *
 615  * Deprecated: 2.32: Use g_rec_mutex_clear()
 616  */
 617 void
 618 g_static_rec_mutex_free (GStaticRecMutex *mutex)
 619 {
 620   g_return_if_fail (mutex);
 621
 622   g_static_mutex_free (&mutex->mutex);
 623 }
 624
 625 /* GStaticRWLock {{{1 ----------------------------------------------------- */
 626
 627 /**
 628  * GStaticRWLock:
 629  *
 630  * The #GStaticRWLock struct represents a read-write lock. A read-write
 631  * lock can be used for protecting data that some portions of code only
 632  * read from, while others also write. In such situations it is
 633  * desirable that several readers can read at once, whereas of course
 634  * only one writer may write at a time. Take a look at the following
 635  * example:
 636  *
 637  * <example>
 638  *  <title>An array with access functions</title>
 639  *  <programlisting>
 640  *   GStaticRWLock rwlock = G_STATIC_RW_LOCK_INIT;
 641  *   GPtrArray *array;
 642  *
 643  *   gpointer
 644  *   my_array_get (guint index)
 645  *   {
 646  *     gpointer retval = NULL;
 647  *
 648  *     if (!array)
 649  *       return NULL;
 650  *
 651  *     g_static_rw_lock_reader_lock (&amp;rwlock);
 652  *     if (index &lt; array->len)
 653  *       retval = g_ptr_array_index (array, index);
 654  *     g_static_rw_lock_reader_unlock (&amp;rwlock);
 655  *
 656  *     return retval;
 657  *   }
 658  *
 659  *   void
 660  *   my_array_set (guint index, gpointer data)
 661  *   {
 662  *     g_static_rw_lock_writer_lock (&amp;rwlock);
 663  *
 664  *     if (!array)
 665  *       array = g_ptr_array_new (<!-- -->);
 666  *
 667  *     if (index >= array->len)
 668  *       g_ptr_array_set_size (array, index+1);
 669  *     g_ptr_array_index (array, index) = data;
 670  *
 671  *     g_static_rw_lock_writer_unlock (&amp;rwlock);
 672  *   }
 673  *  </programlisting>
 674  * </example>
 675  *
 676  * This example shows an array which can be accessed by many readers
 677  * (the <function>my_array_get()</function> function) simultaneously,
 678  * whereas the writers (the <function>my_array_set()</function>
 679  * function) will only be allowed once at a time and only if no readers
 680  * currently access the array. This is because of the potentially
 681  * dangerous resizing of the array. Using these functions is fully
 682  * multi-thread safe now.
 683  *
 684  * Most of the time, writers should have precedence over readers. That
 685  * means, for this implementation, that as soon as a writer wants to
 686  * lock the data, no other reader is allowed to lock the data, whereas,
 687  * of course, the readers that already have locked the data are allowed
 688  * to finish their operation. As soon as the last reader unlocks the
 689  * data, the writer will lock it.
 690  *
 691  * Even though #GStaticRWLock is not opaque, it should only be used
 692  * with the following functions.
 693  *
 694  * All of the <function>g_static_rw_lock_*</function> functions can be
 695  * used even if g_thread_init() has not been called. Then they do
 696  * nothing, apart from <function>g_static_rw_lock_*_trylock</function>,
 697  * which does nothing but returning %TRUE.
 698  *
 699  * <note><para>A read-write lock has a higher overhead than a mutex. For
 700  * example, both g_static_rw_lock_reader_lock() and
 701  * g_static_rw_lock_reader_unlock() have to lock and unlock a
 702  * #GStaticMutex, so it takes at least twice the time to lock and unlock
 703  * a #GStaticRWLock that it does to lock and unlock a #GStaticMutex. So
 704  * only data structures that are accessed by multiple readers, and which
 705  * keep the lock for a considerable time justify a #GStaticRWLock. The
 706  * above example most probably would fare better with a
 707  * #GStaticMutex.</para></note>
 708  *
 709  * Deprecated: 2.32: Use a #GRWLock instead
 710  **/
 711
 712 /**
 713  * G_STATIC_RW_LOCK_INIT:
 714  *
 715  * A #GStaticRWLock must be initialized with this macro before it can
 716  * be used. This macro can used be to initialize a variable, but it
 717  * cannot be assigned to a variable. In that case you have to use
 718  * g_static_rw_lock_init().
 719  *
 720  * |[
 721  *   GStaticRWLock my_lock = G_STATIC_RW_LOCK_INIT;
 722  * ]|
 723  */
 724
 725 /**
 726  * g_static_rw_lock_init:
 727  * @lock: a #GStaticRWLock to be initialized.
 728  *
 729  * A #GStaticRWLock must be initialized with this function before it
 730  * can be used. Alternatively you can initialize it with
 731  * #G_STATIC_RW_LOCK_INIT.
 732  *
 733  * Deprecated: 2.32: Use g_rw_lock_init() instead
 734  */
 735 void
 736 g_static_rw_lock_init (GStaticRWLock* lock)
 737 {
 738   static const GStaticRWLock init_lock = G_STATIC_RW_LOCK_INIT;
 739
 740   g_return_if_fail (lock);
 741
 742   *lock = init_lock;
 743 }
 744
 745 inline static void
 746 g_static_rw_lock_wait (GCond** cond, GStaticMutex* mutex)
 747 {
 748   if (!*cond)
 749       *cond = g_cond_new ();
 750   g_cond_wait (*cond, g_static_mutex_get_mutex (mutex));
 751 }
 752
 753 inline static void
 754 g_static_rw_lock_signal (GStaticRWLock* lock)
 755 {
 756   if (lock->want_to_write && lock->write_cond)
 757     g_cond_signal (lock->write_cond);
 758   else if (lock->want_to_read && lock->read_cond)
 759     g_cond_broadcast (lock->read_cond);
 760 }
 761
 762 /**
 763  * g_static_rw_lock_reader_lock:
 764  * @lock: a #GStaticRWLock to lock for reading.
 765  *
 766  * Locks @lock for reading. There may be unlimited concurrent locks for
 767  * reading of a #GStaticRWLock at the same time.  If @lock is already
 768  * locked for writing by another thread or if another thread is already
 769  * waiting to lock @lock for writing, this function will block until
 770  * @lock is unlocked by the other writing thread and no other writing
 771  * threads want to lock @lock. This lock has to be unlocked by
 772  * g_static_rw_lock_reader_unlock().
 773  *
 774  * #GStaticRWLock is not recursive. It might seem to be possible to
 775  * recursively lock for reading, but that can result in a deadlock, due
 776  * to writer preference.
 777  *
 778  * Deprecated: 2.32: Use g_rw_lock_reader_lock() instead
 779  */
 780 void
 781 g_static_rw_lock_reader_lock (GStaticRWLock* lock)
 782 {
 783   g_return_if_fail (lock);
 784
 785   if (!g_threads_got_initialized)
 786     return;
 787
 788   g_static_mutex_lock (&lock->mutex);
 789   lock->want_to_read++;
 790   while (lock->have_writer || lock->want_to_write)
 791     g_static_rw_lock_wait (&lock->read_cond, &lock->mutex);
 792   lock->want_to_read--;
 793   lock->read_counter++;
 794   g_static_mutex_unlock (&lock->mutex);
 795 }
 796
 797 /**
 798  * g_static_rw_lock_reader_trylock:
 799  * @lock: a #GStaticRWLock to lock for reading.
 800  * @Returns: %TRUE, if @lock could be locked for reading.
 801  *
 802  * Tries to lock @lock for reading. If @lock is already locked for
 803  * writing by another thread or if another thread is already waiting to
 804  * lock @lock for writing, immediately returns %FALSE. Otherwise locks
 805  * @lock for reading and returns %TRUE. This lock has to be unlocked by
 806  * g_static_rw_lock_reader_unlock().
 807  *
 808  * Deprectated: 2.32: Use g_rw_lock_reader_trylock() instead
 809  */
 810 gboolean
 811 g_static_rw_lock_reader_trylock (GStaticRWLock* lock)
 812 {
 813   gboolean ret_val = FALSE;
 814
 815   g_return_val_if_fail (lock, FALSE);
 816
 817   if (!g_threads_got_initialized)
 818     return TRUE;
 819
 820   g_static_mutex_lock (&lock->mutex);
 821   if (!lock->have_writer && !lock->want_to_write)
 822     {
 823       lock->read_counter++;
 824       ret_val = TRUE;
 825     }
 826   g_static_mutex_unlock (&lock->mutex);
 827   return ret_val;
 828 }
 829
 830 /**
 831  * g_static_rw_lock_reader_unlock:
 832  * @lock: a #GStaticRWLock to unlock after reading.
 833  *
 834  * Unlocks @lock. If a thread waits to lock @lock for writing and all
 835  * locks for reading have been unlocked, the waiting thread is woken up
 836  * and can lock @lock for writing.
 837  *
 838  * Deprectated: 2.32: Use g_rw_lock_reader_unlock() instead
 839  */
 840 void
 841 g_static_rw_lock_reader_unlock  (GStaticRWLock* lock)
 842 {
 843   g_return_if_fail (lock);
 844
 845   if (!g_threads_got_initialized)
 846     return;
 847
 848   g_static_mutex_lock (&lock->mutex);
 849   lock->read_counter--;
 850   if (lock->read_counter == 0)
 851     g_static_rw_lock_signal (lock);
 852   g_static_mutex_unlock (&lock->mutex);
 853 }
 854
 855 /**
 856  * g_static_rw_lock_writer_lock:
 857  * @lock: a #GStaticRWLock to lock for writing.
 858  *
 859  * Locks @lock for writing. If @lock is already locked for writing or
 860  * reading by other threads, this function will block until @lock is
 861  * completely unlocked and then lock @lock for writing. While this
 862  * functions waits to lock @lock, no other thread can lock @lock for
 863  * reading. When @lock is locked for writing, no other thread can lock
 864  * @lock (neither for reading nor writing). This lock has to be
 865  * unlocked by g_static_rw_lock_writer_unlock().
 866  *
 867  * Deprectated: 2.32: Use g_rw_lock_writer_lock() instead
 868  */
 869 void
 870 g_static_rw_lock_writer_lock (GStaticRWLock* lock)
 871 {
 872   g_return_if_fail (lock);
 873
 874   if (!g_threads_got_initialized)
 875     return;
 876
 877   g_static_mutex_lock (&lock->mutex);
 878   lock->want_to_write++;
 879   while (lock->have_writer || lock->read_counter)
 880     g_static_rw_lock_wait (&lock->write_cond, &lock->mutex);
 881   lock->want_to_write--;
 882   lock->have_writer = TRUE;
 883   g_static_mutex_unlock (&lock->mutex);
 884 }
 885
 886 /**
 887  * g_static_rw_lock_writer_trylock:
 888  * @lock: a #GStaticRWLock to lock for writing.
 889  * @Returns: %TRUE, if @lock could be locked for writing.
 890  *
 891  * Tries to lock @lock for writing. If @lock is already locked (for
 892  * either reading or writing) by another thread, it immediately returns
 893  * %FALSE. Otherwise it locks @lock for writing and returns %TRUE. This
 894  * lock has to be unlocked by g_static_rw_lock_writer_unlock().
 895  *
 896  * Deprectated: 2.32: Use g_rw_lock_writer_trylock() instead
 897  */
 898 gboolean
 899 g_static_rw_lock_writer_trylock (GStaticRWLock* lock)
 900 {
 901   gboolean ret_val = FALSE;
 902
 903   g_return_val_if_fail (lock, FALSE);
 904
 905   if (!g_threads_got_initialized)
 906     return TRUE;
 907
 908   g_static_mutex_lock (&lock->mutex);
 909   if (!lock->have_writer && !lock->read_counter)
 910     {
 911       lock->have_writer = TRUE;
 912       ret_val = TRUE;
 913     }
 914   g_static_mutex_unlock (&lock->mutex);
 915   return ret_val;
 916 }
 917
 918 /**
 919  * g_static_rw_lock_writer_unlock:
 920  * @lock: a #GStaticRWLock to unlock after writing.
 921  *
 922  * Unlocks @lock. If a thread is waiting to lock @lock for writing and
 923  * all locks for reading have been unlocked, the waiting thread is
 924  * woken up and can lock @lock for writing. If no thread is waiting to
 925  * lock @lock for writing, and some thread or threads are waiting to
 926  * lock @lock for reading, the waiting threads are woken up and can
 927  * lock @lock for reading.
 928  *
 929  * Deprectated: 2.32: Use g_rw_lock_writer_unlock() instead
 930  */
 931 void
 932 g_static_rw_lock_writer_unlock (GStaticRWLock* lock)
 933 {
 934   g_return_if_fail (lock);
 935
 936   if (!g_threads_got_initialized)
 937     return;
 938
 939   g_static_mutex_lock (&lock->mutex);
 940   lock->have_writer = FALSE;
 941   g_static_rw_lock_signal (lock);
 942   g_static_mutex_unlock (&lock->mutex);
 943 }
 944
 945 /**
 946  * g_static_rw_lock_free:
 947  * @lock: a #GStaticRWLock to be freed.
 948  *
 949  * Releases all resources allocated to @lock.
 950  *
 951  * You don't have to call this functions for a #GStaticRWLock with an
 952  * unbounded lifetime, i.e. objects declared 'static', but if you have
 953  * a #GStaticRWLock as a member of a structure, and the structure is
 954  * freed, you should also free the #GStaticRWLock.
 955  *
 956  * Deprecated: 2.32: Use a #GRWLock instead
 957  */
 958 void
 959 g_static_rw_lock_free (GStaticRWLock* lock)
 960 {
 961   g_return_if_fail (lock);
 962
 963   if (lock->read_cond)
 964     {
 965       g_cond_free (lock->read_cond);
 966       lock->read_cond = NULL;
 967     }
 968   if (lock->write_cond)
 969     {
 970       g_cond_free (lock->write_cond);
 971       lock->write_cond = NULL;
 972     }
 973   g_static_mutex_free (&lock->mutex);
 974 }
 975
 976 /* vim: set foldmethod=marker: */
 977