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

[Eric Blake]

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
+ * 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

-------------- next part --------------
A non-text attachment was scrubbed...
Name: signature.asc
Type: application/pgp-signature
Size: 604 bytes
Desc: OpenPGP digital signature
URL: <http://listman.redhat.com/archives/libvir-list/attachments/20140101/f10fc238/attachment-0001.sig>