:right-sidebar: True

Mutex
===================================================================

.. currentmodule:: gi.repository.GLib





.. class:: Mutex(*args, **kwargs)
   :no-contents-entry:






The :obj:`~gi.repository.GLib.Mutex` 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:


.. code-block:: C
    :dedent:

      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 :obj:`~gi.repository.GLib.Mutex` can be used as a solution to this problem:


.. code-block:: C
    :dedent:

      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 :obj:`~gi.repository.GLib.Mutex` 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 :obj:`~gi.repository.GLib.Mutex` is placed in other contexts (eg: embedded in a struct)
then it must be explicitly initialised using :func:`~gi.repository.GLib.Mutex.init`.

A :obj:`~gi.repository.GLib.Mutex` should only be accessed via ``g_mutex_`` functions.




Methods
-------

.. rst-class:: interim-class

.. class:: Mutex
   :no-index:


   .. method:: clear() -> None

      Frees the resources allocated to a mutex with :func:`~gi.repository.GLib.Mutex.init`.

      This function should not be used with a :obj:`~gi.repository.GLib.Mutex` that has been
      statically allocated.

      Calling :func:`~gi.repository.GLib.Mutex.clear` on a locked mutex leads to undefined
      behaviour.


      .. versionadded:: 2.32








   .. method:: init() -> None

      Initializes a :obj:`~gi.repository.GLib.Mutex` 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.


      .. code-block:: C
          :dedent:

            typedef struct {
              GMutex m;
              ...
            } Blob;

          Blob *b;

          b = g_new (Blob, 1);
          g_mutex_init (&b->m);

      To undo the effect of :func:`~gi.repository.GLib.Mutex.init` when a mutex is no longer
      needed, use :func:`~gi.repository.GLib.Mutex.clear`.

      Calling :func:`~gi.repository.GLib.Mutex.init` on an already initialized :obj:`~gi.repository.GLib.Mutex` leads
      to undefined behaviour.


      .. versionadded:: 2.32








   .. method:: lock() -> None

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

      :obj:`~gi.repository.GLib.Mutex` is neither guaranteed to be recursive nor to be
      non-recursive.  As such, calling :func:`~gi.repository.GLib.Mutex.lock` on a :obj:`~gi.repository.GLib.Mutex` that has
      already been locked by the same thread results in undefined behaviour
      (including but not limited to deadlocks).









   .. method:: trylock() -> bool

      Tries to lock ``mutex``\. If ``mutex`` is already locked by another thread,
      it immediately returns :const:`False`. Otherwise it locks ``mutex`` and returns
      :const:`True`.

      :obj:`~gi.repository.GLib.Mutex` is neither guaranteed to be recursive nor to be
      non-recursive.  As such, calling :func:`~gi.repository.GLib.Mutex.lock` on a :obj:`~gi.repository.GLib.Mutex` that has
      already been locked by the same thread results in undefined behaviour
      (including but not limited to deadlocks or arbitrary return values).









   .. method:: unlock() -> None

      Unlocks ``mutex``\. If another thread is blocked in a :func:`~gi.repository.GLib.Mutex.lock`
      call for ``mutex``\, it will become unblocked and can lock ``mutex`` itself.

      Calling :func:`~gi.repository.GLib.Mutex.unlock` on a mutex that is not locked by the
      current thread leads to undefined behaviour.



















Fields
------

.. rst-class:: interim-class

.. class:: Mutex
   :no-index:
   

   .. attribute:: i

      






   .. attribute:: p