[libvirt] virConnectClose() API function question

Michal Novotny minovotn at redhat.com
Wed Jun 22 16:07:54 UTC 2011


On 06/22/2011 05:57 PM, Daniel P. Berrange wrote:
> On Wed, Jun 22, 2011 at 04:48:31PM +0100, Daniel P. Berrange wrote:
>> On Wed, Jun 22, 2011 at 09:41:57AM -0600, Eric Blake wrote:
>>> On 06/21/2011 09:53 AM, Matthias Bolte wrote:
>>>>> [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.
>>> At this point, I worry that changing return values might break existing
>>> code, so I would favor a documentation update, but I'd also like to hear
>>> an opinion from DV or danpb.
>> I think we shouldn't change the semantics.
> Just to clarify: The code is right. The docs are wrong.
>
> This is actually a good general rule for resolving any doubts :-)
>
> Daniel
Well, it makes perfect sense to update docs and let user know that there
are some resources allocated that has to be freed prior to freeing the
connection object so I'm +1 for updating the docs instead ;-)

Michal

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




More information about the libvir-list mailing list