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

On 12/31/2013 08:21 AM, Eric Blake wrote: 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 + * sending any keepalive messages. + * + * Note: The client has to implement and run an event loop with + * virEventRegisterImpl() or virEventRegisterDefaultImpl() to be able to + * use keepalive messages. Failure to do so may result in connections + * being closed unexpectedly. * * Note: This API function controls only keepalive messages sent by the client. * If the server is configured to use keepalive you still need to run the event diff --git i/src/util/virevent.c w/src/util/virevent.c index 0c94946..f3cebe0 100644 --- i/src/util/virevent.c +++ w/src/util/virevent.c @@ -1,7 +1,7 @@ /* * virevent.c: event loop for monitoring file handles * - * Copyright (C) 2007, 2011, 2013 Red Hat, Inc. + * Copyright (C) 2007, 2011, 2013-2014 Red Hat, Inc. * Copyright (C) 2007 Daniel P. Berrange * * This library is free software; you can redistribute it and/or @@ -205,7 +205,11 @@ virEventRemoveTimeout(int timer) * Use of the virEventAddHandle() and similar APIs require that the * corresponding handler be registered. Use of the * virConnectDomainEventRegisterAny() and similar APIs requires that - * the three timeout handlers be registered. + * the three timeout handlers be registered. Likewise, the three + * timeout handlers must be registered if the remote server has been + * configured to send keepalive messages, or if the client intends + * to call virConnectSetKeepAlive(), to avoid either side from + * unexpectedly closing the connection due to inactivity. * * If an application does not need to integrate with an * existing event loop implementation, then the -- Eric Blake eblake redhat com +1-919-301-3266 Libvirt virtualization library http://libvirt.org