[libvirt] [libvirt-php] About the inconsistency in libvirt-php
Hi all: I noticed that there's some inconsistent behaviors in libvirt-php, and wondering what's the best way to handle them. In libvirt-php: libvirt_list_domains() returns an array of all domain resource; libvirt_list_active_domains() returns an array of running domain ids; libvirt_list_defined_domains() returns an array of defined domain names. and libvirt_list_storagepools() returns an array of actived storagepool names. In my opinion, returning an array of names would be better when listing all kinds of objects. And the naming convenances, let's take domains as an example. libvirt-php provied libvirt_list_domains() for all domains, which has no corresponding function in libvirt. libvirt_list_active_domains() for running domains, corresponding to virConnectListDomains() in libvirt. libvirt_list_defined_domains() for defined domains, corresponding to virConnectListDefinedDomains() in libvirt. I believe it is fine. However, for defined objects, sometimes it used term "defined" (libvirt_list_defined_domains), and sometimes use term "inactive" (libvirt_get_inactive_domain_count) in contrast to "active". Which would be better?
于 2011年02月21日 10:50, Lyre 写道:
Hi all:
I noticed that there's some inconsistent behaviors in libvirt-php, and wondering what's the best way to handle them.
In libvirt-php:
libvirt_list_domains() returns an array of all domain resource; libvirt_list_active_domains() returns an array of running domain ids; libvirt_list_defined_domains() returns an array of defined domain names.
and
libvirt_list_storagepools() returns an array of actived storagepool names.
In my opinion, returning an array of names would be better when listing all kinds of objects.
And the naming convenances, let's take domains as an example.
libvirt-php provied libvirt_list_domains() for all domains, which has no corresponding function in libvirt. libvirt_list_active_domains() for running domains, corresponding to virConnectListDomains() in libvirt. libvirt_list_defined_domains() for defined domains, corresponding to virConnectListDefinedDomains() in libvirt.
I believe it is fine. However, for defined objects, sometimes it used term "defined" (libvirt_list_defined_domains), and sometimes use term "inactive" (libvirt_get_inactive_domain_count) in contrast to "active". Which would be better?
Not sure if I get the meaning correctly, and also not sure what the exact meaning of "active" and "inactive" are in libvirt-php, but I guess: 1) "active" and "inactive" are about the domain state. 2) "defined" is about if it the domain has persistent config file on disk. So, if guessing 1) is right: A "defined" domain can be in either of "active" and "inactive" state; And an "active" domain can be "defined" or "not defined", and it's the same for "inactive" domain. Any conflict? Regards Osier
On Mon, Feb 21, 2011 at 1:23 PM, Osier Yang <jyang@redhat.com> wrote:
于 2011年02月21日 10:50, Lyre 写道:
Hi all:
I noticed that there's some inconsistent behaviors in libvirt-php, and wondering what's the best way to handle them.
In libvirt-php:
libvirt_list_domains() returns an array of all domain resource; libvirt_list_active_domains() returns an array of running domain ids; libvirt_list_defined_domains() returns an array of defined domain names.
and
libvirt_list_storagepools() returns an array of actived storagepool names.
In my opinion, returning an array of names would be better when listing all kinds of objects.
And the naming convenances, let's take domains as an example.
libvirt-php provied libvirt_list_domains() for all domains, which has no corresponding function in libvirt. libvirt_list_active_domains() for running domains, corresponding to virConnectListDomains() in libvirt. libvirt_list_defined_domains() for defined domains, corresponding to virConnectListDefinedDomains() in libvirt.
I believe it is fine. However, for defined objects, sometimes it used term "defined" (libvirt_list_defined_domains), and sometimes use term "inactive" (libvirt_get_inactive_domain_count) in contrast to "active". Which would be better?
Not sure if I get the meaning correctly, and also not sure what the exact meaning of "active" and "inactive" are in libvirt-php, but I guess:
1) "active" and "inactive" are about the domain state.
2) "defined" is about if it the domain has persistent config file on disk.
So, if guessing 1) is right:
A "defined" domain can be in either of "active" and "inactive" state; And an "active" domain can be "defined" or "not defined", and it's the same for "inactive" domain.
Any conflict?
Regards Osier
What about the "actived" & "defined" in libvirt? As far as I know, virConnectListDefinedDomains() will list domains which isn't running and has persistent config file on disk "defined" in libvirt-php should have same meaning with libvirt, since the implementation of libvirt_list_defined_domains() is just a wrapper of virConnectListDefinedDomains(), and libvirt_get_inactive_domain_count() is a wrapper of virConnectNumOfDefinedDomains().
于 2011年02月21日 13:44, Lyre 写道:
On Mon, Feb 21, 2011 at 1:23 PM, Osier Yang <jyang@redhat.com <mailto:jyang@redhat.com>> wrote:
于 2011年02月21日 10:50, Lyre 写道:
Hi all:
I noticed that there's some inconsistent behaviors in libvirt-php, and wondering what's the best way to handle them.
In libvirt-php:
libvirt_list_domains() returns an array of all domain resource; libvirt_list_active_domains() returns an array of running domain ids; libvirt_list_defined_domains() returns an array of defined domain names.
and
libvirt_list_storagepools() returns an array of actived storagepool names.
In my opinion, returning an array of names would be better when listing all kinds of objects.
And the naming convenances, let's take domains as an example.
libvirt-php provied libvirt_list_domains() for all domains, which has no corresponding function in libvirt. libvirt_list_active_domains() for running domains, corresponding to virConnectListDomains() in libvirt. libvirt_list_defined_domains() for defined domains, corresponding to virConnectListDefinedDomains() in libvirt.
I believe it is fine. However, for defined objects, sometimes it used term "defined" (libvirt_list_defined_domains), and sometimes use term "inactive" (libvirt_get_inactive_domain_count) in contrast to "active". Which would be better?
Not sure if I get the meaning correctly, and also not sure what the exact meaning of "active" and "inactive" are in libvirt-php, but I guess:
1) "active" and "inactive" are about the domain state.
2) "defined" is about if it the domain has persistent config file on disk.
So, if guessing 1) is right:
A "defined" domain can be in either of "active" and "inactive" state; And an "active" domain can be "defined" or "not defined", and it's the same for "inactive" domain.
Any conflict?
Regards Osier
What about the "actived" & "defined" in libvirt?
As far as I know, virConnectListDefinedDomains() will list domains which isn't running and has persistent config file on disk
Ah, yes, it is, understand you now, but I'm surpised, as "defined" is not related with if the domain is "active" or "inactive" indeed from view of libvirt design indeed.
"defined" in libvirt-php should have same meaning with libvirt, since the implementation of libvirt_list_defined_domains() is just a wrapper of virConnectListDefinedDomains(), and libvirt_get_inactive_domain_count() is a wrapper of virConnectNumOfDefinedDomains().
On 02/21/2011 03:50 AM, Lyre wrote:
Hi all:
I noticed that there's some inconsistent behaviors in libvirt-php, and wondering what's the best way to handle them.
In libvirt-php:
libvirt_list_domains() returns an array of all domain resource; libvirt_list_active_domains() returns an array of running domain ids; libvirt_list_defined_domains() returns an array of defined domain names.
and
libvirt_list_storagepools() returns an array of actived storagepool names.
In my opinion, returning an array of names would be better when listing all kinds of objects.
Well, good point Lyre. I guess we should be change it to something like: libvirt_list_domains() - return domain pointers for all domains libvirt_list_active_domains() - return pointers for active domains libvirt_list_defined_domains() - return pointers for inactive domains, also we should consider renaming it to list_inactive_domains() Also, I guess we should add a new function: libvirt_list_domain_names() - return names of all domains (both active and inactive) This should be applied to everything - networks, storage pools etc...
And the naming convenances, let's take domains as an example.
libvirt-php provied libvirt_list_domains() for all domains, which has no corresponding function in libvirt. libvirt_list_active_domains() for running domains, corresponding to virConnectListDomains() in libvirt. libvirt_list_defined_domains() for defined domains, corresponding to virConnectListDefinedDomains() in libvirt.
I believe it is fine. However, for defined objects, sometimes it used term "defined" (libvirt_list_defined_domains), and sometimes use term "inactive" (libvirt_get_inactive_domain_count) in contrast to "active". Which would be better?
For this one I guess we should use naming like "all", "active" and "inactive". Michal -- Michal Novotny<minovotn@redhat.com>, RHCE Virtualization Team (xen userspace), Red Hat
On 22/02/2011, at 12:32 AM, Michal Novotny wrote: <snip>
libvirt_list_defined_domains() - return pointers for inactive domains, also we should consider renaming it to list_inactive_domains()
Ouch, yeah that looks pretty non-optimal. Probably better to fix it now, rather than leave it completely wrong. :/ But... it'll need some kind of Big Warning about the problem, and the change, on the libvirt-php pages for the next release. (personal opinion) Probably something like this: WARNING: In previous releases of libvirt-php, the function libvirt_list_defined_domains() was returning the wrong kind of information. It *should* have been showing all persistent domains, both active and inactive. However it was instead showing just inactive domains. This has now been fixed, so all persistent domains are listed. If your PHP code relies on the incorrect behaviour however, you'll need to adjust it. Maybe with some details about the new libvirt_list_inactive_domains() function too? Heh, that's just my opinion anyway. :) Regards and best wishes, Justin Clift
Thanks for your reply Justin. We should definitely do something with that. I'll work on that after my shift finishes, maybe even tomorrow shift, since I need to concentrate on something else now. However we should document the naming conventions with functionality described. It should be written in some document as well. I'll take care of this. Michal On 02/21/2011 03:49 PM, Justin Clift wrote:
On 22/02/2011, at 12:32 AM, Michal Novotny wrote: <snip>
libvirt_list_defined_domains() - return pointers for inactive domains, also we should consider renaming it to list_inactive_domains() Ouch, yeah that looks pretty non-optimal. Probably better to fix it now, rather than leave it completely wrong. :/
But... it'll need some kind of Big Warning about the problem, and the change, on the libvirt-php pages for the next release. (personal opinion)
Probably something like this:
WARNING: In previous releases of libvirt-php, the function libvirt_list_defined_domains() was returning the wrong kind of information. It *should* have been showing all persistent domains, both active and inactive. However it was instead showing just inactive domains.
This has now been fixed, so all persistent domains are listed. If your PHP code relies on the incorrect behaviour however, you'll need to adjust it.
Maybe with some details about the new libvirt_list_inactive_domains() function too?
Heh, that's just my opinion anyway. :)
Regards and best wishes,
Justin Clift
-- Michal Novotny<minovotn@redhat.com>, RHCE Virtualization Team (xen userspace), Red Hat
WARNING: In previous releases of libvirt-php, the function libvirt_list_defined_domains() was returning the wrong kind of information. It *should* have been showing all persistent domains, both active and inactive. However it was instead showing just inactive domains.
Hi justin, Is there a way to list the "defined/persistent" domains in libvirt? virConenctListDefinedDomains() doesn't behavior like that. I'm really amazed, the behavior of "defined" in libvirt development guide seems to be equivalent to "inactive". But you guys told me there are different, it refer to the persistent domains.
On 02/22/2011 05:12 AM, Lyre wrote:
WARNING: In previous releases of libvirt-php, the function libvirt_list_defined_domains() was returning the wrong kind of information. It *should* have been showing all persistent domains, both active and inactive. However it was instead showing just inactive domains.
Hi justin, Is there a way to list the "defined/persistent" domains in libvirt? virConenctListDefinedDomains() doesn't behavior like that.
I'm really amazed, the behavior of "defined" in libvirt development guide seems to be equivalent to "inactive". But you guys told me there are different, it refer to the persistent domains.
From my understanding virConnectListActiveDomains() is listing all the active (running) domains and virConnectListDefinedDomains() is listing all the inactive domains that are defined since if we create a domain directly from XML, i.e. non-persistent, we have the domain in active domains list but it's not defined. Only inactive but defined domains are in the defined list AFAIK. If we have 2 domains created *directly* from XML file, 3 persistent domains active and 4 domains inactive (but defined) we should be getting number 5 from virConnectListActiveDomains() since 2 + 3. For defined (inactive) domains we should be getting number for and total number should be 2 + 3 + 4 = 9 domains. Michal -- Michal Novotny<minovotn@redhat.com>, RHCE Virtualization Team (xen userspace), Red Hat
From my understanding virConnectListActiveDomains() is listing all the active (running) domains and virConnectListDefinedDomains() is listing all the inactive domains that are defined since if we create a domain directly from XML, i.e. non-persistent, we have the domain in active domains list but it's not defined. Only inactive but defined domains are in the defined list AFAIK.
I can't find the function virConnectListActiveDomains(), did you mean virConnectListActiveDomains()? If we have 2 domains created *directly* from XML file, 3 persistent domains
active and 4 domains inactive (but defined) we should be getting number 5 from virConnectListActiveDomains() since 2 + 3. For defined (inactive) domains we should be getting number for and total number should be 2 + 3 + 4 = 9 domains.
Confused, do you missed some words? Shouldn't it be: 2 active but not defined 3 active but defined 4 inactive and defined 2 + 3 = 5 active 3 + 4 = 7 defined 2 + 3 + 4 = 9 total libvirt_list_domains() should gets 9; libvirt_list_active_domains() gets 5 libivrt_list_inactive_domains() gets 4? libvirt_list_defined_domains() (if there's such a function) gets 7?
On 02/22/2011 08:49 AM, Lyre wrote:
From my understanding virConnectListActiveDomains() is listing all the active (running) domains and virConnectListDefinedDomains() is listing all the inactive domains that are defined since if we create a domain directly from XML, i.e. non-persistent, we have the domain in active domains list but it's not defined. Only inactive but defined domains are in the defined list AFAIK.
I can't find the function virConnectListActiveDomains(), did you mean virConnectListActiveDomains()?
Oh, sorry. It's called virConnectListDomains() in libvirt: Collect the list of active domains, and store their ID in @maxids. So that's why I rewrote it to lookup domain by ID and get the domain name to add to the list. I did rewrite some codes there and also I'm thinking of adding comments there. This will be later used to generate API documentation for the site.
If we have 2 domains created *directly* from XML file, 3 persistent domains active and 4 domains inactive (but defined) we should be getting number 5 from virConnectListActiveDomains() since 2 + 3. For defined (inactive) domains we should be getting number for and total number should be 2 + 3 + 4 = 9 domains.
Confused, do you missed some words?
I apologize. I made a typo there since I meant "For defined (inactive) domains we should be getting number four (4)".
Shouldn't it be:
2 active but not defined 3 active but defined 4 inactive and defined 2 + 3 = 5 active 3 + 4 = 7 defined 2 + 3 + 4 = 9 total
Well, from what I know defined domains are those that are both defined and *not* active as written at [1]: "Provides the number of defined but inactive domains.". Please note "but inactive". So therefore defined is returns number 4. Michal [1] http://libvirt.org/html/libvirt-libvirt.html#virConnectNumOfDefinedDomains -- Michal Novotny<minovotn@redhat.com>, RHCE Virtualization Team (xen userspace), Red Hat
On Tue, Feb 22, 2011 at 12:12:03PM +0800, Lyre wrote:
WARNING: In previous releases of libvirt-php, the function libvirt_list_defined_domains() was returning the wrong kind of information. It *should* have been showing all persistent domains, both active and inactive. However it was instead showing just inactive domains.
Hi justin, Is there a way to list the "defined/persistent" domains in libvirt? virConenctListDefinedDomains() doesn't behavior like that.
I'm really amazed, the behavior of "defined" in libvirt development guide seems to be equivalent to "inactive".
There are two types of guest - Persistent: This has a config file on disk. It will appear either in the ListDefinedDomains or ListDomains, depending on whether it is currently running - Transient: This has *no* config on disk. It will only appear in ListDomains and will disappear completely when it is shutdown. Every inactive domain is thus a persistent domain. A running domain can be either transient or persistent. There is a virDomainIsPersistent() API to distinguish them. Daniel -- |: http://berrange.com -o- http://www.flickr.com/photos/dberrange/ :| |: http://libvirt.org -o- http://virt-manager.org :| |: http://autobuild.org -o- http://search.cpan.org/~danberr/ :| |: http://entangle-photo.org -o- http://live.gnome.org/gtk-vnc :|
On 02/22/2011 10:21 AM, Daniel P. Berrange wrote:
On Tue, Feb 22, 2011 at 12:12:03PM +0800, Lyre wrote:
WARNING: In previous releases of libvirt-php, the function libvirt_list_defined_domains() was returning the wrong kind of information. It *should* have been showing all persistent domains, both active and inactive. However it was instead showing just inactive domains.
Hi justin, Is there a way to list the "defined/persistent" domains in libvirt? virConenctListDefinedDomains() doesn't behavior like that.
I'm really amazed, the behavior of "defined" in libvirt development guide seems to be equivalent to "inactive". There are two types of guest
- Persistent: This has a config file on disk. It will appear either in the ListDefinedDomains or ListDomains, depending on whether it is currently running - Transient: This has *no* config on disk. It will only appear in ListDomains and will disappear completely when it is shutdown.
Every inactive domain is thus a persistent domain. A running domain can be either transient or persistent. There is a virDomainIsPersistent() API to distinguish them.
Daniel That's what I was thinking Daniel. Thanks for clarification. I didn't know about virDomainIsPersistent() API but it could be useful.
Thanks for your reply, Michal -- Michal Novotny<minovotn@redhat.com>, RHCE Virtualization Team (xen userspace), Red Hat
On 22/02/2011, at 8:21 PM, Daniel P. Berrange wrote: On Tue, Feb 22, 2011 at 12:12:03PM +0800, Lyre wrote: <snip>
I'm really amazed, the behavior of "defined" in libvirt development guide seems to be equivalent to "inactive".
There are two types of guest
- Persistent: This has a config file on disk. It will appear either in the ListDefinedDomains or ListDomains, depending on whether it is currently running - Transient: This has *no* config on disk. It will only appear in ListDomains and will disappear completely when it is shutdown.
Every inactive domain is thus a persistent domain. A running domain can be either transient or persistent. There is a virDomainIsPersistent() API to distinguish them.
This *might* be useful further reading info: http://wiki.libvirt.org/page/VM_lifecycle#Transient_guest_domains_vs_Persist...
participants (5)
-
Daniel P. Berrange -
Justin Clift -
Lyre -
Michal Novotny -
Osier Yang