[Libvir] Re: Third version of virDomainMigrate API

[Richard W.M. Jones]

Daniel P. Berrange wrote:
> In terms of the set of data we need for a basic impl, I think these
> are resonable. That said I've been thinking about this in relation to 
> the earlier points in this  thread about cancellation, and progress info,
> etc. I'm wondering if we would be well served by introducing a new object 
> to co-ordinate the whole thing. 
> 
>   /* Prepare for migration to dconn */
>   virDomainMigratePtr mig = virDomainMigratePrepare(dom, dconn)
> 
>   /* Optionally specify a custom transport */
>   virDomainMigrateTransport(mig, "ssh://root@dest/");
> 
>   /* Optionally throttle */
>   virDomainMigrateBandwidth(mig, 10);
> 
>   /* Perform the migration */
>   virDomainMigrateRun(mig, flags);
> 
>   /* Release resources */
>   virDomainMigrateFree(mig);
> 
> This would make it easier for us to extend the capabilities in the
> future. eg adding more properties, or add APIs to run async, or 
> getting progress info, etc, etc.
> 
> eg, if flags request ASYNC, then one could imagine cancellation via
> 
>    virDomainMigrateAbort(mig);
> 
> Or to poll for completion...
> 
>    virDomainMigrateStatus(mig);
> 
> 
> Finally we could have a convenience API
> 
>    virDomainMigrate(dom, dconn);
> 
> For apps which don't care about custom transports, etc, etc

Totally off on a tangent here, but a trick from functional programming 
is to return a "suspension".  The call still looks like this:

   ddom = Domain.migrate dom dconn;

The trick is that the call returns immediately, and 'ddom' isn't 
necessarily a domain object, at least not until you try to use it.  For 
example, if the next statement was:

   printf "new domain id = %d\n" (Domain.id ddom);

then the call to Domain.id ddom would (in the jargon) "force the 
suspension" -- basically cause the program to wait until the domain has 
migrated before returning the ID.

With suspensions you can examine their state _without_ forcing them. 
For example:

   while Domain.is_migrating ddom; do
     printf "Domain still migrating ... %d percent done.\n"
       (Domain.migration_percent ddom);
     sleep 1;
   done;
   printf "Domain migrated, ID = %d\n" (Domain.id ddom)

(Of course error handling is omitted here, but in a functional language 
it would just use exceptions.  The C equivalent is more involved because 
you have to explicitly check for errors at every call).

The advantage of suspensions is that in the simple case where you don't 
care about fancy progress bars, the code looks exactly the same as normal.

Rich.