PageRenderTime 67ms CodeModel.GetById 49ms app.highlight 9ms RepoModel.GetById 1ms app.codeStats 1ms

/src/wrappers/glib/library/core/g_thread.e

http://github.com/tybor/Liberty
Specman e | 1516 lines | 57 code | 32 blank | 1427 comment | 0 complexity | 45a13d9f8e1473733c6bc698c8dcb4e3 MD5 | raw file

Large files files are truncated, but you can click here to view the full file

   1indexing
   2	description: "Threads — thread abstraction; including threads, different mutexes, conditions and thread private data"
   3	copyright: "(C) 2011 Paolo Redaelli"
   4	license: "LGPL v2 or later"
   5	version: "2.28"
   6
   7
   8deferred class G_THREAD
   9	obsolete "G_THREAD is currently unusable because standard library is NOT thread safe. At all"
  10	-- A thread of work.
  11	
  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	-- if the program is not carefully designed. In particular, due to the
  17	-- concurrent nature of threads, no assumptions on the order of execution
  18	-- of code running in different threads can be made, unless order is
  19	-- explicitly forced by the programmer through synchronization primitives.
  20
  21	-- The aim of the thread related functions in GLib is to provide a portable
  22	-- means for writing multi-threaded software. There are primitives for
  23	-- mutexes to protect the access to portions of memory (G_MUTEX,
  24	-- GStaticMutex, G_LOCK_DEFINE, GStaticRecMutex and GStaticRWLock). There
  25	-- are primitives for condition variables to allow synchronization of
  26	-- threads (GCond). There are primitives for thread-private data - data
  27	-- that every thread has a private instance of (GPrivate, GStaticPrivate).
  28	-- Last but definitely not least there are primitives to portably create
  29	-- and manage threads (GThread).
  30
  31
  32	-- When using G_THREADs in your program, you have to link with the
  33	-- libraries that the command pkg-config --libs gthread-2.0 outputs. This
  34	-- is not the case for all the other thread related functions of GLib.
  35	-- Those can be used without having to link with the thread libraries
  36	-- This will be hopefully automatized in further wrappers releases
  37
  38inherit
  39	WRAPPER 
  40		redefine default_create end
  41	EIFFEL_OWNED
  42		redefine default_create end
  43insert
  44	GTHREAD_EXTERNALS
  45		redefine default_create end
  46
  47feature 
  48	default_create is
  49		do
  50			-- Please note that since version 2.24 the GObject initialization
  51			-- function g_type_init() initializes threads (with a NULL
  52			-- argument), so most applications, including those using Gtk+ will
  53			-- run with threads enabled. If you want a special thread
  54			-- implementation, make sure you call g_thread_init() before
  55			-- g_type_init() is called. 
  56
  57			-- We are going to use threads so we need either to call
  58			g_thread_init(default_pointer)
  59			-- since version 2.24 g_thread_init may be called multiple times and nothing happens except for the first call.
  60			-- If no thread system is available and vtable is NULL or if not all elements of vtable are non-NULL, then g_thread_init() will abort.
  61			-- check is_thread_system_initialized  end
  62
  63
  64		end
  65
  66	run is
  67		-- The command invoked when the thread is started
  68		deferred
  69		end
  70
  71	start is
  72		-- Start Current thread as joinable.
  73
  74		-- TODO: add proper queries and setters for joinability, stack_size, priority
  75		local this: G_THREAD; priority: GTHREADPRIORITY_ENUM; stack_size: NATURAL_32
  76		do
  77			priority.set_normal
  78			this := Current
  79			from_external_pointer(g_thread_create_full
  80			($run,$this,stack_size,1,1,priority.value,default_pointer))
  81			-- GThread * g_thread_create (GThreadFunc func, gpointer data, gboolean joinable, GError **error);
  82			-- This function creates a new thread with the default priority.
  83			-- If joinable is TRUE, you can wait for this threads termination calling g_thread_join(). Otherwise the thread will just disappear when it terminates.
  84
  85			-- The new thread executes the function func with the argument data. If the thread was created successfully, it is returned.
  86
  87			-- error can be NULL to ignore errors, or non-NULL to report errors. The error is set, if and only if the function returns NULL.
  88			-- func :a function to execute in the new thread.
  89			-- data :an argument to supply to the new thread.
  90			-- joinable : should this thread be joinable?
  91			-- error : return location for error.
  92			-- Returns : the new GThread on success.
  93
  94			-- This function is currently implemented with a macro: #define g_thread_create(func, data, joinable, error)                    (g_thread_create_full (func, data, 0, joinable, FALSE,G_THREAD_PRIORITY_NORMAL, error))
  95
  96		end
  97feature -- Commands
  98	set_priority (a_priority: GTHREADPRIORITY_ENUM) is
  99		-- Changes the priority of Current thread to `a_priority'
 100
 101		-- It is not guaranteed that threads with different priorities really
 102		-- behave accordingly. On some systems (e.g. Linux) there are no thread
 103		-- priorities. On other systems (e.g. Solaris) there doesn't seem to be
 104		-- different scheduling for different priorities. All in all try to
 105		-- avoid being dependent on priorities.
 106	do
 107		g_thread_set_priority (handle, a_priority.value)
 108	end
 109
 110	join is
 111		-- Waits until Current thread finishes, i.e. the command `run` finish
 112		-- or `thread_exit' is called by thread. All resources of thread including the
 113		-- GThread struct are released. thread must have been created with
 114		-- joinable=TRUE in g_thread_create(). The value returned by func or
 115		-- given to g_thread_exit() by thread is returned by this function.
 116
 117		-- Returns : the return value of the thread.
 118	local p: POINTER
 119	do
 120		p := g_thread_join(handle) 
 121	end
 122
 123	yield is 
 124		-- Gives way to other threads waiting to be scheduled 
 125		-- This command is often used as a method to make busy wait less evil.
 126		-- But in most cases you will encounter, there are better methods to do
 127		-- that. So in general you shouldn't use it. 
 128
 129		-- Currenty unimplemented
 130	do
 131		not_yet_implemented
 132		-- g_thread_yield is a macro. wrappers_generator cannot handle this
 133	end
 134	
 135	thread_exit, finish is
 136		-- Exits the thread. If another thread is waiting for that thread using join and the current thread is joinable, the waiting thread will be woken up and get some_results as the result of join. If the current thread is not joinable, some_results are ignored.
 137
 138	require current_shall_not_be_part_of_a_pool: 
 139		-- Never call exit from within a thread of a G_THREAD_POOL, as that
 140		-- will mess up the bookkeeping and lead to funny and unwanted results.
 141	do
 142		g_thread_exit(default_pointer) --$some_results)
 143	end
 144
 145feature -- Process-wide queries 
 146	is_thread_system_initialized: BOOLEAN is
 147		-- Has the Glib thread system been initialized?
 148	do
 149		Result:=g_thread_get_initialized.to_boolean
 150	end
 151
 152
 153feature {} -- Unwrapped features
 154	
 155-- g_thread_create_full ()
 156-- 
 157-- GThread *           g_thread_create_full                (GThreadFunc func,
 158--                                                          gpointer data,
 159--                                                          gulong stack_size,
 160--                                                          gboolean joinable,
 161--                                                          gboolean bound,
 162--                                                          GThreadPriority priority,
 163--                                                          GError **error);
 164-- 
 165-- This function creates a new thread with the priority priority. If the underlying thread implementation supports it, the thread gets a stack size of stack_size or the default value for the current platform, if stack_size is 0.
 166-- 
 167-- If joinable is TRUE, you can wait for this threads termination calling g_thread_join(). Otherwise the thread will just disappear when it terminates. If bound is TRUE, this thread will be scheduled in the system scope, otherwise the implementation is free to do scheduling in the process scope. The first variant is more expensive resource-wise, but generally faster. On some systems (e.g. Linux) all threads are bound.
 168-- 
 169-- The new thread executes the function func with the argument data. If the thread was created successfully, it is returned.
 170-- 
 171-- error can be NULL to ignore errors, or non-NULL to report errors. The error is set, if and only if the function returns NULL.
 172-- 
 173-- Note
 174-- 
 175-- It is not guaranteed that threads with different priorities really behave accordingly. On some systems (e.g. Linux) there are no thread priorities. On other systems (e.g. Solaris) there doesn't seem to be different scheduling for different priorities. All in all try to avoid being dependent on priorities. Use G_THREAD_PRIORITY_NORMAL here as a default.
 176-- 
 177-- Note
 178-- 
 179-- Only use g_thread_create_full() if you really can't use g_thread_create() instead. g_thread_create() does not take stack_size, bound, and priority as arguments, as they should only be used in cases in which it is unavoidable.
 180-- 
 181-- func :
 182-- 	a function to execute in the new thread.
 183-- 
 184-- data :
 185-- 	an argument to supply to the new thread.
 186-- 
 187-- stack_size :
 188-- 	a stack size for the new thread.
 189-- 
 190-- joinable :
 191-- 	should this thread be joinable?
 192-- 
 193-- bound :
 194-- 	should this thread be bound to a system thread?
 195-- 
 196-- priority :
 197-- 	a priority for the thread.
 198-- 
 199-- error :
 200-- 	return location for error.
 201-- 
 202-- Returns :
 203-- 	the new GThread on success.
 204-- g_thread_self ()
 205-- 
 206-- GThread *           g_thread_self                       (void);
 207-- 
 208-- This functions returns the GThread corresponding to the calling thread.
 209-- 
 210-- Returns :
 211-- 	the current thread.
 212-- g_thread_join ()
 213-- 
 214-- gpointer            g_thread_join                       (GThread *thread);
 215-- 
 216-- Waits until thread finishes, i.e. the function func, as given to g_thread_create(), returns or g_thread_exit() is called by thread. All resources of thread including the GThread struct are released. thread must have been created with joinable=TRUE in g_thread_create(). The value returned by func or given to g_thread_exit() by thread is returned by this function.
 217-- 
 218-- thread :
 219-- 	a GThread to be waited for.
 220-- 
 221-- Returns :
 222-- 	the return value of the thread.
 223
 224-- g_thread_foreach ()
 225-- 
 226-- void                g_thread_foreach                    (GFunc thread_func,
 227--                                                          gpointer user_data);
 228-- 
 229-- Call thread_func on all existing GThread structures. Note that threads may decide to exit while thread_func is running, so without intimate knowledge about the lifetime of foreign threads, thread_func shouldn't access the GThread* pointer passed in as first argument. However, thread_func will not be called for threads which are known to have exited already.
 230-- 
 231-- Due to thread lifetime checks, this function has an execution complexity which is quadratic in the number of existing threads.
 232-- 
 233-- thread_func :
 234-- 	function to call for all GThread structures
 235-- 
 236-- user_data :
 237-- 	second argument to thread_func
 238-- 
 239-- Since 2.10
 240-- GMutex
 241-- 
 242-- typedef struct _GMutex GMutex;
 243-- 
 244-- The GMutex struct is an opaque data structure to represent a mutex (mutual exclusion). It can be used to protect data against shared access. Take for example the following function:
 245-- 
 246-- Example 2. A function which will not work in a threaded environment
 247-- 
 248-- 1
 249-- 2
 250-- 3
 251-- 4
 252-- 5
 253-- 6
 254-- 7
 255-- 8
 256-- 9
 257-- 10
 258-- 11
 259-- 12
 260-- 
 261-- 	
 262-- 
 263-- int
 264-- give_me_next_number (void)
 265-- {
 266--   static int current_number = 0;
 267-- 
 268--   /* now do a very complicated calculation to calculate the new
 269--    * number, this might for example be a random number generator
 270--    */
 271--   current_number = calc_next_number (current_number);
 272-- 
 273--   return current_number;
 274-- }
 275-- 
 276-- 
 277-- 
 278-- It is easy to see that this won't work in a multi-threaded application. There current_number must be protected against shared access. A first naive implementation would be:
 279-- 
 280-- Example 3. The wrong way to write a thread-safe function
 281-- 
 282-- 1
 283-- 2
 284-- 3
 285-- 4
 286-- 5
 287-- 6
 288-- 7
 289-- 8
 290-- 9
 291-- 10
 292-- 11
 293-- 12
 294-- 13
 295-- 14
 296-- 15
 297-- 
 298-- 	
 299-- 
 300-- int
 301-- give_me_next_number (void)
 302-- {
 303--   static int current_number = 0;
 304--   int ret_val;
 305--   static GMutex * mutex = NULL;
 306-- 
 307--   if (!mutex) mutex = g_mutex_new ();
 308-- 
 309--   g_mutex_lock (mutex);
 310--   ret_val = current_number = calc_next_number (current_number);
 311--   g_mutex_unlock (mutex);
 312-- 
 313--   return ret_val;
 314-- }
 315-- 
 316-- 
 317-- 
 318-- This looks like it would work, but there is a race condition while constructing the mutex and this code cannot work reliable. Please do not use such constructs in your own programs! One working solution is:
 319-- 
 320-- Example 4. A correct thread-safe function
 321-- 
 322-- 1
 323-- 2
 324-- 3
 325-- 4
 326-- 5
 327-- 6
 328-- 7
 329-- 8
 330-- 9
 331-- 10
 332-- 11
 333-- 12
 334-- 13
 335-- 14
 336-- 15
 337-- 16
 338-- 17
 339-- 18
 340-- 19
 341-- 20
 342-- 21
 343-- 22
 344-- 23
 345-- 24
 346-- 25
 347-- 26
 348-- 
 349-- 	
 350-- 
 351-- static GMutex *give_me_next_number_mutex = NULL;
 352-- 
 353-- /* this function must be called before any call to
 354--  * give_me_next_number()
 355--  *
 356--  * it must be called exactly once.
 357--  */
 358-- void
 359-- init_give_me_next_number (void)
 360-- {
 361--   g_assert (give_me_next_number_mutex == NULL);
 362--   give_me_next_number_mutex = g_mutex_new ();
 363-- }
 364-- 
 365-- int
 366-- give_me_next_number (void)
 367-- {
 368--   static int current_number = 0;
 369--   int ret_val;
 370-- 
 371--   g_mutex_lock (give_me_next_number_mutex);
 372--   ret_val = current_number = calc_next_number (current_number);
 373--   g_mutex_unlock (give_me_next_number_mutex);
 374-- 
 375--   return ret_val;
 376-- }
 377-- 
 378-- 
 379-- 
 380-- GStaticMutex provides a simpler and safer way of doing this.
 381-- 
 382-- If you want to use a mutex, and your code should also work without calling g_thread_init() first, then you can not use a GMutex, as g_mutex_new() requires that the thread system be initialized. Use a GStaticMutex instead.
 383-- 
 384-- A GMutex should only be accessed via the following functions.
 385-- 
 386-- Note
 387-- 
 388-- All of the g_mutex_* functions are actually macros. Apart from taking their addresses, you can however use them as if they were functions.
 389-- 
 390-- g_mutex_new ()
 391-- 
 392-- GMutex *            g_mutex_new                         ();
 393-- 
 394-- Creates a new GMutex.
 395-- 
 396-- Note
 397-- 
 398-- This function will abort if g_thread_init() has not been called yet.
 399-- 
 400-- Returns :
 401-- 	a new GMutex.
 402-- g_mutex_lock ()
 403-- 
 404-- void                g_mutex_lock                        (GMutex *mutex);
 405-- 
 406-- Locks mutex. If mutex is already locked by another thread, the current thread will block until mutex is unlocked by the other thread.
 407-- 
 408-- This function can be used even if g_thread_init() has not yet been called, and, in that case, will do nothing.
 409-- 
 410-- Note
 411-- 
 412-- GMutex is neither guaranteed to be recursive nor to be non-recursive, i.e. a thread could deadlock while calling g_mutex_lock(), if it already has locked mutex. Use GStaticRecMutex, if you need recursive mutexes.
 413-- 
 414-- mutex :
 415-- 	a GMutex.
 416-- g_mutex_trylock ()
 417-- 
 418-- gboolean            g_mutex_trylock                     (GMutex *mutex);
 419-- 
 420-- Tries to lock mutex. If mutex is already locked by another thread, it immediately returns FALSE. Otherwise it locks mutex and returns TRUE.
 421-- 
 422-- This function can be used even if g_thread_init() has not yet been called, and, in that case, will immediately return TRUE.
 423-- 
 424-- Note
 425-- 
 426-- GMutex is neither guaranteed to be recursive nor to be non-recursive, i.e. the return value of g_mutex_trylock() could be both FALSE or TRUE, if the current thread already has locked mutex. Use GStaticRecMutex, if you need recursive mutexes.
 427-- 
 428-- mutex :
 429-- 	a GMutex.
 430-- 
 431-- Returns :
 432-- 	TRUE, if mutex could be locked.
 433-- g_mutex_unlock ()
 434-- 
 435-- void                g_mutex_unlock                      (GMutex *mutex);
 436-- 
 437-- Unlocks mutex. If another thread is blocked in a g_mutex_lock() call for mutex, it will be woken and can lock mutex itself.
 438-- 
 439-- This function can be used even if g_thread_init() has not yet been called, and, in that case, will do nothing.
 440-- 
 441-- mutex :
 442-- 	a GMutex.
 443-- g_mutex_free ()
 444-- 
 445-- void                g_mutex_free                        (GMutex *mutex);
 446-- 
 447-- Destroys mutex.
 448-- 
 449-- Note
 450-- 
 451-- Calling g_mutex_free() on a locked mutex may result in undefined behaviour.
 452-- 
 453-- mutex :
 454-- 	a GMutex.
 455-- GStaticMutex
 456-- 
 457-- typedef struct _GStaticMutex GStaticMutex;
 458-- 
 459-- A GStaticMutex works like a GMutex, but it has one significant advantage. It doesn't need to be created at run-time like a GMutex, but can be defined at compile-time. Here is a shorter, easier and safer version of our give_me_next_number() example:
 460-- 
 461-- Example 5.  Using GStaticMutex to simplify thread-safe programming
 462-- 
 463-- 1
 464-- 2
 465-- 3
 466-- 4
 467-- 5
 468-- 6
 469-- 7
 470-- 8
 471-- 9
 472-- 10
 473-- 11
 474-- 12
 475-- 13
 476-- 
 477-- 	
 478-- 
 479-- int
 480-- give_me_next_number (void)
 481-- {
 482--   static int current_number = 0;
 483--   int ret_val;
 484--   static GStaticMutex mutex = G_STATIC_MUTEX_INIT;
 485-- 
 486--   g_static_mutex_lock (&mutex);
 487--   ret_val = current_number = calc_next_number (current_number);
 488--   g_static_mutex_unlock (&mutex);
 489-- 
 490--   return ret_val;
 491-- }
 492-- 
 493-- 
 494-- 
 495-- Sometimes you would like to dynamically create a mutex. If you don't want to require prior calling to g_thread_init(), because your code should also be usable in non-threaded programs, you are not able to use g_mutex_new() and thus GMutex, as that requires a prior call to g_thread_init(). In theses cases you can also use a GStaticMutex. It must be initialized with g_static_mutex_init() before using it and freed with with g_static_mutex_free() when not needed anymore to free up any allocated resources.
 496-- 
 497-- Even though GStaticMutex is not opaque, it should only be used with the following functions, as it is defined differently on different platforms.
 498-- 
 499-- All of the g_static_mutex_* functions apart from g_static_mutex_get_mutex can also be used even if g_thread_init() has not yet been called. Then they do nothing, apart from g_static_mutex_trylock, which does nothing but returning TRUE.
 500-- 
 501-- Note
 502-- 
 503-- All of the g_static_mutex_* functions are actually macros. Apart from taking their addresses, you can however use them as if they were functions.
 504-- 
 505-- G_STATIC_MUTEX_INIT
 506-- 
 507-- #define G_STATIC_MUTEX_INIT
 508-- 
 509-- A GStaticMutex must be initialized with this macro, before it can be used. This macro can used be to initialize a variable, but it cannot be assigned to a variable. In that case you have to use g_static_mutex_init().
 510-- 
 511-- 1
 512-- 
 513-- 	
 514-- 
 515-- GStaticMutex my_mutex = G_STATIC_MUTEX_INIT;
 516-- 
 517-- g_static_mutex_init ()
 518-- 
 519-- void                g_static_mutex_init                 (GStaticMutex *mutex);
 520-- 
 521-- Initializes mutex. Alternatively you can initialize it with G_STATIC_MUTEX_INIT.
 522-- 
 523-- mutex :
 524-- 	a GStaticMutex to be initialized.
 525-- g_static_mutex_lock ()
 526-- 
 527-- void                g_static_mutex_lock                 (GStaticMutex *mutex);
 528-- 
 529-- Works like g_mutex_lock(), but for a GStaticMutex.
 530-- 
 531-- mutex :
 532-- 	a GStaticMutex.
 533-- g_static_mutex_trylock ()
 534-- 
 535-- gboolean            g_static_mutex_trylock              (GStaticMutex *mutex);
 536-- 
 537-- Works like g_mutex_trylock(), but for a GStaticMutex.
 538-- 
 539-- mutex :
 540-- 	a GStaticMutex.
 541-- 
 542-- Returns :
 543-- 	TRUE, if the GStaticMutex could be locked.
 544-- g_static_mutex_unlock ()
 545-- 
 546-- void                g_static_mutex_unlock               (GStaticMutex *mutex);
 547-- 
 548-- Works like g_mutex_unlock(), but for a GStaticMutex.
 549-- 
 550-- mutex :
 551-- 	a GStaticMutex.
 552-- g_static_mutex_get_mutex ()
 553-- 
 554-- GMutex *            g_static_mutex_get_mutex            (GStaticMutex *mutex);
 555-- 
 556-- For some operations (like g_cond_wait()) you must have a GMutex instead of a GStaticMutex. This function will return the corresponding GMutex for mutex.
 557-- 
 558-- mutex :
 559-- 	a GStaticMutex.
 560-- 
 561-- Returns :
 562-- 	the GMutex corresponding to mutex.
 563-- g_static_mutex_free ()
 564-- 
 565-- void                g_static_mutex_free                 (GStaticMutex *mutex);
 566-- 
 567-- Releases all resources allocated to mutex.
 568-- 
 569-- You don't have to call this functions for a GStaticMutex with an unbounded lifetime, i.e. objects declared 'static', but if you have a GStaticMutex as a member of a structure and the structure is freed, you should also free the GStaticMutex.
 570-- 
 571-- Note
 572-- 
 573-- Calling g_static_mutex_free() on a locked mutex may result in undefined behaviour.
 574-- 
 575-- mutex :
 576-- 	a GStaticMutex to be freed.
 577-- G_LOCK_DEFINE()
 578-- 
 579-- #define G_LOCK_DEFINE(name)    
 580-- 
 581-- The G_LOCK_* macros provide a convenient interface to GStaticMutex with the advantage that they will expand to nothing in programs compiled against a thread-disabled GLib, saving code and memory there. G_LOCK_DEFINE defines a lock. It can appear anywhere variable definitions may appear in programs, i.e. in the first block of a function or outside of functions. The name parameter will be mangled to get the name of the GStaticMutex. This means that you can use names of existing variables as the parameter - e.g. the name of the variable you intent to protect with the lock. Look at our give_me_next_number() example using the G_LOCK_* macros:
 582-- 
 583-- Example 6. Using the G_LOCK_* convenience macros
 584-- 
 585-- 1
 586-- 2
 587-- 3
 588-- 4
 589-- 5
 590-- 6
 591-- 7
 592-- 8
 593-- 9
 594-- 10
 595-- 11
 596-- 12
 597-- 13
 598-- 14
 599-- 
 600-- 	
 601-- 
 602-- G_LOCK_DEFINE (current_number);
 603-- 
 604-- int
 605-- give_me_next_number (void)
 606-- {
 607--   static int current_number = 0;
 608--   int ret_val;
 609-- 
 610--   G_LOCK (current_number);
 611--   ret_val = current_number = calc_next_number (current_number);
 612--   G_UNLOCK (current_number);
 613-- 
 614--   return ret_val;
 615-- }
 616-- 
 617-- 
 618-- 
 619-- name :
 620-- 	the name of the lock.
 621-- G_LOCK_DEFINE_STATIC()
 622-- 
 623-- #define G_LOCK_DEFINE_STATIC(name)
 624-- 
 625-- This works like G_LOCK_DEFINE, but it creates a static object.
 626-- 
 627-- name :
 628-- 	the name of the lock.
 629-- G_LOCK_EXTERN()
 630-- 
 631-- #define G_LOCK_EXTERN(name)    
 632-- 
 633-- This declares a lock, that is defined with G_LOCK_DEFINE in another module.
 634-- 
 635-- name :
 636-- 	the name of the lock.
 637-- G_LOCK()
 638-- 
 639-- #define G_LOCK(name)
 640-- 
 641-- Works like g_mutex_lock(), but for a lock defined with G_LOCK_DEFINE.
 642-- 
 643-- name :
 644-- 	the name of the lock.
 645-- G_TRYLOCK()
 646-- 
 647-- #define G_TRYLOCK(name)
 648-- 
 649-- Works like g_mutex_trylock(), but for a lock defined with G_LOCK_DEFINE.
 650-- 
 651-- name :
 652-- 	the name of the lock.
 653-- 
 654-- Returns :
 655-- 	TRUE, if the lock could be locked.
 656-- G_UNLOCK()
 657-- 
 658-- #define G_UNLOCK(name)
 659-- 
 660-- Works like g_mutex_unlock(), but for a lock defined with G_LOCK_DEFINE.
 661-- 
 662-- name :
 663-- 	the name of the lock.
 664-- struct GStaticRecMutex
 665-- 
 666-- struct GStaticRecMutex {
 667-- };
 668-- 
 669-- A GStaticRecMutex works like a GStaticMutex, but it can be locked multiple times by one thread. If you enter it n times, you have to unlock it n times again to let other threads lock it. An exception is the function g_static_rec_mutex_unlock_full(): that allows you to unlock a GStaticRecMutex completely returning the depth, (i.e. the number of times this mutex was locked). The depth can later be used to restore the state of the GStaticRecMutex by calling g_static_rec_mutex_lock_full().
 670-- 
 671-- Even though GStaticRecMutex is not opaque, it should only be used with the following functions.
 672-- 
 673-- All of the g_static_rec_mutex_* functions can be used even if g_thread_init() has not been called. Then they do nothing, apart from g_static_rec_mutex_trylock, which does nothing but returning TRUE.
 674-- G_STATIC_REC_MUTEX_INIT
 675-- 
 676-- #define G_STATIC_REC_MUTEX_INIT { G_STATIC_MUTEX_INIT }
 677-- 
 678-- A GStaticRecMutex must be initialized with this macro before it can be used. This macro can used be to initialize a variable, but it cannot be assigned to a variable. In that case you have to use g_static_rec_mutex_init().
 679-- 
 680-- 1
 681-- 
 682-- 	
 683-- 
 684-- GStaticRecMutex my_mutex = G_STATIC_REC_MUTEX_INIT;
 685-- 
 686-- g_static_rec_mutex_init ()
 687-- 
 688-- void                g_static_rec_mutex_init             (GStaticRecMutex *mutex);
 689-- 
 690-- A GStaticRecMutex must be initialized with this function before it can be used. Alternatively you can initialize it with G_STATIC_REC_MUTEX_INIT.
 691-- 
 692-- mutex :
 693-- 	a GStaticRecMutex to be initialized.
 694-- g_static_rec_mutex_lock ()
 695-- 
 696-- void                g_static_rec_mutex_lock             (GStaticRecMutex *mutex);
 697-- 
 698-- Locks mutex. If mutex is already locked by another thread, the current thread will block until mutex is unlocked by the other thread. If mutex is already locked by the calling thread, this functions increases the depth of mutex and returns immediately.
 699-- 
 700-- mutex :
 701-- 	a GStaticRecMutex to lock.
 702-- g_static_rec_mutex_trylock ()
 703-- 
 704-- gboolean            g_static_rec_mutex_trylock          (GStaticRecMutex *mutex);
 705-- 
 706-- Tries to lock mutex. If mutex is already locked by another thread, it immediately returns FALSE. Otherwise it locks mutex and returns TRUE. If mutex is already locked by the calling thread, this functions increases the depth of mutex and immediately returns TRUE.
 707-- 
 708-- mutex :
 709-- 	a GStaticRecMutex to lock.
 710-- 
 711-- Returns :
 712-- 	TRUE, if mutex could be locked.
 713-- g_static_rec_mutex_unlock ()
 714-- 
 715-- void                g_static_rec_mutex_unlock           (GStaticRecMutex *mutex);
 716-- 
 717-- Unlocks mutex. Another thread will be allowed to lock mutex only when it has been unlocked as many times as it had been locked before. If mutex is completely unlocked and another thread is blocked in a g_static_rec_mutex_lock() call for mutex, it will be woken and can lock mutex itself.
 718-- 
 719-- mutex :
 720-- 	a GStaticRecMutex to unlock.
 721-- g_static_rec_mutex_lock_full ()
 722-- 
 723-- void                g_static_rec_mutex_lock_full        (GStaticRecMutex *mutex,
 724--                                                          guint depth);
 725-- 
 726-- Works like calling g_static_rec_mutex_lock() for mutex depth times.
 727-- 
 728-- mutex :
 729-- 	a GStaticRecMutex to lock.
 730-- 
 731-- depth :
 732-- 	number of times this mutex has to be unlocked to be completely unlocked.
 733-- g_static_rec_mutex_unlock_full ()
 734-- 
 735-- guint               g_static_rec_mutex_unlock_full      (GStaticRecMutex *mutex);
 736-- 
 737-- Completely unlocks mutex. If another thread is blocked in a g_static_rec_mutex_lock() call for mutex, it will be woken and can lock mutex itself. This function returns the number of times that mutex has been locked by the current thread. To restore the state before the call to g_static_rec_mutex_unlock_full() you can call g_static_rec_mutex_lock_full() with the depth returned by this function.
 738-- 
 739-- mutex :
 740-- 	a GStaticRecMutex to completely unlock.
 741-- 
 742-- Returns :
 743-- 	number of times mutex has been locked by the current thread.
 744-- g_static_rec_mutex_free ()
 745-- 
 746-- void                g_static_rec_mutex_free             (GStaticRecMutex *mutex);
 747-- 
 748-- Releases all resources allocated to a GStaticRecMutex.
 749-- 
 750-- You don't have to call this functions for a GStaticRecMutex with an unbounded lifetime, i.e. objects declared 'static', but if you have a GStaticRecMutex as a member of a structure and the structure is freed, you should also free the GStaticRecMutex.
 751-- 
 752-- mutex :
 753-- 	a GStaticRecMutex to be freed.
 754-- struct GStaticRWLock
 755-- 
 756-- struct GStaticRWLock {
 757-- };
 758-- 
 759-- The GStaticRWLock struct represents a read-write lock. A read-write lock can be used for protecting data that some portions of code only read from, while others also write. In such situations it is desirable that several readers can read at once, whereas of course only one writer may write at a time. Take a look at the following example:
 760-- 
 761-- Example 7. An array with access functions
 762-- 
 763-- 1
 764-- 2
 765-- 3
 766-- 4
 767-- 5
 768-- 6
 769-- 7
 770-- 8
 771-- 9
 772-- 10
 773-- 11
 774-- 12
 775-- 13
 776-- 14
 777-- 15
 778-- 16
 779-- 17
 780-- 18
 781-- 19
 782-- 20
 783-- 21
 784-- 22
 785-- 23
 786-- 24
 787-- 25
 788-- 26
 789-- 27
 790-- 28
 791-- 29
 792-- 30
 793-- 31
 794-- 32
 795-- 33
 796-- 
 797-- 	
 798-- 
 799-- GStaticRWLock rwlock = G_STATIC_RW_LOCK_INIT;
 800-- GPtrArray *array;
 801-- 
 802-- gpointer
 803-- my_array_get (guint index)
 804-- {
 805--   gpointer retval = NULL;
 806-- 
 807--   if (!array)
 808--     return NULL;
 809-- 
 810--   g_static_rw_lock_reader_lock (&rwlock);
 811--   if (index < array->len)
 812--     retval = g_ptr_array_index (array, index);
 813--   g_static_rw_lock_reader_unlock (&rwlock);
 814-- 
 815--   return retval;
 816-- }
 817-- 
 818-- void
 819-- my_array_set (guint index, gpointer data)
 820-- {
 821--   g_static_rw_lock_writer_lock (&rwlock);
 822-- 
 823--   if (!array)
 824--     array = g_ptr_array_new ();
 825-- 
 826--   if (index >= array->len)
 827--     g_ptr_array_set_size (array, index+1);
 828--   g_ptr_array_index (array, index) = data;
 829-- 
 830--   g_static_rw_lock_writer_unlock (&rwlock);
 831-- }
 832-- 
 833-- 
 834-- 
 835-- This example shows an array which can be accessed by many readers (the my_array_get() function) simultaneously, whereas the writers (the my_array_set() function) will only be allowed once at a time and only if no readers currently access the array. This is because of the potentially dangerous resizing of the array. Using these functions is fully multi-thread safe now.
 836-- 
 837-- Most of the time, writers should have precedence over readers. That means, for this implementation, that as soon as a writer wants to lock the data, no other reader is allowed to lock the data, whereas, of course, the readers that already have locked the data are allowed to finish their operation. As soon as the last reader unlocks the data, the writer will lock it.
 838-- 
 839-- Even though GStaticRWLock is not opaque, it should only be used with the following functions.
 840-- 
 841-- All of the g_static_rw_lock_* functions can be used even if g_thread_init() has not been called. Then they do nothing, apart from g_static_rw_lock_*_trylock, which does nothing but returning TRUE.
 842-- 
 843-- Note
 844-- 
 845-- A read-write lock has a higher overhead than a mutex. For example, both g_static_rw_lock_reader_lock() and g_static_rw_lock_reader_unlock() have to lock and unlock a GStaticMutex, so it takes at least twice the time to lock and unlock a GStaticRWLock that it does to lock and unlock a GStaticMutex. So only data structures that are accessed by multiple readers, and which keep the lock for a considerable time justify a GStaticRWLock. The above example most probably would fare better with a GStaticMutex.
 846-- 
 847-- G_STATIC_RW_LOCK_INIT
 848-- 
 849-- #define G_STATIC_RW_LOCK_INIT { G_STATIC_MUTEX_INIT, NULL, NULL, 0, FALSE, 0, 0 }
 850-- 
 851-- A GStaticRWLock must be initialized with this macro before it can be used. This macro can used be to initialize a variable, but it cannot be assigned to a variable. In that case you have to use g_static_rw_lock_init().
 852-- 
 853-- 1
 854-- 
 855-- 	
 856-- 
 857-- GStaticRWLock my_lock = G_STATIC_RW_LOCK_INIT;
 858-- 
 859-- g_static_rw_lock_init ()
 860-- 
 861-- void                g_static_rw_lock_init               (GStaticRWLock *lock);
 862-- 
 863-- A GStaticRWLock must be initialized with this function before it can be used. Alternatively you can initialize it with G_STATIC_RW_LOCK_INIT.
 864-- 
 865-- lock :
 866-- 	a GStaticRWLock to be initialized.
 867-- g_static_rw_lock_reader_lock ()
 868-- 
 869-- void                g_static_rw_lock_reader_lock        (GStaticRWLock *lock);
 870-- 
 871-- Locks lock for reading. There may be unlimited concurrent locks for reading of a GStaticRWLock at the same time. If lock is already locked for writing by another thread or if another thread is already waiting to lock lock for writing, this function will block until lock is unlocked by the other writing thread and no other writing threads want to lock lock. This lock has to be unlocked by g_static_rw_lock_reader_unlock().
 872-- 
 873-- GStaticRWLock is not recursive. It might seem to be possible to recursively lock for reading, but that can result in a deadlock, due to writer preference.
 874-- 
 875-- lock :
 876-- 	a GStaticRWLock to lock for reading.
 877-- g_static_rw_lock_reader_trylock ()
 878-- 
 879-- gboolean            g_static_rw_lock_reader_trylock     (GStaticRWLock *lock);
 880-- 
 881-- Tries to lock lock for reading. If lock is already locked for writing by another thread or if another thread is already waiting to lock lock for writing, immediately returns FALSE. Otherwise locks lock for reading and returns TRUE. This lock has to be unlocked by g_static_rw_lock_reader_unlock().
 882-- 
 883-- lock :
 884-- 	a GStaticRWLock to lock for reading.
 885-- 
 886-- Returns :
 887-- 	TRUE, if lock could be locked for reading.
 888-- g_static_rw_lock_reader_unlock ()
 889-- 
 890-- void                g_static_rw_lock_reader_unlock      (GStaticRWLock *lock);
 891-- 
 892-- Unlocks lock. If a thread waits to lock lock for writing and all locks for reading have been unlocked, the waiting thread is woken up and can lock lock for writing.
 893-- 
 894-- lock :
 895-- 	a GStaticRWLock to unlock after reading.
 896-- g_static_rw_lock_writer_lock ()
 897-- 
 898-- void                g_static_rw_lock_writer_lock        (GStaticRWLock *lock);
 899-- 
 900-- Locks lock for writing. If lock is already locked for writing or reading by other threads, this function will block until lock is completely unlocked and then lock lock for writing. While this functions waits to lock lock, no other thread can lock lock for reading. When lock is locked for writing, no other thread can lock lock (neither for reading nor writing). This lock has to be unlocked by g_static_rw_lock_writer_unlock().
 901-- 
 902-- lock :
 903-- 	a GStaticRWLock to lock for writing.
 904-- g_static_rw_lock_writer_trylock ()
 905-- 
 906-- gboolean            g_static_rw_lock_writer_trylock     (GStaticRWLock *lock);
 907-- 
 908-- Tries to lock lock for writing. If lock is already locked (for either reading or writing) by another thread, it immediately returns FALSE. Otherwise it locks lock for writing and returns TRUE. This lock has to be unlocked by g_static_rw_lock_writer_unlock().
 909-- 
 910-- lock :
 911-- 	a GStaticRWLock to lock for writing.
 912-- 
 913-- Returns :
 914-- 	TRUE, if lock could be locked for writing.
 915-- g_static_rw_lock_writer_unlock ()
 916-- 
 917-- void                g_static_rw_lock_writer_unlock      (GStaticRWLock *lock);
 918-- 
 919-- Unlocks lock. If a thread is waiting to lock lock for writing and all locks for reading have been unlocked, the waiting thread is woken up and can lock lock for writing. If no thread is waiting to lock lock for writing, and some thread or threads are waiting to lock lock for reading, the waiting threads are woken up and can lock lock for reading.
 920-- 
 921-- lock :
 922-- 	a GStaticRWLock to unlock after writing.
 923-- g_static_rw_lock_free ()
 924-- 
 925-- void                g_static_rw_lock_free               (GStaticRWLock *lock);
 926-- 
 927-- Releases all resources allocated to lock.
 928-- 
 929-- You don't have to call this functions for a GStaticRWLock with an unbounded lifetime, i.e. objects declared 'static', but if you have a GStaticRWLock as a member of a structure, and the structure is freed, you should also free the GStaticRWLock.
 930-- 
 931-- lock :
 932-- 	a GStaticRWLock to be freed.
 933-- GCond
 934-- 
 935-- typedef struct _GCond GCond;
 936-- 
 937-- The GCond struct is an opaque data structure that represents a condition. Threads can block on a GCond if they find a certain condition to be false. If other threads change the state of this condition they signal the GCond, and that causes the waiting threads to be woken up.
 938-- 
 939-- Example 8.  Using GCond to block a thread until a condition is satisfied
 940-- 
 941-- 1
 942-- 2
 943-- 3
 944-- 4
 945-- 5
 946-- 6
 947-- 7
 948-- 8
 949-- 9
 950-- 10
 951-- 11
 952-- 12
 953-- 13
 954-- 14
 955-- 15
 956-- 16
 957-- 17
 958-- 18
 959-- 19
 960-- 20
 961-- 21
 962-- 22
 963-- 23
 964-- 24
 965-- 25
 966-- 26
 967-- 27
 968-- 
 969-- 	
 970-- 
 971-- GCond* data_cond = NULL; /* Must be initialized somewhere */
 972-- GMutex* data_mutex = NULL; /* Must be initialized somewhere */
 973-- gpointer current_data = NULL;
 974-- 
 975-- void
 976-- push_data (gpointer data)
 977-- {
 978--   g_mutex_lock (data_mutex);
 979--   current_data = data;
 980--   g_cond_signal (data_cond);
 981--   g_mutex_unlock (data_mutex);
 982-- }
 983-- 
 984-- gpointer
 985-- pop_data (void)
 986-- {
 987--   gpointer data;
 988-- 
 989--   g_mutex_lock (data_mutex);
 990--   while (!current_data)
 991--     g_cond_wait (data_cond, data_mutex);
 992--   data = current_data;
 993--   current_data = NULL;
 994--   g_mutex_unlock (data_mutex);
 995-- 
 996--   return data;
 997-- }
 998-- 
 999-- 
1000-- 
1001-- Whenever a thread calls pop_data() now, it will wait until current_data is non-NULL, i.e. until some other thread has called push_data().
1002-- 
1003-- Note
1004-- 
1005-- It is important to use the g_cond_wait() and g_cond_timed_wait() functions only inside a loop which checks for the condition to be true. It is not guaranteed that the waiting thread will find the condition fulfilled after it wakes up, even if the signaling thread left the condition in that state: another thread may have altered the condition before the waiting thread got the chance to be woken up, even if the condition itself is protected by a GMutex, like above.
1006-- 
1007-- A GCond should only be accessed via the following functions.
1008-- 
1009-- Note
1010-- 
1011-- All of the g_cond_* functions are actually macros. Apart from taking their addresses, you can however use them as if they were functions.
1012-- 
1013-- g_cond_new ()
1014-- 
1015-- GCond*              g_cond_new                          ();
1016-- 
1017-- Creates a new GCond. This function will abort, if g_thread_init() has not been called yet.
1018-- 
1019-- Returns :
1020-- 	a new GCond.
1021-- g_cond_signal ()
1022-- 
1023-- void                g_cond_signal                       (GCond *cond);
1024-- 
1025-- If threads are waiting for cond, exactly one of them is woken up. It is good practice to hold the same lock as the waiting thread while calling this function, though not required.
1026-- 
1027-- This function can be used even if g_thread_init() has not yet been called, and, in that case, will do nothing.
1028-- 
1029-- cond :
1030-- 	a GCond.
1031-- g_cond_broadcast ()
1032-- 
1033-- void                g_cond_broadcast                    (GCond *cond);
1034-- 
1035-- If threads are waiting for cond, all of them are woken up. It is good practice to lock the same mutex as the waiting threads, while calling this function, though not required.
1036-- 
1037-- This function can be used even if g_thread_init() has not yet been called, and, in that case, will do nothing.
1038-- 
1039-- cond :
1040-- 	a GCond.
1041-- g_cond_wait ()
1042-- 
1043-- void                g_cond_wait                         (GCond *cond,
1044--                                                          GMutex *mutex);
1045-- 
1046-- Waits until this thread is woken up on cond. The mutex is unlocked before falling asleep and locked again before resuming.
1047-- 
1048-- This function can be used even if g_thread_init() has not yet been called, and, in that case, will immediately return.
1049-- 
1050-- cond :
1051-- 	a GCond.
1052-- 
1053-- mutex :
1054-- 	a GMutex, that is currently locked.
1055-- g_cond_timed_wait ()
1056-- 
1057-- gboolean            g_cond_timed_wait                   (GCond *cond,
1058--                                                          GMutex *mutex,
1059--                                                          GTimeVal *abs_time);
1060-- 
1061-- Waits until this thread is woken up on cond, but not longer than until the time specified by abs_time. The mutex is unlocked before falling asleep and locked again before resuming.
1062-- 
1063-- If abs_time is NULL, g_cond_timed_wait() acts like g_cond_wait().
1064-- 
1065-- This function can be used even if g_thread_init() has not yet been called, and, in that case, will immediately return TRUE.
1066-- 
1067-- To easily calculate abs_time a combination of g_get_current_time() and g_time_val_add() can be used.
1068-- 
1069-- cond :
1070-- 	a GCond.
1071-- 
1072-- mutex :
1073-- 	a GMutex that is currently locked.
1074-- 
1075-- abs_time :
1076-- 	a GTimeVal, determining the final time.
1077-- 
1078-- Returns :
1079-- 	TRUE if cond was signalled, or FALSE on timeout.
1080-- g_cond_free ()
1081-- 
1082-- void                g_cond_free                         (GCond *cond);
1083-- 
1084-- Destroys the GCond.
1085-- 
1086-- cond :
1087-- 	a GCond.
1088-- GPrivate
1089-- 
1090-- typedef struct _GPrivate GPrivate;
1091-- 
1092-- The GPrivate struct is an opaque data structure to represent a thread private data key. Threads can thereby obtain and set a pointer which is private to the current thread. Take our give_me_next_number() example from above. Suppose we don't want current_number to be shared between the threads, but instead to be private to each thread. This can be done as follows:
1093-- 
1094-- Example 9. Using GPrivate for per-thread data
1095-- 
1096-- 1
1097-- 2
1098-- 3
1099-- 4
1100-- 5
1101-- 6
1102-- 7
1103-- 8
1104-- 9
1105-- 10
1106-- 11
1107-- 12
1108-- 13
1109-- 14
1110-- 15
1111-- 16
1112-- 17
1113-- 18
1114-- 19
1115-- 
1116-- 	
1117-- 
1118-- GPrivate* current_number_key = NULL; /* Must be initialized somewhere
1119--                                         with g_private_new (g_free); */
1120-- 
1121-- int
1122-- give_me_next_number (void)
1123-- {
1124--   int *current_number = g_private_get (current_number_key);
1125-- 
1126--   if (!current_number)
1127--     {
1128--       current_number = g_new (int, 1);
1129--       *current_number = 0;
1130--       g_private_set (current_number_key, current_number);
1131--     }
1132-- 
1133--   *current_number = calc_next_number (*current_number);
1134-- 
1135--   return *current_number;
1136-- }
1137-- 
1138-- 
1139-- 
1140-- Here the pointer belonging to the key current_number_key is read. If it is NULL, it has not been set yet. Then get memory for an integer value, assign this memory to the pointer and write the pointer back. Now we have an integer value that is private to the current thread.
1141-- 
1142-- The GPrivate struct should only be accessed via the following functions.
1143-- 
1144-- Note
1145-- 
1146-- All of the g_private_* functions are actually macros. Apart from taking their addresses, you can however use them as if they were functions.
1147-- 
1148-- g_private_new ()
1149-- 
1150-- GPrivate*           g_private_new                       (GDestroyNotify destructor);
1151-- 
1152-- Creates a new GPrivate. If destructor is non-NULL, it is a pointer to a destructor function. Whenever a thread ends and the corresponding pointer keyed to this instance of GPrivate is non-NULL, the destructor is called with this pointer as the argument.
1153-- 
1154-- Note
1155-- 
1156-- destructor is used quite differently from notify in g_static_private_set().
1157-- 
1158-- Note
1159-- 
1160-- A GPrivate can not be freed. Reuse it instead, if you can, to avoid shortage, or use GStaticPrivate.
1161-- 
1162-- Note
1163-- 
1164-- This function will abort if g_thread_init() has not been called yet.
1165-- 
1166-- destructor :
1167-- 	a function to destroy the data keyed to GPrivate when a thread ends.
1168-- 
1169-- Returns :
1170-- 	a new GPrivate.
1171-- g_private_get ()
1172-- 
1173-- gpointer            g_private_get                       (GPrivate *private_key);
1174-- 
1175-- Returns the pointer keyed to private_key for the current thread. If g_private_set() hasn't been called for the current private_key and thread yet, this pointer will be NULL.
1176-- 
1177-- This function can be used even if g_thread_init() has not yet been called, and, in that case, will return the value of private_key casted to gpointer. Note however, that private data set before g_thread_init() will not be retained after the call. Instead, NULL will be returned in all threads directly after g_thread_init(), regardless of any g_private_set() calls issued before threading system intialization.
1178-- 
1179-- private_key :
1180-- 	a GPrivate.
1181-- 
1182-- Returns :
1183-- 	the corresponding pointer.
1184-- g_private_set ()
1185-- 
1186-- void                g_private_set                       (GPrivate *private_key,
1187--                                                          gpointer data);
1188-- 
1189-- Sets the pointer keyed to private_key for the current thread.
1190-- 
1191-- This function can be used even if g_thread_init() has not yet been called, and, in that case, will set private_key to data casted to GPrivate*. See g_private_get() for resulting caveats.
1192-- 
1193-- private_key :
1194-- 	a GPrivate.
1195-- 
1196-- data :
1197-- 	the new pointer.
1198-- struct GStaticPrivate
1199-- 
1200-- struct GStaticPrivate {
1201-- };
1202-- 
1203-- A GStaticPrivate works almost like a GPrivate, but it has one significant advantage. It doesn't need to be created at run-time like a GPrivate, but can be defined at compile-time. This is similar to the difference between GMutex and GStaticMutex. Now look at our give_me_next_number() example with GStaticPrivate:
1204-- 
1205-- Example 10. Using GStaticPrivate for per-thread data
1206-- 
1207-- 1
1208-- 2
1209-- 3
1210-- 4
1211-- 5
1212-- 6
1213-- 7
1214-- 8
1215-- 9
1216-- 10
1217-- 11
1218-- 12
1219-- 13
1220-- 14
1221-- 15
1222-- 16
1223-- 17
1224-- 
1225-- 	
1226-- 
1227-- int
1228-- give_me_next_number ()
1229-- {
1230--   static GStaticPrivate current_number_key = G_STATIC_PRIVATE_INIT;
1231--   int *current_number = g_static_private_get (&current_number_key);
1232-- 
1233--   if (!current_number)
1234--     {
1235--       current_number = g_new (int,1);
1236--       *current_number = 0;
1237--       g_static_private_set (&current_number_key, current_number, g_free);
1238--     }
1239-- 
1240--   *current_number = calc_next_number (*current_number);
1241-- 
1242--   return *current_number;
1243-- }
1244-- 
1245-- 
1246-- 
1247-- G_STATIC_PRIVATE_INIT
1248-- 
1249-- #define G_STATIC_PRIVATE_INIT 
1250-- 
1251-- Every GStaticPrivate must be initialized with this macro, before it can be used.
1252-- 
1253-- 1
1254-- 
1255-- 	
1256-- 
1257-- GStaticPrivate my_private = G_STATIC_PRIVATE_INIT;
1258-- 
1259-- g_static_private_init ()
1260-- 
1261-- void                g_static_private_init               (GStaticPrivate *private_key);
1262-- 
1263-- Initializes private_key. Alternatively you can initialize it with G_STATIC_PRIVATE_INIT.
1264-- 
1265-- private_key :
1266-- 	a GStaticPrivate to be initialized.
1267-- g_static_private_get ()
1268-- 
1269-- gpointer            g_static_private_get                (GStaticPrivate *private_key);
1270-- 
1271-- Works like g_private_get() only for a GStaticPrivate.
1272-- 
1273-- This function works even if g_thread_init() has not yet been called.
1274-- 
1275-- private_key :
1276-- 	a GStaticPrivate.
1277-- 
1278-- Returns :
1279-- 	the corresponding pointer.
1280-- g_static_private_set ()
1281-- 
1282-- void                g_static_private_set                (GStaticPrivate *private_key,
1283--                                                          gpointer data,
1284--                                                          GDestroyNotify notify);
1285-- 
1286-- Sets the pointer keyed to private_key for the current thread and the function notify to be called with that pointer (NULL or non-NULL), whenever the pointer is set again or whenever the current thread ends.
1287-- 
1288-- This function works even if g_thread_init() has not yet been called. If g_thread_init() is called later, the data keyed to private_key will be inherited only by the main thread, i.e. the one that called g_thread_init().
1289-- 
1290-- Note
1291-- 
1292-- notify is used quite differently from destructor in g_private_new().
1293-- 
1294-- private_key :
1295-- 	a GStaticPrivate.
1296-- 
1297-- data :
1298-- 	the new pointer.
1299-- 
1300-- notify :
1301-- 	a function to be called with the pointer whenever the current thread ends or sets this pointer again.
1302-- g_static_private_free ()
1303-- 
1304-- void                g_static_private_free               (GStaticPrivate *private_key);
1305-- 
1306-- Releases all resources allocated to private_key.
1307-- 
1308-- You don't have to call this functions for a GStaticPrivate with an unbounded lifetime, i.e. objects declared 'static', but if you have a GStaticPrivate as a member of a structure and the structure is freed, you should also free the GStaticPrivate.
1309-- 
1310-- private_key :
1311-- 	a GStaticPrivate to be freed.
1312-- struct GOnce
1313-- 
1314-- struct GOnce {
1315--   volatile GOnceStatus status;
1316--   volatile gpointer retval;
1317-- };
1318-- 
1319-- A GOnce struct controls a one-time initialization function. Any one-time initialization function must have its own unique GOnce struct.
1320-- 
1321-- volatile GOnceStatus status;
1322-- 	the status of the GOnce
1323-- 
1324-- volatile gpointer retval;
1325-- 	the value returned by the call to the function, if status is G_ONCE_STATUS_READY
1326-- 
1327-- Since 2.4
1328-- enum GOnceStatus
1329-- 
1330-- typedef enum
1331-- {
1332--   G_ONCE_STATUS_NOTCALLED,
1333--   G_ONCE_STATUS_PROGRESS,
1334--   G_ONCE_STATUS_READY  
1335-- } GOnceStatus;
1336-- 
1337-- The possible statuses of a one-time initialization function controlled by a GOnce struct.
1338-- 
1339-- G_ONCE_STATUS_NOTCALLED
1340-- 	the function has not been called yet.
1341-- 
1342-- G_ONCE_STATUS_PROGRESS
1343-- 	the function call is currently in progress.
1344-- 
1345-- G_ONCE_STATUS_READY
1346-- 	the function has been called.
1347-- 
1348-- Since 2.4
1349-- G_ONCE_INIT
1350-- 
1351-- #define G_ONCE_INIT { G_ONCE_STATUS_NOTCALLED, NULL }
1352-- 
1353-- A GOnce must be initialized with this macro before it can be used.
1354-- 
1355-- 1
1356-- 
1357-- 	
1358-- 
1359-- GOnce my_once = G_ONCE_INIT;
1360-- 
1361-- Since 2.4
1362-- g_once()
1363-- 
1364-- #define             g_once(once, func, arg)
1365-- 
1366-- The first call to this routine by a process with a given GOnce struct calls func with the given argument. Thereafter, subsequent calls to g_once() with the same GOnce struct do not call func again, but return the stored result of the first call. On return from g_once(), the status of once will be G_ONCE_STATUS_READY.
1367-- 
1368-- For example, a mutex or a thread-specific data key must be created exactly once. In a threaded environment, calling g_once() ensures that the initialization is serialized across multiple threads.
1369-- 
1370-- Note
1371-- 
1372-- Calling g_once() recursively on the same GOnce struct in func will lead to a deadlock.
1373-- 
1374-- 1
1375-- 2
1376-- 3
1377-- 4
1378-- 5
1379-- 6
1380-- 7
1381-- 8
1382-- 9
1383-- 
1384-- 	
1385-- 
1386-- gpointer
1387-- get_debug_flags (void)
1388-- {
1389--   static GOnce my_once = G_ONCE_INIT;
1390-- 
1391--   g_once (&my_once, parse_debug_flags, NULL);
1392-- 
1393--   return my_once.retval;
1394-- }
1395-- 
1396-- once :
1397-- 	a GOnce structure
1398-- 
1399-- func :
1400-- 	the GThreadFunc function associated to once. This function is called only once, regardless of the number of times it and its associated GOnce struct are passed to g_once().
1401-- 
1402-- arg :
1403-- 	data to be passed to func
1404-- 
1405-- Since 2.4
1406-- g_once_init_enter ()
1407-- 
1408-- gboolean            g_once_init_enter                   (volatile gsize *value_location);
1409-- 
1410-- Function to be called when starting a critical initialization section. The argument value_location must point to a static 0-initialized variable that will be set to a value other than 0 at the end of the initialization section. In combination with g_once_init_leave() and the unique address value_location, it can be ensured that an initialization section will be executed only once during a program's life time, and that concurrent threads are blocked until initialization completed. To be used in constructs like this:
1411-- 
1412-- 1
1413-- 2
1414-- 3
1415-- 4
1416-- 5
1417-- 6
1418-- 7
1419-- 8
1420-- 9
1421-- 10
1422-- 
1423-- 	
1424-- 
1425-- static gsize initialization_value = 0;
1426-- 
1427-- if (g_once_init_enter (&initialization_value))
1428--   {
1429--     gsize setup_value = 42; /* initialization code here */
1430-- 
1431--     g_once_init_leave (&initialization_value, setup_value);
1432--   }
1433-- 
1434-- /* use initialization_value here */
1435-- 
1436-- value_location :
1437-- 	location of a static initializable variable containing 0.
1438-- 
1439-- Returns :
1440-- 	TRUE if the initialization section should be entered, FALSE and blocks otherwise
1441-- 
1442-- Since 2.14
1443-- g_once_init_leave ()
1444-- 
1445-- void                g_once_init_leave                   (volatile gsize *value_location,
1446--                                                          gsize initialization_value);
1447-- 
1448-- Counterpart to g_once_init_enter()…

Large files files are truncated, but you can click here to view the full file