Add doc/locking.txt, documenting locking order

Reviewed-by: imsnah

diff --git a/Makefile.am b/Makefile.am
index f9682dd..c329c5e 100644 (file)
--- a/Makefile.am
+++ b/Makefile.am
@@ -139,6 +139,7 @@ EXTRA_DIST = \
        doc/examples/ganeti.initd.in \
        doc/examples/ganeti.cron.in \
        doc/examples/dumb-allocator \
+       doc/locking.txt \
        test/testutils.py \
        test/mocks.py \
        $(dist_TESTS) \

diff --git a/doc/locking.txt b/doc/locking.txt
new file mode 100644 (file)
index 0000000..5a8cdbc
--- /dev/null
+++ b/doc/locking.txt
@@ -0,0 +1,33 @@
+Introduction:
+
+This document describes lock order dependencies in Ganeti.
+It is divided by functional sections
+
+
+Opcode Execution Locking:
+
+These locks are declared by Logical Units (LUs) (in cmdlib.py) and acquired by
+the Processor (in mcpu.py) with the aid of the Ganeti Locking Library
+(locking.py). They are acquired in the following order:
+
+  * BGL: this is the Big Ganeti Lock, it exists for retrocompatibility. New LUs
+    acquire it in a shared fashion, and are able to execute all toghether
+    (baring other lock waits) while old LUs acquire it exclusively and can only
+    execute one at a time, and not at the same time with new LUs.
+  * Instance locks: can be declared in ExpandNames() o DeclareLocks() by an LU,
+    and have the same name as the instance itself. They are acquired as a set.
+    Internally the locking library acquired them in alphabetical order.
+  * Node locks: can be declared in ExpandNames() o DeclareLocks() by an LU, and
+    have the same name as the node itself. They are acquired as a set.
+    Internally the locking library acquired them in alphabetical order. Given
+    this order it's possible to safely acquire a set of instances, and then the
+    nodes they reside on.
+
+The ConfigWriter (in config.py) is also protected by a SharedLock, which is
+shared by functions that read the config and acquired exclusively by functions
+that modify it. Since the ConfigWriter calls rpc.call_upload_file to all nodes
+to distribute the config without holding the node locks, this call must be able
+to execute on the nodes in parallel with other operations (but not necessarily
+concurrently with itself on the same file, as inside the ConfigWriter this is
+called with the internal config lock held.
+