Class Mutex

java.lang.Object
org.javagi.base.ProxyInstance
org.gnome.glib.Mutex
All Implemented Interfaces:
Proxy
@Generated("org.javagi.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()
    Allocate a new Mutex.
    Mutex(Arena arena)
    Allocate a new Mutex.
    Mutex(MemorySegment address)
    Create a Mutex proxy instance for the provided memory address.
    Mutex(MemorySegment p, int[] i)
    Allocate a new Mutex with the fields set to the provided values.
    Mutex(MemorySegment p, int[] i, Arena arena)
    Allocate a new Mutex with the fields set to the provided values.

  • 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 mutex. If this Mutex is already locked by another thread, the current thread will block until this Mutex is unlocked by the other thread.
    static Mutex
    new_()
    Deprecated.
    GMutex can now be statically allocated, or embedded in structures and initialised with g_mutex_init().
    @Nullable int @Nullable []
    readI()
    Read the value of the field i.
    MemorySegment
    readP()
    Read the value of the field p.
    boolean
    trylock()
    Tries to lock mutex. If this Mutex is already locked by another thread, it immediately returns false.
    void
    unlock()
    Unlocks mutex. If another thread is blocked in a g_mutex_lock() call for mutex, it will become unblocked and can lock this Mutex itself.
    void
    writeI(@Nullable int @Nullable [] i, Arena _arena)
    Write a value in the field i.
    void
    writeP(MemorySegment p)
    Write a value in the field p.

    Methods inherited from class ProxyInstance

    equals, handle, hashCode

    Methods inherited from class 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

    • Mutex

      public Mutex()
      Allocate a new Mutex. The memory is allocated with Arena.ofAuto().

    • Mutex

      public Mutex(MemorySegment p, int[] i, Arena arena)
      Allocate a new Mutex with the fields set to the provided values.
      Parameters:
      p - value for the field p
      i - value for the field i
      arena - to control the memory allocation scope

    • Mutex

      public Mutex(MemorySegment p, int[] i)
      Allocate a new Mutex with the fields set to the provided values. The memory is allocated with Arena.ofAuto().
      Parameters:
      p - value for the field p
      i - value for the field i

  • Method Details

    • getMemoryLayout

      public static MemoryLayout getMemoryLayout()
      The memory layout of the native struct.
      Returns:
      the memory layout

    • readP

      public MemorySegment readP()
      Read the value of the field p.
      Returns:
      The value of the field p

    • writeP

      public void writeP(MemorySegment p)
      Write a value in the field p.
      Parameters:
      p - The new value for the field p

    • readI

      public @Nullable int @Nullable [] readI()
      Read the value of the field i.
      Returns:
      The value of the field i

    • writeI

      public void writeI(@Nullable int @Nullable [] i, Arena _arena)
      Write a value in the field i.
      Parameters:
      i - The new value for the field i

    • 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

    • 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.

      Since:
      2.32

    • 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.

      Since:
      2.32

    • lock

      public void lock()

      Locks 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 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 mutex. If another thread is blocked in a g_mutex_lock() call for 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.