[libvirt] RFC [1/3]: The internal lock manager API

[Eric Blake]

On 09/10/2010 10:00 AM, Daniel P. Berrange wrote:
> /**
>   * virLockManagerSetParameter:
>   * @manager: the lock manager context
>   * @key: the parameter name
>   * @value: the parameter value
>   *
>   * Set a configuration parameter for the managed process.
>   * A process of VIR_LOCK_MANAGER_START_DOMAIN will be
>   * given at least 3 parameters:
>   *
>   * - id: the domain unique id
>   * - uuid: the domain uuid
>   * - name: the domain name
>   *
>   * There may be other parameters specific to the lock manager
>   * plugin that are provided for the managed process
>   *
>   * This should only be called prior to the supervised process
>   * being started. Setting parameters may change the set of
>   * argv returned by virLockManagerGetSupervisorArgs.

Returns 0 on success, -1 on failure?  I'm guessing this is general usage 
throughout this file, but should it be mentioned per function, or just 
once up front?

> /**
>   * virLockManagerRegisterResource:
>   * @manager: the lock manager context
>   * @type: the resource type virLockManagerResourceType
>   * @name: the resource name
>   * @flags: the resource access flags
>   *
>   * Register a resource that is required when the process
>   * starts up. This may only be called prior to the process
>   * being started. The format of @name varies according to
>   * the resource @type. A VIR_LOCK_MANAGER_RESOURCE_TYPE_DISK
>   * will have a fully qualified file path.
>   *
>   * If no flags are given, the resource is assumed to be
>   * used in exclusive, read-write mode. Access can be
>   * relaxed to readonly, or shared read-write.

Returns 0 on success, -1 on failure?

> /**
>   * virLockManagerAcquireResource:
>   * @manager: the lock manager context
>   * @type: the resource type virLockManagerResourceType
>   * @name: the resource name
>   * @flags: the resource access flags
>   *
>   * Dynamically acquire a resource for a running process.
>   * This may only be called once the process has been
>   * started. The format of @name varies according to
>   * the resource @type. A VIR_LOCK_MANAGER_RESOURCE_TYPE_DISK
>   * will have a fully qualified file path.
>   *
>   * If no flags are given, the resource is assumed to be
>   * used in exclusive, read-write mode. Access can be
>   * relaxed to readonly, or shared read-write.

Does this guarantee that lock is not obtained on failure?  Should flags 
include VIR_LOCK_ACQUIRE_PROBE, which then allows the choice between 
blocking to wait for the lock (flags==0) or an immediate return of -2 if 
the lock is already owned by another process (flags==1)?

> /**
>   * virLockManagerReleaseResource:
>   * @manager: the lock manager context
>   * @type: the resource type virLockManagerResourceType
>   * @name: the resource name
>   * @flags: the resource access flags
>   *
>   * Dynamically release a resource for a running process.
>   * This may only be called after the process has been
>   * started. The format of @name varies according to
>   * the resource @type. A VIR_LOCK_MANAGER_RESOURCE_TYPE_DISK
>   * will have a fully qualified file path.
>   *
>   * If no flags are given, the resource is assumed to be
>   * used in exclusive, read-write mode. Access can be
>   * relaxed to readonly, or shared read-write.

If this fails, is the resource state indeterminate, or is it still 
guaranteed to be locked?

> /**
>   * virLockManagerPrepareMigrate:
>   * @manager: the lock manager context
>   * @targetURI: destination of the migration
>   *
>   * Notify the supevisor that the process is about to be migrated

s/supevisor/supervisor/

> /**
>   * virLockManager:
>   * @manager: the lock manager context
>   *
>   * Inform the supervisor that the supervised process has
>   * been, or can be stopped.

Does this automatically release any locks held by the manager, or fail 
if the manager still owns locks?

> /**
>   * virLockManager:
>   * @manager: the lock manager context
>   *
>   * Release resources. If the supervised process is still
>   * running, it will be killed with prejudice

Does this first attempt to automatically release any locks held by the 
manager?

-- 
Eric Blake   eblake at redhat.com    +1-801-349-2682
Libvirt virtualization library http://libvirt.org