labthings_fastapi.global_lock
=============================

.. py:module:: labthings_fastapi.global_lock

.. autoapi-nested-parse::

   Global locking.

   If the feature is enabled, a global lock is used to restrict running actions
   and setting properties. This module defines a wrapper for `threading.RLock`
   with a context manager that acquires the lock using a short timeout.



Classes
-------

.. autoapisummary::

   labthings_fastapi.global_lock.GlobalLock


Module Contents
---------------

.. py:class:: GlobalLock

   An RLock wrapper and work-a-like with a default timeout.

   Initialise the global lock.


   .. py:attribute:: _lock


   .. py:attribute:: default_timeout
      :type:  float
      :value: 0.05



   .. py:method:: acquire(blocking: bool = True, timeout: float | types.EllipsisType = ...) -> bool

      Acquire the lock.

      This wraps the underlying `threading.RLock.acquire` but will by default
      block with a short timeout.

      :param blocking: whether to wait for the lock to become free. `True` (the
          default) will block until the lock is available or we time out. `False`
          will always return immediately.
      :param timeout: the length of time to wait for the lock, if ``blocking`` is
          `True` - or `-1` to specify waiting forever.

      :return: whether the lock was successfully acquired.



   .. py:method:: release() -> None

      Release the lock.

      This wraps `threading.RLock.release` without modification.



   .. py:method:: __enter__() -> None

      Allow the lock to be used as a context manager.

      The behaviour when used as a context manager is different from a regular
      `threading.RLock` because it will use the default timeout rather than
      blocking forever.

      :raises GlobalLockBusyError: if the lock is in use by another thread.



   .. py:method:: __exit__(exc_type: type[BaseException] | None, exc_value: BaseException | None, traceback: types.TracebackType | None) -> None

      Allow the lock to be used as a context manager.

      The lock is released when the context ends. No error handling is done.

      :param exc_type: the exception type, if one was raised (ignored).
      :param exc_value: the exception, if one was raised (ignored).
      :param traceback: the traceback, if an error was raised (ignored).