Joshua Harlow cbdf411306 Add a few usage examples for lockutils

There was a complaint that the usage examples in oslo.concurrency
are lacking (which they are) so this addresses some of those concerns
by adding a few usage examples (and descriptions).

Change-Id: I0738b898f1235e83a600c7732d70058b3fd3860f

2016-03-17 15:06:53 -07:00

2.6 KiB

Raw Blame History

Usage

To use oslo.concurrency in a project, import the relevant module. For example:

from oslo_concurrency import lockutils
from oslo_concurrency import processutils

API Documentation <api/index>

Locking a function (local to a process)

To ensure that a function (which is not thread safe) is only used in a thread safe manner (typically such type of function should be refactored to avoid this problem but if not then the following can help):

@lockutils.synchronized('not_thread_safe')
def not_thread_safe():
    pass

Once decorated later callers of this function will be able to call into this method and the contract that two threads will not enter this function at the same time will be upheld. Make sure that the names of the locks used are carefully chosen (typically by namespacing them to your app so that other apps will not chose the same names).

Locking a function (local to a process as well as across process)

To ensure that a function (which is not thread safe or multi-process safe) is only used in a safe manner (typically such type of function should be refactored to avoid this problem but if not then the following can help):

@lockutils.synchronized('not_thread_process_safe', external=True)
def not_thread_process_safe():
    pass

Once decorated later callers of this function will be able to call into this method and the contract that two threads (or any two processes) will not enter this function at the same time will be upheld. Make sure that the names of the locks used are carefully chosen (typically by namespacing them to your app so that other apps will not chose the same names).

Common ways to prefix/namespace the synchronized decorator

Since it is highly recommended to prefix (or namespace) the usage of the synchronized there are a few helpers that can make this much easier to achieve.

An example is:

myapp_synchronized = lockutils.synchronized_with_prefix("myapp")

Then further usage of the lockutils.synchronized would instead now use this decorator created above instead of using lockutils.synchronized directly.

Command Line Wrapper

oslo.concurrency includes a command line tool for use in test jobs that need the environment variable OSLO_LOCK_PATH set. To use it, prefix the command to be run with lockutils-wrapper. For example:

$ lockutils-wrapper env | grep OSLO_LOCK_PATH
OSLO_LOCK_PATH=/tmp/tmpbFHK45

2.6 KiB Raw Blame History