2011/6/22 Eric Blake <eblake@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