[libvirt] RFC: Domain events add DEFINED and UNDEFINED events

[Daniel P. Berrange]

We currently have the following list of events for domains:

      VIR_DOMAIN_EVENT_ADDED,
      VIR_DOMAIN_EVENT_REMOVED,
      VIR_DOMAIN_EVENT_STARTED,
      VIR_DOMAIN_EVENT_SUSPENDED,
      VIR_DOMAIN_EVENT_RESUMED,
      VIR_DOMAIN_EVENT_STOPPED,
      VIR_DOMAIN_EVENT_SAVED,
      VIR_DOMAIN_EVENT_RESTORED,

The QEMU driver supports all of them, except for ADDED and REMOVED. I
was looking at adding these and wondering how exactly we should define
the semantics

Originally I was just going to emit 'ADDED' from virDomainDefine() driver
impl and 'REMOVED' from virDomainUndefine().

This does not, however, take into account that there are two sorts of
domains, so called 'persistent' and 'transient' domains.

With a transient domain, there is no config file, so the first time you
know about the domain is when it is booted via virDomainCreateXML(),
and all trace of it disappears when it shuts down, or migrates, or is
saved.  With a persistent domain though, it is visible before it is
booted, and remains visible after shutdown/migrate/save etc.

The current set of events does not allow applications to get this level
of visibility. eg when receiving a VIR_DOMAIN_EVENT_STOPPED event, there
is no way to know wether the domain was transient / persistent, and thus
whether to remove it from your list of VMs, or simply mark it shutoff.

So, I'd like to propose that we do the following:

 - Clarify the semantics for 

    * VIR_DOMAIN_EVENT_ADDED
    
    Emitted when a domain comes into existance, by which I mean a
    previously known inactive domain is defined, or a transient
    domain is booted. This is emited before any other events for
    a domain with that UUID/name.

    * VIR_DOMAIN_EVENT_REMOVED

    Emitted when a domains goes out of existance, by which I mean
    a transient domain shuts down / migrates / is saved, or a
    persistent domain is undefined. This is the last event ever to
    be emitted for a domain with that UUID/name.


 - Create two more events

     * VIR_DOMAIN_EVENT_DEFINED

     Emitted whenenever a domain's config file is created. This can
     be when a peristent domain is first defined, when it is later
     re-defined, or when an transient domain gains a confi file,
     becoming persistent.

     * VIR_DOMAIN_EVENT_UNDEFINED

     Emitted when a domain's config file is removed.

With this complete set of events, virt-manager is able to track domains
without ever having to poll for the domain listing.

I think we also need to provide some way for an application to determine
what set of events a hypervisor backend supports. eg, if it only supports
the STARTED/STOPPED events, virt-manager would still need to do polling to
find out about defined/undefined domains.

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