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

1 files changed, 51 insertions, 0 deletions

diff --git a/doc/source/usage.rst b/doc/source/usage.rst
index f438151..dd8ba98 100644
--- a/doc/source/usage.rst
+++ b/doc/source/usage.rst
@@ -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
 ====================