openstack/oslo.concurrency
Code Issues Proposed changes

Add a few usage examples for lockutils

Browse Source 
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
This commit is contained in:
Joshua Harlow 2016-03-17 15:06:50 -07:00
parent 7cd7883936
commit cbdf411306
1 changed files with 51 additions and 0 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

51
doc/source/usage.rst
View File

@ -6,11 +6,62 @@ 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
====================