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

[Matthias Bolte]

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(-)
>
> 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