Functions
g_thread_new ()
GThread *
g_thread_new (const gchar *name,
GThreadFunc func,
gpointer data);
This function creates a new thread. The new thread starts by invoking
func
with the argument data. The thread will run until func
returns
or until g_thread_exit() is called from the new thread. The return value
of func
becomes the return value of the thread, which can be obtained
with g_thread_join().
The name
can be useful for discriminating threads in a debugger.
It is not used for other purposes and does not have to be unique.
Some systems restrict the length of name
to 16 bytes.
If the thread can not be created the program aborts. See
g_thread_try_new() if you want to attempt to deal with failures.
If you are using threads to offload (potentially many) short-lived tasks,
GThreadPool may be more appropriate than manually spawning and tracking
multiple GThreads.
To free the struct returned by this function, use g_thread_unref().
Note that g_thread_join() implicitly unrefs the GThread as well.
New threads by default inherit their scheduler policy (POSIX) or thread
priority (Windows) of the thread creating the new thread.
This behaviour changed in GLib 2.64: before threads on Windows were not
inheriting the thread priority but were spawned with the default priority.
Starting with GLib 2.64 the behaviour is now consistent between Windows and
POSIX and all threads inherit their parent thread's priority.
Since: 2.32
g_thread_try_new ()
GThread *
g_thread_try_new (const gchar *name,
GThreadFunc func,
gpointer data,
GError **error);
This function is the same as g_thread_new() except that
it allows for the possibility of failure.
If a thread can not be created (due to resource limits),
error
is set and NULL is returned.
Since: 2.32
g_thread_ref ()
GThread *
g_thread_ref (GThread *thread);
Increase the reference count on thread
.
Returns
a new reference to thread
Since: 2.32
g_thread_unref ()
void
g_thread_unref (GThread *thread);
Decrease the reference count on thread
, possibly freeing all
resources associated with it.
Note that each thread holds a reference to its GThread while
it is running, so it is safe to drop your own reference to it
if you don't need it anymore.
Since: 2.32
g_thread_join ()
gpointer
g_thread_join (GThread *thread);
Waits until thread
finishes, i.e. the function func
, as
given to g_thread_new(), returns or g_thread_exit() is called.
If thread
has already terminated, then g_thread_join()
returns immediately.
Any thread can wait for any other thread by calling g_thread_join(),
not just its 'creator'. Calling g_thread_join() from multiple threads
for the same thread
leads to undefined behaviour.
The value returned by func
or given to g_thread_exit() is
returned by this function.
g_thread_join() consumes the reference to the passed-in thread
.
This will usually cause the GThread struct and associated resources
to be freed. Use g_thread_ref() to obtain an extra reference if you
want to keep the GThread alive beyond the g_thread_join() call.
Returns
the return value of the thread
g_thread_yield ()
void
g_thread_yield ();
Causes the calling thread to voluntarily relinquish the CPU, so
that other threads can run.
This function is often used as a method to make busy wait less evil.
g_thread_exit ()
void
g_thread_exit (gpointer retval);
Terminates the current thread.
If another thread is waiting for us using g_thread_join() then the
waiting thread will be woken up and get retval
as the return value
of g_thread_join().
Calling g_thread_exit() with a parameter retval
is equivalent to
returning retval
from the function func
, as given to g_thread_new().
You must only call g_thread_exit() from a thread that you created
yourself with g_thread_new() or related APIs. You must not call
this function from a thread created with another threading library
or or from within a GThreadPool.
g_thread_self ()
GThread *
g_thread_self (void);
This function returns the GThread corresponding to the
current thread. Note that this function does not increase
the reference count of the returned struct.
This function will return a GThread even for threads that
were not created by GLib (i.e. those created by other threading
APIs). This may be useful for thread identification purposes
(i.e. comparisons) but you must not use GLib functions (such
as g_thread_join()) on these threads.
Returns
the GThread representing the current thread
g_mutex_init ()
void
g_mutex_init (GMutex *mutex);
Initializes a GMutex so that it can be used.
This function is useful to initialize a mutex that has been
allocated on the stack, or as part of a larger structure.
It is not necessary to initialize a mutex that has been
statically allocated.
To undo the effect of g_mutex_init() when a mutex is no longer
needed, use g_mutex_clear().
Calling g_mutex_init() on an already initialized GMutex leads
to undefined behaviour.
Since: 2.32
g_mutex_clear ()
void
g_mutex_clear (GMutex *mutex);
Frees the resources allocated to a mutex with g_mutex_init().
This function should not be used with a GMutex that has been
statically allocated.
Calling g_mutex_clear() on a locked mutex leads to undefined
behaviour.
Sine: 2.32
g_mutex_lock ()
void
g_mutex_lock (GMutex *mutex);
Locks mutex
. If mutex
is already locked by another thread, the
current thread will block until mutex
is unlocked by the other
thread.
GMutex is neither guaranteed to be recursive nor to be
non-recursive. As such, calling g_mutex_lock() on a GMutex that has
already been locked by the same thread results in undefined behaviour
(including but not limited to deadlocks).
g_mutex_trylock ()
gboolean
g_mutex_trylock (GMutex *mutex);
Tries to lock mutex
. If mutex
is already locked by another thread,
it immediately returns FALSE. Otherwise it locks mutex
and returns
TRUE.
GMutex is neither guaranteed to be recursive nor to be
non-recursive. As such, calling g_mutex_lock() on a GMutex that has
already been locked by the same thread results in undefined behaviour
(including but not limited to deadlocks or arbitrary return values).
Returns
TRUE if mutex
could be locked
g_mutex_unlock ()
void
g_mutex_unlock (GMutex *mutex);
Unlocks mutex
. If another thread is blocked in a g_mutex_lock()
call for mutex
, it will become unblocked and can lock mutex
itself.
Calling g_mutex_unlock() on a mutex that is not locked by the
current thread leads to undefined behaviour.
G_LOCK_DEFINE()
#define G_LOCK_DEFINE(name)
The G_LOCK_ macros provide a convenient interface to GMutex.
G_LOCK_DEFINE defines a lock. It can appear in any place where
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 GMutex. This means that you
can use names of existing variables as the parameter - e.g. the name
of the variable you intend to protect with the lock. Look at our
give_me_next_number() example using the G_LOCK macros:
Here is an example for using the G_LOCK convenience macros:
G_LOCK_DEFINE_STATIC()
#define G_LOCK_DEFINE_STATIC(name)
This works like G_LOCK_DEFINE, but it creates a static object.
G_LOCK_EXTERN()
#define G_LOCK_EXTERN(name)
This declares a lock, that is defined with G_LOCK_DEFINE in another
module.
g_rec_mutex_init ()
void
g_rec_mutex_init (GRecMutex *rec_mutex);
Initializes a GRecMutex so that it can be used.
This function is useful to initialize a recursive mutex
that has been allocated on the stack, or as part of a larger
structure.
It is not necessary to initialise a recursive mutex that has been
statically allocated.
Calling g_rec_mutex_init() on an already initialized GRecMutex
leads to undefined behaviour.
To undo the effect of g_rec_mutex_init() when a recursive mutex
is no longer needed, use g_rec_mutex_clear().
Since: 2.32
g_rec_mutex_clear ()
void
g_rec_mutex_clear (GRecMutex *rec_mutex);
Frees the resources allocated to a recursive mutex with
g_rec_mutex_init().
This function should not be used with a GRecMutex that has been
statically allocated.
Calling g_rec_mutex_clear() on a locked recursive mutex leads
to undefined behaviour.
Sine: 2.32
g_rec_mutex_lock ()
void
g_rec_mutex_lock (GRecMutex *rec_mutex);
Locks rec_mutex
. If rec_mutex
is already locked by another
thread, the current thread will block until rec_mutex
is
unlocked by the other thread. If rec_mutex
is already locked
by the current thread, the 'lock count' of rec_mutex
is increased.
The mutex will only become available again when it is unlocked
as many times as it has been locked.
Since: 2.32
g_rec_mutex_trylock ()
gboolean
g_rec_mutex_trylock (GRecMutex *rec_mutex);
Tries to lock rec_mutex
. If rec_mutex
is already locked
by another thread, it immediately returns FALSE. Otherwise
it locks rec_mutex
and returns TRUE.
Returns
TRUE if rec_mutex
could be locked
Since: 2.32
g_rec_mutex_unlock ()
void
g_rec_mutex_unlock (GRecMutex *rec_mutex);
Unlocks rec_mutex
. If another thread is blocked in a
g_rec_mutex_lock() call for rec_mutex
, it will become unblocked
and can lock rec_mutex
itself.
Calling g_rec_mutex_unlock() on a recursive mutex that is not
locked by the current thread leads to undefined behaviour.
Since: 2.32
g_rw_lock_init ()
void
g_rw_lock_init (GRWLock *rw_lock);
Initializes a GRWLock so that it can be used.
This function is useful to initialize a lock that has been
allocated on the stack, or as part of a larger structure. It is not
necessary to initialise a reader-writer lock that has been statically
allocated.
To undo the effect of g_rw_lock_init() when a lock is no longer
needed, use g_rw_lock_clear().
Calling g_rw_lock_init() on an already initialized GRWLock leads
to undefined behaviour.
Since: 2.32
g_rw_lock_clear ()
void
g_rw_lock_clear (GRWLock *rw_lock);
Frees the resources allocated to a lock with g_rw_lock_init().
This function should not be used with a GRWLock that has been
statically allocated.
Calling g_rw_lock_clear() when any thread holds the lock
leads to undefined behaviour.
Sine: 2.32
g_rw_lock_writer_lock ()
void
g_rw_lock_writer_lock (GRWLock *rw_lock);
Obtain a write lock on rw_lock
. If any thread already holds
a read or write lock on rw_lock
, the current thread will block
until all other threads have dropped their locks on rw_lock
.
Since: 2.32
g_rw_lock_writer_trylock ()
gboolean
g_rw_lock_writer_trylock (GRWLock *rw_lock);
Tries to obtain a write lock on rw_lock
. If any other thread holds
a read or write lock on rw_lock
, it immediately returns FALSE.
Otherwise it locks rw_lock
and returns TRUE.
Returns
TRUE if rw_lock
could be locked
Since: 2.32
g_rw_lock_writer_unlock ()
void
g_rw_lock_writer_unlock (GRWLock *rw_lock);
Release a write lock on rw_lock
.
Calling g_rw_lock_writer_unlock() on a lock that is not held
by the current thread leads to undefined behaviour.
Since: 2.32
g_rw_lock_reader_lock ()
void
g_rw_lock_reader_lock (GRWLock *rw_lock);
Obtain a read lock on rw_lock
. If another thread currently holds
the write lock on rw_lock
, the current thread will block. If another thread
does not hold the write lock, but is waiting for it, it is implementation
defined whether the reader or writer will block. Read locks can be taken
recursively.
It is implementation-defined how many threads are allowed to
hold read locks on the same lock simultaneously. If the limit is hit,
or if a deadlock is detected, a critical warning will be emitted.
Since: 2.32
g_rw_lock_reader_trylock ()
gboolean
g_rw_lock_reader_trylock (GRWLock *rw_lock);
Tries to obtain a read lock on rw_lock
and returns TRUE if
the read lock was successfully obtained. Otherwise it
returns FALSE.
Returns
TRUE if rw_lock
could be locked
Since: 2.32
g_rw_lock_reader_unlock ()
void
g_rw_lock_reader_unlock (GRWLock *rw_lock);
Release a read lock on rw_lock
.
Calling g_rw_lock_reader_unlock() on a lock that is not held
by the current thread leads to undefined behaviour.
Since: 2.32
g_cond_init ()
void
g_cond_init (GCond *cond);
Initialises a GCond so that it can be used.
This function is useful to initialise a GCond that has been
allocated as part of a larger structure. It is not necessary to
initialise a GCond that has been statically allocated.
To undo the effect of g_cond_init() when a GCond is no longer
needed, use g_cond_clear().
Calling g_cond_init() on an already-initialised GCond leads
to undefined behaviour.
Since: 2.32
g_cond_clear ()
void
g_cond_clear (GCond *cond);
Frees the resources allocated to a GCond with g_cond_init().
This function should not be used with a GCond that has been
statically allocated.
Calling g_cond_clear() for a GCond on which threads are
blocking leads to undefined behaviour.
Since: 2.32
g_cond_wait ()
void
g_cond_wait (GCond *cond,
GMutex *mutex);
Atomically releases mutex
and waits until cond
is signalled.
When this function returns, mutex
is locked again and owned by the
calling thread.
When using condition variables, it is possible that a spurious wakeup
may occur (ie: g_cond_wait() returns even though g_cond_signal() was
not called). It's also possible that a stolen wakeup may occur.
This is when g_cond_signal() is called, but another thread acquires
mutex
before this thread and modifies the state of the program in
such a way that when g_cond_wait() is able to return, the expected
condition is no longer met.
For this reason, g_cond_wait() must always be used in a loop. See
the documentation for GCond for a complete example.
g_cond_timed_wait ()
gboolean
g_cond_timed_wait (GCond *cond,
GMutex *mutex,
GTimeVal *abs_time);
g_cond_timed_wait has been deprecated since version 2.32 and should not be used in newly-written code.
Use g_cond_wait_until() instead.
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.
If abs_time
is NULL, g_cond_timed_wait() acts like g_cond_wait().
This function can be used even if g_thread_init() has not yet been
called, and, in that case, will immediately return TRUE.
To easily calculate abs_time
a combination of g_get_real_time()
and g_time_val_add() can be used.
Returns
TRUE if cond
was signalled, or FALSE on timeout
g_cond_wait_until ()
gboolean
g_cond_wait_until (GCond *cond,
GMutex *mutex,
gint64 end_time);
Waits until either cond
is signalled or end_time
has passed.
As with g_cond_wait() it is possible that a spurious or stolen wakeup
could occur. For that reason, waiting on a condition variable should
always be in a loop, based on an explicitly-checked predicate.
TRUE is returned if the condition variable was signalled (or in the
case of a spurious wakeup). FALSE is returned if end_time
has
passed.
The following code shows how to correctly perform a timed wait on a
condition variable (extending the example presented in the
documentation for GCond):
Notice that the end time is calculated once, before entering the
loop and reused. This is the motivation behind the use of absolute
time on this API -- if a relative time of 5 seconds were passed
directly to the call and a spurious wakeup occurred, the program would
have to start over waiting again (which would lead to a total wait
time of more than 5 seconds).
Since: 2.32
g_cond_signal ()
void
g_cond_signal (GCond *cond);
If threads are waiting for cond
, at least one of them is unblocked.
If no threads are waiting for cond
, this function has no effect.
It is good practice to hold the same lock as the waiting thread
while calling this function, though not required.
g_cond_broadcast ()
void
g_cond_broadcast (GCond *cond);
If threads are waiting for cond
, all of them are unblocked.
If no threads are waiting for cond
, this function has no effect.
It is good practice to lock the same mutex as the waiting threads
while calling this function, though not required.
G_PRIVATE_INIT()
#define G_PRIVATE_INIT(notify)
A macro to assist with the static initialisation of a GPrivate.
This macro is useful for the case that a GDestroyNotify function
should be associated with the key. This is needed when the key will be
used to point at memory that should be deallocated when the thread
exits.
Additionally, the GDestroyNotify will also be called on the previous
value stored in the key when g_private_replace() is used.
If no GDestroyNotify is needed, then use of this macro is not
required -- if the GPrivate is declared in static scope then it will
be properly initialised by default (ie: to all zeros). See the
examples below.
Since: 2.32
g_private_get ()
gpointer
g_private_get (GPrivate *key);
Returns the current value of the thread local variable key
.
If the value has not yet been set in this thread, NULL is returned.
Values are never copied between threads (when a new thread is
created, for example).
Returns
the thread-local value
g_private_set ()
void
g_private_set (GPrivate *key,
gpointer value);
Sets the thread local variable key
to have the value value
in the
current thread.
This function differs from g_private_replace() in the following way:
the GDestroyNotify for key
is not called on the old value.
g_private_replace ()
void
g_private_replace (GPrivate *key,
gpointer value);
Sets the thread local variable key
to have the value value
in the
current thread.
This function differs from g_private_set() in the following way: if
the previous value was non-NULL then the GDestroyNotify handler for
key
is run on it.
Since: 2.32
g_once()
#define g_once(once, func, arg)
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.
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.
Calling g_once() recursively on the same GOnce struct in
func
will lead to a deadlock.
Since: 2.4
g_once_init_enter ()
gboolean
g_once_init_enter (volatile void *location);
Function to be called when starting a critical initialization
section. The argument 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:
Returns
TRUE if the initialization section should be entered,
FALSE and blocks otherwise
Since: 2.14
g_once_init_leave ()
void
g_once_init_leave (volatile void *location,
gsize result);
Counterpart to g_once_init_enter(). Expects a location of a static
0-initialized initialization variable, and an initialization value
other than 0. Sets the variable to the initialization value, and
releases concurrent threads blocking in g_once_init_enter() on this
initialization variable.
Since: 2.14
g_bit_lock ()
void
g_bit_lock (volatile gint *address,
gint lock_bit);
Sets the indicated lock_bit
in address
. If the bit is already
set, this call will block until g_bit_unlock() unsets the
corresponding bit.
Attempting to lock on two different bits within the same integer is
not supported and will very probably cause deadlocks.
The value of the bit that is set is (1u << bit
). If bit
is not
between 0 and 31 then the result is undefined.
This function accesses address
atomically. All other accesses to
address
must be atomic in order for this function to work
reliably.
Since: 2.24
g_bit_trylock ()
gboolean
g_bit_trylock (volatile gint *address,
gint lock_bit);
Sets the indicated lock_bit
in address
, returning TRUE if
successful. If the bit is already set, returns FALSE immediately.
Attempting to lock on two different bits within the same integer is
not supported.
The value of the bit that is set is (1u << bit
). If bit
is not
between 0 and 31 then the result is undefined.
This function accesses address
atomically. All other accesses to
address
must be atomic in order for this function to work
reliably.
Returns
TRUE if the lock was acquired
Since: 2.24
g_bit_unlock ()
void
g_bit_unlock (volatile gint *address,
gint lock_bit);
Clears the indicated lock_bit
in address
. If another thread is
currently blocked in g_bit_lock() on this same bit then it will be
woken up.
This function accesses address
atomically. All other accesses to
address
must be atomic in order for this function to work
reliably.
Since: 2.24
g_pointer_bit_lock ()
void
g_pointer_bit_lock (volatile void *address,
gint lock_bit);
This is equivalent to g_bit_lock, but working on pointers (or other
pointer-sized values).
For portability reasons, you may only lock on the bottom 32 bits of
the pointer.
Since: 2.30
g_pointer_bit_trylock ()
gboolean
g_pointer_bit_trylock (volatile void *address,
gint lock_bit);
This is equivalent to g_bit_trylock, but working on pointers (or
other pointer-sized values).
For portability reasons, you may only lock on the bottom 32 bits of
the pointer.
Returns
TRUE if the lock was acquired
Since: 2.30
g_pointer_bit_unlock ()
void
g_pointer_bit_unlock (volatile void *address,
gint lock_bit);
This is equivalent to g_bit_unlock, but working on pointers (or other
pointer-sized values).
For portability reasons, you may only lock on the bottom 32 bits of
the pointer.
Since: 2.30
g_get_num_processors ()
guint
g_get_num_processors (void);
Determine the approximate number of threads that the system will
schedule simultaneously for this process. This is intended to be
used as a parameter to g_thread_pool_new() for CPU bound tasks and
similar cases.
Returns
Number of schedulable threads, always greater than 0
Since: 2.36
Types and Values
G_THREAD_ERROR
#define G_THREAD_ERROR g_thread_error_quark ()
The error domain of the GLib thread subsystem.
enum GThreadError
Possible errors of thread related functions.
GThread
typedef struct {
} GThread;
The GThread struct represents a running thread. This struct
is returned by g_thread_new() or g_thread_try_new(). You can
obtain the GThread struct representing the current thread by
calling g_thread_self().
GThread is refcounted, see g_thread_ref() and g_thread_unref().
The thread represented by it holds a reference while it is running,
and g_thread_join() consumes the reference that it is given, so
it is normally not necessary to manage GThread references
explicitly.
The structure is opaque -- none of its fields may be directly
accessed.
union GMutex
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:
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 GMutex can be used as a solution to this problem:
Notice that the GMutex is not initialised to any particular value.
Its placement in static storage ensures that it will be initialised
to all-zeros, which is appropriate.
If a GMutex is placed in other contexts (eg: embedded in a struct)
then it must be explicitly initialised using g_mutex_init().
A GMutex should only be accessed via g_mutex_ functions.
struct GRecMutex
struct GRecMutex {
};
The GRecMutex struct is an opaque data structure to represent a
recursive mutex. It is similar to a GMutex with the difference
that it is possible to lock a GRecMutex multiple times in the same
thread without deadlock. When doing so, care has to be taken to
unlock the recursive mutex as often as it has been locked.
If a GRecMutex is allocated in static storage then it can be used
without initialisation. Otherwise, you should call
g_rec_mutex_init() on it and g_rec_mutex_clear() when done.
A GRecMutex should only be accessed with the
g_rec_mutex_ functions.
Since: 2.32
struct GRWLock
struct GRWLock {
};
The GRWLock struct is an opaque data structure to represent a
reader-writer lock. It is similar to a GMutex in that it allows
multiple threads to coordinate access to a shared resource.
The difference to a mutex is that a reader-writer lock discriminates
between read-only ('reader') and full ('writer') access. While only
one thread at a time is allowed write access (by holding the 'writer'
lock via g_rw_lock_writer_lock()), multiple threads can gain
simultaneous read-only access (by holding the 'reader' lock via
g_rw_lock_reader_lock()).
It is unspecified whether readers or writers have priority in acquiring the
lock when a reader already holds the lock and a writer is queued to acquire
it.
Here is an example for an array with access functions:
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 one 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.
If a GRWLock is allocated in static storage then it can be used
without initialisation. Otherwise, you should call
g_rw_lock_init() on it and g_rw_lock_clear() when done.
A GRWLock should only be accessed with the g_rw_lock_ functions.
Since: 2.32
struct GCond
struct GCond {
};
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.
Consider the following example of a shared variable. One or more
threads can wait for data to be published to the variable and when
another thread publishes the data, it can signal one of the waiting
threads to wake up to collect the data.
Here is an example for using GCond to block a thread until a condition
is satisfied:
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().
The example shows that use of a condition variable must always be
paired with a mutex. Without the use of a mutex, there would be a
race between the check of current_data
by the while loop in
pop_data() and waiting. Specifically, another thread could set
current_data
after the check, and signal the cond (with nobody
waiting on it) before the first thread goes to sleep. GCond is
specifically useful for its ability to release the mutex and go
to sleep atomically.
It is also important to use the g_cond_wait() and g_cond_wait_until()
functions only inside a loop which checks for the condition to be
true. See g_cond_wait() for an explanation of why the condition may
not be true even after it returns.
If a GCond is allocated in static storage then it can be used
without initialisation. Otherwise, you should call g_cond_init()
on it and g_cond_clear() when done.
A GCond should only be accessed via the g_cond_ functions.
struct GPrivate
struct GPrivate {
};
The GPrivate struct is an opaque data structure to represent a
thread-local data key. It is approximately equivalent to the
pthread_setspecific()/pthread_getspecific() APIs on POSIX and to
TlsSetValue()/TlsGetValue() on Windows.
If you don't already know why you might want this functionality,
then you probably don't need it.
GPrivate is a very limited resource (as far as 128 per program,
shared between all libraries). It is also not possible to destroy a
GPrivate after it has been used. As such, it is only ever acceptable
to use GPrivate in static scope, and even then sparingly so.
See G_PRIVATE_INIT() for a couple of examples.
The GPrivate structure should be considered opaque. It should only
be accessed via the g_private_ functions.
struct GOnce
struct GOnce {
volatile GOnceStatus status;
volatile gpointer retval;
};
A GOnce struct controls a one-time initialization function. Any
one-time initialization function must have its own unique GOnce
struct.
Since: 2.4
enum GOnceStatus
The possible statuses of a one-time initialization function
controlled by a GOnce struct.
Since: 2.4
G_ONCE_INIT
#define G_ONCE_INIT { G_ONCE_STATUS_NOTCALLED, NULL }
A GOnce must be initialized with this macro before it can be used.
Since: 2.4