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&gt;: >> * 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.