Re: [libvirt] [PATCH] docs: fix docs to match behavior of virConnectClose
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(-)
diff --git a/src/libvirt.c b/src/libvirt.c
index c57e0c3..b9765b1 100644
--- a/src/libvirt.c
+++ b/src/libvirt.c
@@ -1295,7 +1295,12 @@ error:
* especially if there is running domain which need further monitoring by
* the application.
*
- * 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.
virConnectClose returning > 0 even when the virConnectOpen* and
virConnectRef calls are matched with virConnectClose calls might
confuse an application developer and giving him the impression that
libvirt doesn't behave as expected or having a bug. This can happen
when you try to close the connection before freeing the remaining
objects depending on it.
+ * Returns the number of remaining references (positive if the
connection
+ * remains open, 0 if closed) in case of success or -1 in case of error.
*/
int
virConnectClose(virConnectPtr conn)
--
1.7.4.4
--
Matthias Bolte
http://photron.blogspot.com