[libvirt] [PATCH] docs: fix docs to match behavior of virConnectClose

[Matthias Bolte]

2011/6/22 Eric Blake <eblake at redhat.com>:
> On 06/22/2011 10:43 AM, Matthias Bolte wrote:
>> 2011/6/22 Eric Blake <eblake at redhat.com>:
>>> * src/libvirt.c (virConnectClose): Mention reference count return.
>>> Reported by Michal Novotny, analyzed by Matthias Bolte.
>>> ---
>>>  src/libvirt.c |    7 ++++++-
>>>  1 files changed, 6 insertions(+), 1 deletions(-)
>>>
>
>>> - * Returns 0 in case of success or -1 in case of error.
>>> + * Connections are reference counted; the connection is not actually
>>> + * closed until all calls to virConnectRef have had a matching
>>> + * virConnectClose call.
>>
>> Actually you need to match the virConnectOpen* call too. Interpreted
>> strictly it says that you only need to match the virConnectRef calls
>> which means that you don't have to call it when you didn't call
>> virConnectRef for a connection, doesn't it? Maybe just adding
>> appending a "too" to the sentence fixes this.
>>
>> The reference counting applies to vir(Domain|Network|...)Free too. But
>> this comment is missing that domain, network, etc objects that depend
>> on the connection take a reference on it too. So it's more complicated
>> than the comment implies. I'm not sure if we should explain this here.
>
> Hmm, good points.  How about:
>
> Connections are reference counted; the count is explicitly increased by
> virConnectRef and virConnectOpen, as well as temporarily increased by
> other API that depend on the connection remaining alive.  Every
> virConnectRef and virConnectOpen call should have a matching
> virConnectClose, and all other references will be released after the
> corresponding operation completes.

There is virConnectOpenReadOnly and virConnectOpenAuth too.

You're a bit vague about the "other API", but I think its better this
way than being too explicit and creating some kind of list that need
to be maintained here.

> The return value is the number of remaining references on success
> (positive implies that some other call still has a reference open, 0
> implies that no references remain and the connection is closed), or -1
> on failure.  It is possible for the last virConnectClose to return a
> positive value if some other object still has a temporary reference to
> the connection, but the application should not try to further use a
> connection after the virConnectClose that matches the virConnectOpen.

ACK.

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