Add doc/locking.txt, documenting locking order

Reviewed-by: imsnah

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) \

doc/locking.txt

+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.
+