Package org.gnome.glib

Class Mutex

java.lang.Object

io.github.jwharm.javagi.base.ProxyInstance

org.gnome.glib.Mutex

All Implemented Interfaces:

Proxy

@Generated("io.github.jwharm.JavaGI")
public class Mutex
extends ProxyInstance

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.

Constructor Summary

Constructors

Constructor	Description
Mutex(Arena arena)	Allocate a new Mutex.
Mutex(MemorySegment address)	Create a Mutex proxy instance for the provided memory address.

Method Summary

Modifier and Type	Method	Description
void	clear()	Frees the resources allocated to a mutex with g_mutex_init().
void	free()	Deprecated. GMutex can now be statically allocated, or embedded in structures and initialised with g_mutex_init().
static MemoryLayout	getMemoryLayout()	The memory layout of the native struct.
void	init()	Initializes a GMutex so that it can be used.
void	lock()	Locks this Mutex.
static Mutex	new_()	Deprecated. GMutex can now be statically allocated, or embedded in structures and initialised with g_mutex_init().
boolean	trylock()	Tries to lock this Mutex.
void	unlock()	Unlocks this Mutex.

Methods inherited from class io.github.jwharm.javagi.base.ProxyInstance

equals, handle, hashCode

Methods inherited from class java.lang.Object

clone, finalize, getClass, notify, notifyAll, toString, wait, wait, wait

Constructor Details

Mutex

public Mutex(MemorySegment address)

Create a Mutex proxy instance for the provided memory address.

Parameters:

address - the memory address of the native object

Mutex

public Mutex(Arena arena)

Allocate a new Mutex.

Parameters:

arena - to control the memory allocation scope

Method Details

getMemoryLayout

public static MemoryLayout getMemoryLayout()

The memory layout of the native struct.

Returns:

the memory layout

clear

public void 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.

free

@Deprecated
public void free()

Deprecated.

GMutex can now be statically allocated, or embedded in structures and initialised with g_mutex_init().

Destroys a this Mutex that has been created with g_mutex_new().

Calling g_mutex_free() on a locked mutex may result in undefined behaviour.

init

public void 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.

lock

public void lock()

Locks this Mutex. If this Mutex is already locked by another thread, the current thread will block until this 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).

trylock

public boolean trylock()

Tries to lock this Mutex. If this Mutex is already locked by another thread, it immediately returns false. Otherwise it locks this 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 this Mutex could be locked

unlock

public void unlock()

Unlocks this Mutex. If another thread is blocked in a g_mutex_lock() call for this Mutex, it will become unblocked and can lock this Mutex itself.

Calling g_mutex_unlock() on a mutex that is not locked by the current thread leads to undefined behaviour.

new_

@Deprecated
public static Mutex new_()

Deprecated.

GMutex can now be statically allocated, or embedded in structures and initialised with g_mutex_init().

Allocates and initializes a new GMutex.

Returns:

a newly allocated GMutex. Use g_mutex_free() to free