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

[Daniel P. Berrange]

On Fri, Sep 10, 2010 at 01:50:56PM -0600, Eric Blake wrote:
> 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?

Yes, they're all folllowing that normal convention.

> >/**
> >  * 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)?

I can't really think of a case when libvirt would need todo a
non-blocking probe, so I left that out for simplicity. Do we
need to guarentee that the lock is not obtained  on failure ?
I don't think that is neccessary to specify for safety, so
I'd just leave it undefined.

> 
> >/**
> >  * 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?

I think it is sufficient to leave it undefined, since that is
still safe.

> 
> >/**
> >  * virLockManager:

Opps, virLockManagerShutdown

> >  * @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?

The intention is that all locks will be released, but as above
this is not critical from a safety POV.

> 
> >/**
> >  * 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?

I intend that it will call virLockManagerShutdown() so in that sense, yes.

Daniel
-- 
|: Red Hat, Engineering, London    -o-   http://people.redhat.com/berrange/ :|
|: http://libvirt.org -o- http://virt-manager.org -o- http://deltacloud.org :|
|: http://autobuild.org        -o-         http://search.cpan.org/~danberr/ :|
|: GnuPG: 7D3B9505  -o-   F3C9 553F A1DA 4AC2 5648 23C1 B3DF F742 7D3B 9505 :|