[libvirt] [PATCH] docs: fix docs to match behavior of virConnectClose
Matthias Bolte
matthias.bolte at googlemail.com
Wed Jun 22 16:43:33 UTC 2011
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
More information about the libvir-list
mailing list