cbdf411306
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
75 lines
2.6 KiB
ReStructuredText
75 lines
2.6 KiB
ReStructuredText
=======
|
|
Usage
|
|
=======
|
|
|
|
To use oslo.concurrency in a project, import the relevant module. For
|
|
example::
|
|
|
|
from oslo_concurrency import lockutils
|
|
from oslo_concurrency import processutils
|
|
|
|
.. seealso::
|
|
|
|
* :doc:`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 :envvar:`OSLO_LOCK_PATH` set. To
|
|
use it, prefix the command to be run with
|
|
:command:`lockutils-wrapper`. For example::
|
|
|
|
$ lockutils-wrapper env | grep OSLO_LOCK_PATH
|
|
OSLO_LOCK_PATH=/tmp/tmpbFHK45
|