1 files changed, 42 insertions, 0 deletions
diff --git a/doc/source/user/tutorial/coordinator.rst b/doc/source/user/tutorial/coordinator.rst
new file mode 100644
index 0000000..0131dee
--- /dev/null
+++ b/doc/source/user/tutorial/coordinator.rst
@@ -0,0 +1,42 @@
+=======================
+ Creating A Coordinator
+=======================
+
+The principal object provided by tooz is the *coordinator*. It allows you to
+use various features, such as group membership, leader election or
+distributed locking.
+
+The features provided by tooz coordinator are implemented using different
+drivers. When creating a coordinator, you need to specify which back-end
+driver you want it to use. Different drivers may provide different set of
+capabilities.
+
+If a driver does not support a feature, it will raise a
+:class:`~tooz.NotImplemented` exception.
+
+This example program loads a basic coordinator using the ZooKeeper based
+driver.
+
+.. literalinclude:: ../../../../examples/coordinator.py
+   :language: python
+
+The second argument passed to the coordinator must be a unique identifier
+identifying the running program.
+
+After the coordinator is created, it can be used to use the various features
+provided.
+
+In order to keep the connection to the coordination server active, the method
+:meth:`~tooz.coordination.CoordinationDriver.heartbeat` method must be called
+regularly. This will ensure that the coordinator is not considered dead by
+other program participating in the coordination. Unless you want to call it
+manually, you can use tooz builtin heartbeat manager by passing the
+`start_heart` argument.
+
+.. literalinclude:: ../../../../examples/coordinator_heartbeat.py
+   :language: python
+
+heartbeat at different moment or intervals.
+
+Note that certain drivers, such as `memcached` are heavily based on timeout,
+so the interval used to run the heartbeat is important.