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

[Eric Blake]

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.

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.

-- 
Eric Blake   eblake at redhat.com    +1-801-349-2682
Libvirt virtualization library http://libvirt.org

-------------- next part --------------
A non-text attachment was scrubbed...
Name: signature.asc
Type: application/pgp-signature
Size: 619 bytes
Desc: OpenPGP digital signature
URL: <http://listman.redhat.com/archives/libvir-list/attachments/20110622/a6236189/attachment-0001.sig>