[libvirt] virConnectClose() API function question

[Matthias Bolte]

2011/6/21 Michal Novotny <minovotn at redhat.com>:
> Hi,
> as I've been working on libvirt-php I've been able to see that sometimes
> the virConnectClose() API function is returning the undefined value,
> like in this example:
>
> [2011-06-21 17:29:59 libvirt-php/core]: libvirt_domain_get_info:
> virDomainGetInfo(0xb3184158) returned 0
> [2011-06-21 17:29:59 libvirt-php/core]: Freeing libvirt domain resource
> at 0x3d9751b3184158
> [2011-06-21 17:29:59 libvirt-php/core]: free_resource:
> virDomainFree(0xb3184158) completed successfully
> [2011-06-21 17:29:59 libvirt-php/core]: php_libvirt_connection_dtor:
> virConnectClose(0xb3382588) returned 1 ((null))
> [2011-06-21 17:29:59 libvirt-php/core]: check_resource_allocation:
> libvirt domain resource (conn 0xb3184158) is not allocated
>
> In the API reference of libvirt there's an information that it returns 0
> or -1 ("0 in case of success or -1 in case of error" as can be seen at
> [1]) however according to my libvirt-php tests with the debug log
> enabled there's a return value of 1 with the error string (as caught by
> libvirt error handler) undefined, i.e. NULL.
>
> Does anybody have an idea what may be wrong and why is libvirt sometimes
> returning undefined value for this function?
>
> Thanks,
> Michal
>
> [1] http://libvirt.org/html/libvirt-libvirt.html#virConnectClose
>

In contrast to the documentation virConnectClose returns the remaining
reference count of the connection after unref'ing it. This means
virConnectClose returns -1 on error and returns 0 when there is no
reference left and the connection is really closed. When it returns >
0 then the connection isn't closed yet, but is kept open because there
are still objects alive that depend on it. For example when you open a
connection and get a virDomainPtr from it then the refcount of the
connection is increased, because the domain object depends on it. When
the domain object is freed then the refcount of the connection is
decreased again.

All objects in libvirt like connections, domains, networks etc are
reference counted. But in contrast to virConnectClose other free
functions like virDomainFree don't return the remaining reference
count, they really just return -1 or 0. So the question is: do we
change virConnectClose to really just return -1 or 0, or do we update
the documentation, because someone might depend on virConnectClose
allowing to detect via its return value whether the connection was
really closed or not.

-- 
Matthias Bolte
http://photron.blogspot.com