libvirt/src/locking
Eric Blake 8e22e08935 build: rename files.h to virfile.h
In preparation for a future patch adding new virFile APIs.

* src/util/files.h, src/util/files.c: Move...
* src/util/virfile.h, src/util/virfile.c: ...here, and rename
functions to virFile prefix.  Macro names are intentionally
left alone.
* *.c: All '#include "files.h"' uses changed.
* src/Makefile.am (UTIL_SOURCES): Reflect rename.
* cfg.mk (exclude_file_name_regexp--sc_prohibit_close): Likewise.
* src/libvirt_private.syms: Likewise.
* docs/hacking.html.in: Likewise.
* HACKING: Regenerate.
2011-07-21 10:34:51 -06:00
..
domain_lock.c Ensure sanlock socket is labelled with the VM process label 2011-06-28 16:41:46 +01:00
domain_lock.h Ensure sanlock socket is labelled with the VM process label 2011-06-28 16:41:46 +01:00
libvirt_sanlock.aug Support automatic creation of leases for disks in sanlock 2011-06-28 18:18:06 +01:00
lock_driver_nop.c build: add syntax check for proper flags use 2011-07-15 16:37:30 -06:00
lock_driver_nop.h Add a 'nop' lock driver implementation. 2011-06-02 10:54:00 +01:00
lock_driver_sanlock.c build: rename files.h to virfile.h 2011-07-21 10:34:51 -06:00
lock_driver.h Allow per-driver config file for lock manager plugins 2011-06-28 18:07:06 +01:00
lock_manager.c build: add syntax check for proper flags use 2011-07-15 16:37:30 -06:00
lock_manager.h Allow per-driver config file for lock manager plugins 2011-06-28 18:07:06 +01:00
README Add higher level lock API for domain objects 2011-06-02 10:54:01 +01:00
sanlock.conf Support automatic creation of leases for disks in sanlock 2011-06-28 18:18:06 +01:00
test_libvirt_sanlock.aug Support automatic creation of leases for disks in sanlock 2011-06-28 18:18:06 +01:00

       Using the Lock Manager APIs
       ===========================

This file describes how to use the lock manager APIs.
All the guest lifecycle sequences here have higher
level wrappers provided by the 'domain_lock.h' API,
which simplify thue usage

At libvirtd startup:

  plugin = virLockManagerPluginLoad("sync-manager");


At libvirtd shtudown:

  virLockManagerPluginUnload(plugin)


At guest startup:

  manager = virLockManagerNew(plugin,
                              VIR_LOCK_MANAGER_OBJECT_DOMAIN,
                              0);

  virLockManagerSetParameter(manager, "id", id);
  virLockManagerSetParameter(manager, "uuid", uuid);
  virLockManagerSetParameter(manager, "name", name);

  foreach disk
    virLockManagerRegisterResource(manager,
                                   VIR_LOCK_MANAGER_RESOURCE_TYPE_DISK,
                                   disk.path,
                                   ..flags...);

  if (!virLockManagerAcquireObject(manager))
    abort..

  run QEMU


At guest shutdown:

  ...send QEMU 'quit' monitor command, and/or kill(qemupid)...

  if (!virLockManagerShutdown(manager))
     kill(supervisorpid); /* XXX or leave it running ??? */

  virLockManagerFree(manager);



At libvirtd restart with running guests:

  foreach still running guest
    manager = virLockManagerNew(driver,
                                VIR_LOCK_MANAGER_START_DOMAIN,
                                VIR_LOCK_MANAGER_NEW_ATTACH);
    virLockManagerSetParameter(manager, "id", id);
    virLockManagerSetParameter(manager, "uuid", uuid);
    virLockManagerSetParameter(manager, "name", name);

    if (!virLockManagerGetChild(manager, &qemupid))
      kill(supervisorpid); /* XXX or leave it running ??? */



With disk hotplug:

  if (virLockManagerAcquireResource(manager,
                                    VIR_LOCK_MANAGER_RESOURCE_TYPE_DISK,
                                    disk.path
                                    ..flags..))
     ...abort hotplug attempt ...

  ...hotplug the device...



With disk unhotplug:

    ...hotunplug the device...

  if (virLockManagerReleaseResource(manager,
                                    VIR_LOCK_MANAGER_RESOURCE_TYPE_DISK,
                                    disk.path
                                    ..flags..))
     ...log warning ...



During migration:

  1. On source host

       if (!virLockManagerPrepareMigrate(manager, hosturi))
           ..don't start migration..

  2. On dest host

      manager = virLockManagerNew(driver,
                                  VIR_LOCK_MANAGER_START_DOMAIN,
                                  VIR_LOCK_MANAGER_NEW_MIGRATE);
      virLockManagerSetParameter(manager, "id", id);
      virLockManagerSetParameter(manager, "uuid", uuid);
      virLockManagerSetParameter(manager, "name", name);

      foreach disk
        virLockManagerRegisterResource(manager,
                                       VIR_LOCK_MANAGER_RESOURCE_TYPE_DISK,
                                       disk.path,
                                       ..flags...);

      char **supervisorargv;
      int supervisorargc;

      supervisor = virLockManagerGetSupervisorPath(manager);
      virLockManagerGetSupervisorArgs(&argv, &argc);

      cmd = qemuBuildCommandLine(supervisor, supervisorargv, supervisorargv);

      supervisorpid = virCommandExec(cmd);

      if (!virLockManagerGetChild(manager, &qemupid))
        kill(supervisorpid); /* XXX or leave it running ??? */

  3. Initiate migration in QEMU on source and wait for completion

  4a. On failure

      4a1 On target

            virLockManagerCompleteMigrateIn(manager,
                                            VIR_LOCK_MANAGER_MIGRATE_CANCEL);
            virLockManagerShutdown(manager);
            virLockManagerFree(manager);

      4a2 On source

            virLockManagerCompleteMigrateIn(manager,
                                            VIR_LOCK_MANAGER_MIGRATE_CANCEL);

  4b. On succcess


      4b1 On target

            virLockManagerCompleteMigrateIn(manager, 0);

      42 On source

            virLockManagerCompleteMigrateIn(manager, 0);
            virLockManagerShutdown(manager);
            virLockManagerFree(manager);


Notes:

  - If a lock manager impl does just VM level leases, it can
    ignore all the resource paths at startup.

  - If a lock manager impl does not support migrate
    it can return an error from all migrate calls

  - If a lock manger impl does not support hotplug
    it can return an error from all resource acquire/release calls