[libvirt] virConnectClose() API function question

[Michal Novotny]

On 06/21/2011 05:53 PM, Matthias Bolte wrote:
> 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.
>
Thanks for the clarification Matthias. Now it makes sense to me ;-)

Thanks,
Michal

-- 
Michal Novotny <minovotn at redhat.com>, RHCE, Red Hat
Virtualization Team (xen userspace) | libvirt-php bindings