# `oslo_concurrency.lockutils`

exception oslo_concurrency.lockutils.AcquireLockFailedException(lock_name: str)

  Bases: `Exception`

class oslo_concurrency.lockutils.FairLocks

  Bases: `object`

  A garbage collected container of fair locks.

  With a fair lock, contending lockers will get the lock in the order in which they tried to acquire it.

  This collection internally uses a weak value dictionary so that when a lock is no longer in use (by any threads) it will automatically be removed from this container by the garbage collector.

  get(name: str) → ReaderWriterLock

    Gets (or creates) a lock with a given name.

    Parameters:

      name – The lock name to get/create (used to associate previously created names with the same lock).

    Returns an newly constructed lock (or an existing one if it was already created for the given name).

class oslo_concurrency.lockutils.LockPartialProtocol(*args, **kwargs)

  Bases: `Protocol`

class oslo_concurrency.lockutils.ReaderWriterLock(condition_cls: ~typing.Any = <class 'threading.Condition'>, current_thread_functor: ~collections.abc.Callable[[], ~threading.Thread] = <function current_thread>)

  Bases: `ReaderWriterLock`

  A reader/writer lock.

  Added in version 0.4.

class oslo_concurrency.lockutils.RemovePartialProtocol(*args, **kwargs)

  Bases: `Protocol`

class oslo_concurrency.lockutils.Semaphores

  Bases: `object`

  A garbage collected container of semaphores.

  This collection internally uses a weak value dictionary so that when a semaphore is no longer in use (by any threads) it will automatically be removed from this container by the garbage collector.

  Added in version 0.3.

  get(name: str) → Semaphore

    Gets (or creates) a semaphore with a given name.

    Parameters:

      name – The semaphore name to get/create (used to associate previously created names with the same semaphore).

    Returns an newly constructed semaphore (or an existing one if it was already created for the given name).

class oslo_concurrency.lockutils.SyncPartialProtocol(*args, **kwargs)

  Bases: `Protocol`

oslo_concurrency.lockutils.external_lock(name: str, lock_file_prefix: str | None = None, lock_path: str | None = None) → InterProcessLock

oslo_concurrency.lockutils.get_lock_path(conf: ConfigOpts) → str | None

  Return the path used for external file-based locks.

  Parameters:

    conf (oslo_config.cfg.ConfigOpts) – Configuration object

  Added in version 1.8.

oslo_concurrency.lockutils.internal_fair_lock(name: str) → ReaderWriterLock

oslo_concurrency.lockutils.internal_lock(name: str, semaphores: Semaphores | None = None, blocking: Literal[False] = False) → Semaphore
oslo_concurrency.lockutils.internal_lock(name: str, semaphores: Semaphores | None = None, blocking: Literal[True] = True) → AbstractContextManager[Semaphore]
oslo_concurrency.lockutils.internal_lock(name: str, semaphores: Semaphores | None = None, blocking: bool = True) → AbstractContextManager[Semaphore] | Semaphore

oslo_concurrency.lockutils.lock(name: str, lock_file_prefix: str | None = None, external: bool = False, lock_path: str | None = None, do_log: bool = True, semaphores: Semaphores | None = None, delay: float = 0.01, fair: bool = False, blocking: bool = True) → Generator[ReaderWriterLock, None, None]

  Context based lock

  This function yields a threading.Semaphore instance (if we don’t use eventlet.monkey_patch(), else semaphore.Semaphore) unless external is True, in which case, it’ll yield an InterProcessLock instance.

  Parameters:

    - lock_file_prefix – The lock_file_prefix argument is used to provide lock files on disk with a meaningful prefix.

    - external – The external keyword argument denotes whether this lock should work across multiple processes. This means that if two different workers both run a method decorated with @synchronized(‘mylock’, external=True), only one of them will execute at a time.

    - lock_path – The path in which to store external lock files. For external locking to work properly, this must be the same for all references to the lock.

    - do_log – Whether to log acquire/release messages. This is primarily intended to reduce log message duplication when lock is used from the synchronized decorator.

    - semaphores – Container that provides semaphores to use when locking. This ensures that threads inside the same application can not collide, due to the fact that external process locks are unaware of a processes active threads.

    - delay – Delay between acquisition attempts (in seconds).

    - fair – Whether or not we want a “fair” lock where contending lockers will get the lock in the order in which they tried to acquire it.

    - blocking – Whether to wait forever to try to acquire the lock. Incompatible with fair locks because those provided by the fasteners module doesn’t implements a non-blocking behavior.

  Changed in version 0.2: Added do_log optional parameter.

  Changed in version 0.3: Added delay and semaphores optional parameters.

oslo_concurrency.lockutils.lock_with_prefix(lock_file_prefix: str) → LockPartialProtocol

  Partial object generator for the lock context manager.

  Redefine lock in each project like so:

      (in nova/utils.py)
      from oslo_concurrency import lockutils

      _prefix = 'nova'
      lock = lockutils.lock_with_prefix(_prefix)
      lock_cleanup = lockutils.remove_external_lock_file_with_prefix(_prefix)

      (in nova/foo.py)
      from nova import utils

      with utils.lock('mylock'):
         ...

  Eventually clean up with:

      lock_cleanup('mylock')

  Parameters:

    lock_file_prefix – A string used to provide lock files on disk with a meaningful prefix. Will be separated from the lock name with a hyphen, which may optionally be included in the lock_file_prefix (e.g. `'nova'` and `'nova-'` are equivalent).

oslo_concurrency.lockutils.main() → None

oslo_concurrency.lockutils.remove_external_lock_file(name: str, lock_file_prefix: str | None, lock_path: str | None = None, semaphores: Semaphores | None = None) → None

  Remove an external lock file when it’s not used anymore

  This will be helpful when we have a lot of lock files

oslo_concurrency.lockutils.remove_external_lock_file_with_prefix(lock_file_prefix: str) → RemovePartialProtocol

  Partial object generator for the remove lock file function.

  Redefine remove_external_lock_file_with_prefix in each project like so:

      (in nova/utils.py)
      from oslo_concurrency import lockutils

      _prefix = 'nova'
      synchronized = lockutils.synchronized_with_prefix(_prefix)
      lock = lockutils.lock_with_prefix(_prefix)
      lock_cleanup = lockutils.remove_external_lock_file_with_prefix(_prefix)

      (in nova/foo.py)
      from nova import utils

      @utils.synchronized('mylock')
      def bar(self, *args):
          ...

      def baz(self, *args):
          ...
          with utils.lock('mylock'):
              ...
          ...

      <eventually call lock_cleanup('mylock') to clean up>

  The lock_file_prefix argument is used to provide lock files on disk with a meaningful prefix.

oslo_concurrency.lockutils.set_defaults(lock_path: str) → None

  Set value for lock_path.

  This can be used by tests to set lock_path to a temporary directory.

oslo_concurrency.lockutils.synchronized(name: str, lock_file_prefix: str | None = None, external: bool = False, lock_path: str | None = None, semaphores: Semaphores | None = None, delay: float = 0.01, fair: bool = False, blocking: bool = True) → Callable[[Callable[[P], T]], Callable[[P], T]]

  Synchronization decorator.

  Decorating a method like so:

      @synchronized('mylock')
      def foo(self, *args): ...

  ensures that only one thread will execute the foo method at a time.

  Different methods can share the same lock:

      @synchronized('mylock')
      def foo(self, *args): ...

      @synchronized('mylock')
      def bar(self, *args): ...

  This way only one of either foo or bar can be executing at a time.

  Changed in version 0.3: Added delay and semaphores optional parameter.

oslo_concurrency.lockutils.synchronized_with_prefix(lock_file_prefix: str) → SyncPartialProtocol

  Partial object generator for the synchronization decorator.

  Redefine @synchronized in each project like so:

      (in nova/utils.py)
      from oslo_concurrency import lockutils

      _prefix = 'nova'
      synchronized = lockutils.synchronized_with_prefix(_prefix)
      lock_cleanup = lockutils.remove_external_lock_file_with_prefix(_prefix)

      (in nova/foo.py)
      from nova import utils

      @utils.synchronized('mylock')
      def bar(self, *args):
         ...

  Eventually clean up with:

      lock_cleanup('mylock')

  Parameters:

    lock_file_prefix – A string used to provide lock files on disk with a meaningful prefix. Will be separated from the lock name with a hyphen, which may optionally be included in the lock_file_prefix (e.g. `'nova'` and `'nova-'` are equivalent).

this page last updated: 2026-03-03 12:28:36

Except where otherwise noted, this document is licensed under Creative Commons Attribution 3.0 License. See all OpenStack Legal Documents.

found an error? report a bug