From 0f933d15fecb7deb8d645fcd2fba961695f5e06f Mon Sep 17 00:00:00 2001 From: Guido Trotter <ultrotter@google.com> Date: Fri, 29 Aug 2008 12:45:33 +0000 Subject: [PATCH] Add doc/locking.txt, documenting locking order Reviewed-by: imsnah --- Makefile.am | 1 + doc/locking.txt | 33 +++++++++++++++++++++++++++++++++ 2 files changed, 34 insertions(+) create mode 100644 doc/locking.txt diff --git a/Makefile.am b/Makefile.am index f9682dd6c..c329c5e54 100644 --- 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 index 000000000..5a8cdbc45 --- /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. + -- GitLab