[libvirt] [PATCH 06/10] Add initial docs about the lock managers

Fri May 27 08:57:08 UTC 2011

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 at veillard.com  | Rpmfind RPM search engine http://rpmfind.net/
http://veillard.com/ | virtualization library  http://libvirt.org/