:github_url: hide .. DO NOT EDIT THIS FILE!!! .. Generated automatically from Godot engine sources. .. Generator: https://github.com/godotengine/godot/tree/3.6/doc/tools/make_rst.py. .. XML source: https://github.com/godotengine/godot/tree/3.6/doc/classes/Mutex.xml. .. _class_Mutex: Mutex ===== **Inherits:** :ref:`Reference` **<** :ref:`Object` A synchronization mutex (mutual exclusion). .. rst-class:: classref-introduction-group Description ----------- A synchronization mutex (mutual exclusion). This is used to synchronize multiple :ref:`Thread`\ s, and is equivalent to a binary :ref:`Semaphore`. It guarantees that only one thread can ever acquire the lock at a time. A mutex can be used to protect a critical section; however, be careful to avoid deadlocks. It's of the recursive kind, so it can be locked multiple times by one thread, provided it also unlocks it as many times. \ **Warning:**\ To guarantee that the operating system is able to perform proper cleanup (no crashes, no deadlocks), these conditions must be met: - By the time a **Mutex**'s reference count reaches zero and therefore it is destroyed, no threads (including the one on which the destruction will happen) must have it locked. - By the time a :ref:`Thread`'s reference count reaches zero and therefore it is destroyed, it must not have any mutex locked. .. rst-class:: classref-introduction-group Tutorials --------- - :doc:`../tutorials/performance/threads/using_multiple_threads` .. rst-class:: classref-reftable-group Methods ------- .. table:: :widths: auto +---------------------------------------+----------------------------------------------------------+ | void | :ref:`lock` **(** **)** | +---------------------------------------+----------------------------------------------------------+ | :ref:`Error` | :ref:`try_lock` **(** **)** | +---------------------------------------+----------------------------------------------------------+ | void | :ref:`unlock` **(** **)** | +---------------------------------------+----------------------------------------------------------+ .. rst-class:: classref-section-separator ---- .. rst-class:: classref-descriptions-group Method Descriptions ------------------- .. _class_Mutex_method_lock: .. rst-class:: classref-method void **lock** **(** **)** Locks this **Mutex**, blocks until it is unlocked by the current owner. \ **Note:** This function returns without blocking if the thread already has ownership of the mutex. .. rst-class:: classref-item-separator ---- .. _class_Mutex_method_try_lock: .. rst-class:: classref-method :ref:`Error` **try_lock** **(** **)** Tries locking this **Mutex**, but does not block. Returns :ref:`@GlobalScope.OK` on success, :ref:`@GlobalScope.ERR_BUSY` otherwise. \ **Note:** This function returns :ref:`@GlobalScope.OK` if the thread already has ownership of the mutex. .. rst-class:: classref-item-separator ---- .. _class_Mutex_method_unlock: .. rst-class:: classref-method void **unlock** **(** **)** Unlocks this **Mutex**, leaving it to other threads. \ **Note:** If a thread called :ref:`lock` or :ref:`try_lock` multiple times while already having ownership of the mutex, it must also call :ref:`unlock` the same number of times in order to unlock it correctly. \ **Warning:** Calling :ref:`unlock` more times that :ref:`lock` on a given thread, thus ending up trying to unlock a non-locked mutex, is wrong and may causes crashes or deadlocks. .. |virtual| replace:: :abbr:`virtual (This method should typically be overridden by the user to have any effect.)` .. |const| replace:: :abbr:`const (This method has no side effects. It doesn't modify any of the instance's member variables.)` .. |vararg| replace:: :abbr:`vararg (This method accepts any number of arguments after the ones described here.)` .. |static| replace:: :abbr:`static (This method doesn't need an instance to be called, so it can be called directly using the class name.)`