class: GMutex

[29:7] extends: object

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: |[ int give_me_next_number (void) { static int current_number = 0; // now do a very complicated calculation to calculate the new // number, this might for example be a random number generator current_number = calc_next_number (current_number); return current_number; } ]| 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: |[ int give_me_next_number (void) { static GMutex mutex; static int current_number = 0; int ret_val; g_mutex_lock (&mutex); ret_val = current_number = calc_next_number (current_number); g_mutex_unlock (&mutex); return ret_val; } ]| 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.

Members

handleObj
lib
retainedCallbacks
signalHandlerNames
signalSetterHandlers

Methods

GMutex (Handle = null)

Creates a new Mutex by wrapping a native handle or another wrapper.
- @p Handle is the native handle or another wrapper whose handle to adopt.
toNativeHandle (Source)

Normalizes a constructor argument into a raw pointer carrier. Accepts a raw NativeHandle, a raw NativeBuffer returned from fn.call(...), another generated wrapper exposing handle(), or null. Returns null when the argument carries no pointer.
- @p Source is the raw handle, raw buffer, wrapper, or null.
- @r A raw pointer carrier or null when no pointer is present.
getLib ()

Returns the opened native library for this generated wrapper.
- @r The opened native library.
handle ()

Returns the wrapped NativeHandle.
- @r The wrapped NativeHandle.
isNull ()

Returns true when the wrapped handle is null.
- @r A bool.
describe ()

Returns a small string for debugging generated wrappers.
- @r A string.
clear ()

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.
- @r None.
free ()

Destroys a @mutex that has been created with g_mutex_new(). Calling g_mutex_free() on a locked mutex may result in undefined behaviour.
- @r None.
init ()

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. |[ typedef struct { GMutex m; ... } Blob; Blob *b; b = g_new (Blob, 1); g_mutex_init (&b->m); ]| 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.
- @r None.
lock ()

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).
- @r None.
trylock ()

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).
- @r %TRUE if @mutex could be locked.
unlock ()

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.
- @r None.