3:57 a.m.
On Thu, May 19, 2011 at 07:24:21AM -0400, Daniel P. Berrange wrote:
---
docs/internals/locking.html.in | 257 ++++++++++++++++++++++++++++++++++++++++
docs/sitemap.html.in | 4 +
2 files changed, 261 insertions(+), 0 deletions(-)
create mode 100644 docs/internals/locking.html.in
diff --git a/docs/internals/locking.html.in b/docs/internals/locking.html.in
new file mode 100644
index 0000000..3790ef0
--- /dev/null
+++ b/docs/internals/locking.html.in
@@ -0,0 +1,257 @@
+<html>
+ <body>
+ <h1>Resource Lock Manager</h1>
+
+ <ul id="toc"></ul>
+
+ <p>
+ This page describes the design of the resource lock manager
+ that is used for locking disk images, to ensure exclusive
+ access to content.
+ </p>
+
+ <h2><a name="goals">Goals</a></h2>
+
+ <p>
+ The high level goal is to prevent the same disk image being
+ used by more than one QEMU instance at a time (unless the
+ disk is marked as sharable, or readonly). The scenarios
+ to be prevented are thus:
+ </p>
+
+ <ol>
+ <li>
+ Two different guests running configured to point at the
+ same disk image.
+ </li>
+ <li>
+ One guest being started more than once on two different
+ machines due to admin mistake
+ </li>
+ <li>
+ One guest being started more than once on a single machine
+ due to libvirt driver bug on a single machine.
+ </li>
+ </ol>
+
+ <h2><a name="requirement">Requirements</a></h2>
+
+ <p>
+ The high level goal leads to a set of requirements
+ for the lock manager design
+ </p>
+
+ <ol>
+ <li>
+ A lock must be held on a disk whenever a QEMU process
+ has the disk open
+ </li>
+ <li>
+ The lock scheme must allow QEMU to be configured with
+ readonly, shared write, or exclusive writable disks
+ </li>
+ <li>
+ A lock handover must be performed during the migration
+ process where 2 QEMU processes will have the same disk
+ open concurrently.
+ </li>
+ <li>
+ The lock manager must be able to identify and kill the
+ process accessing the resource if the lock is revoked.
+ </li>
+ <li>
+ Locks can be acquired for arbitrary VM related resources,
+ as determined by the management application.
+ </li>
+ </ol>
+
+ <h2><a name="design">Design</a></h2>
+
+ <p>
+ Within a lock manager the following series of operations
+ will need to be supported.
+ </p>
+
+ <ul>
+ <li>
+ <strong>Register object</strong>
+ Register the identity of an object against which
+ locks will be acquired
+ </li>
+ <li>
+ <strong>Add resource</strong>
+ Associate a resource with an object for future
+ lock acquisition / release
+ </li>
+ <li>
+ <strong>Acquire locks</strong>
+ Acquire the locks for all resources associated
+ with the object
+ </li>
+ <li>
+ <strong>Release locks</strong>
+ Release the locks for all resources associated
+ with the object
+ </li>
+ <li>
+ <strong>Inquire locks</strong>
+ Get a representation of the state of the locks
+ for all resources associated with the object
+ </li>
+ </ul>
+
+ <h2><a name="impl">Plugin
Implementations</a></h2>
+
+ <p>
+ Lock manager implementations are provided as LGPLv2+
+ licensed, dlopen()able library modules. The plugins
+ will be loadable from the following location:
Well unless they compile with a different prefix, right ?
will usually be loadable ....
+ </p>
+
+ <pre>
+/usr/{lib,lib64}/libvirt/lock_manager/$NAME.so
+</pre>
+
+ <p>
+ The lock manager plugin must export a single ELF
+ symbol named <code>virLockDriverImpl</code>, which is
+ a static instance of the <code>virLockDriver</code>
+ struct. The struct is defined in the header file
+ </p>
[...]
+ <p>
+ The following psuedo code illustrates the common
pseudo
+ patterns of operations invoked on the lock
+ manager plugin callbacks.
Shouldn't we point to the README in the src/locking subdir here ?
+ </p>
+
+ <h3><a name="usageLockAcquire">Lock
acquisition</a></h3>
+
small nits, ACK overall
Daniel
--
Daniel Veillard | libxml Gnome XML XSLT toolkit http://xmlsoft.org/
daniel(a)veillard.com | Rpmfind RPM search engine http://rpmfind.net/
http://veillard.com/ | virtualization library http://libvirt.org/