[libvirt] [PATCH] event: improve public API docs

[Martin Kletzander]

On Wed, Jan 01, 2014 at 03:54:14PM -0700, Eric Blake wrote:
> On 12/31/2013 08:21 AM, Eric Blake wrote:
> > Since libvirt 0.9.3, the entire virevent.c file has been a public
> > API, so improve the documentation in this file.  Also, fix a
> > potential core dump - it could only be triggered by bogus use of
> > the API and would only affect the caller (not libvirtd), but we
> > might as well be nice.
> > 
> > * src/libvirt.c (virConnectDomainEventRegister)
> > (virConnectDomainEventRegisterAny)
> > (virConnectNetworkEventRegisterAny): Document event loop requirement.
> > * src/util/virevent.c (virEventAddHandle, virEventRemoveHandle)
> > (virEventAddTimeout, virEventRemoveTimeout): Likewise.
> > (virEventUpdateHandle, virEventUpdateTimeout): Likewise, and avoid
> > core dump if caller didn't register handler.
> > (virEventRunDefaultImpl): Expand example, and set up code block in
> > html docs.
> > (virEventRegisterImpl, virEventRegisterDefaultImpl): Document more
> > on the use of the event loop.
> > 
> > Signed-off-by: Eric Blake <eblake at redhat.com>
> > ---
> >  src/libvirt.c       | 24 ++++++++++------
> >  src/util/virevent.c | 82 +++++++++++++++++++++++++++++++++++------------------
> >  2 files changed, 70 insertions(+), 36 deletions(-)
> 
> I plan on squashing this in, too.
> 
> diff --git i/src/libvirt.c w/src/libvirt.c
> index 0752c3f..753c71f 100644
> --- i/src/libvirt.c
> +++ w/src/libvirt.c
> @@ -2,7 +2,7 @@
>   * libvirt.c: Main interfaces for the libvirt library to handle
> virtualization
>   *           domains from a process running in domain 0
>   *
> - * Copyright (C) 2005-2006, 2008-2013 Red Hat, Inc.
> + * Copyright (C) 2005-2006, 2008-2014 Red Hat, Inc.
>   *
>   * This library is free software; you can redistribute it and/or
>   * modify it under the terms of the GNU Lesser General Public
> @@ -21454,17 +21454,18 @@ error:
>   * @interval: number of seconds of inactivity before a keepalive
> message is sent
>   * @count: number of messages that can be sent in a row
>   *
> - * Start sending keepalive messages after interval second of inactivity and
> + * Start sending keepalive messages after @interval seconds of
> inactivity and
>   * consider the connection to be broken when no response is received after
> - * count keepalive messages sent in a row.  In other words, sending
> count + 1
> - * keepalive message results in closing the connection.  When interval
> is <= 0,
> - * no keepalive messages will be sent.  When count is 0, the connection
> will be
> - * automatically closed after interval seconds of inactivity without
> sending
> - * any keepalive messages.
> - *
> - * Note: client has to implement and run event loop to be able to use
> keepalive
> - * messages.  Failure to do so may result in connections being closed
> - * unexpectedly.
> + * @count keepalive messages sent in a row.  In other words, sending
> count + 1
> + * keepalive message results in closing the connection.  When @interval is
> + * <= 0, no keepalive messages will be sent.  When @count is 0, the
> connection
> + * will be automatically closed after interval seconds of inactivity
> without

s/interval/@interval/

This fixup came through word-wrapped.  Check your e-mail client
settings when pasting patches ;)

ACK to squash it in the previous patch.

Martin
-------------- next part --------------
A non-text attachment was scrubbed...
Name: signature.asc
Type: application/pgp-signature
Size: 836 bytes
Desc: Digital signature
URL: <http://listman.redhat.com/archives/libvir-list/attachments/20140102/abb4b129/attachment-0001.sig>