Mutex

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 glib.mutex.Mutex.init_.

A #GMutex should only be accessed via g_mutex_ functions.

Members

Functions

clear
void clear()

Frees the resources allocated to a mutex with glib.mutex.Mutex.init_.

init_
void init_()

Initializes a #GMutex so that it can be used.

lock
void lock()

Locks mutex. If mutex is already locked by another thread, the current thread will block until mutex is unlocked by the other thread.

trylock
bool trylock()

Tries to lock mutex. If mutex is already locked by another thread, it immediately returns false. Otherwise it locks mutex and returns true.

unlock
void unlock()

Unlocks mutex. If another thread is blocked in a glib.mutex.Mutex.lock call for mutex, it will become unblocked and can lock mutex itself.