Merge "doc: add locking"

doc/source/tutorial/index.rst

@@ -11,3 +11,4 @@ use tooz in your application.
    coordinator
    group_membership
    leader_election
+   lock

doc/source/tutorial/lock.rst

@@ -0,0 +1,14 @@
+======
+ Lock
+======
+
+Tooz provides distributed locks. A lock is identified by a name, and a lock can
+only be acquired by one coordinator at a time.
+
+.. literalinclude:: ../../../examples/lock.py
+   :language: python
+
+The method :meth:`tooz.coordination.CoordinationDriver.get_lock` allows
+to create a lock identified by a name. Once the you retrieve this lock, you can
+use it as a context manager or use the :meth:`tooz.locking.Lock.acquire` and
+:meth:`tooz.locking.Lock.release` methods to acquire and release the lock.

examples/lock.py

@@ -0,0 +1,11 @@
+from tooz import coordination
+
+coordinator = coordination.get_coordinator('kazoo://localhost', b'host-1')
+coordinator.start()
+
+# Create a lock
+lock = coordinator.get_lock("foobar")
+with lock:
+    print("Do something that is distributed")
+
+coordinator.stop()