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

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(a)redhat.com&gt; > --- > 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