Re: [libvirt] [PATCH] docs: fix docs to match behavior of virConnectClose
On 06/22/2011 10:43 AM, Matthias Bolte wrote:
2011/6/22 Eric Blake <eblake(a)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(a)redhat.com +1-801-349-2682
Libvirt virtualization library http://libvirt.org
Attachments:
- signature.asc (application/pgp-signature — 619 bytes)