Re: [libvirt] [PATCH] event: improve public API docs
At Tue, 31 Dec 2013 08:21:29 -0700,
Eric Blake wrote:
@@ -132,17 +151,20 @@ virEventAddTimeout(int timeout,
* @timer: timer id to change
* @timeout: time between events in milliseconds
*
- * Change frequency for a timer.
+ * Change frequency for a timer. This function
+ * requires that an event loop has previously been registered with
+ * virEventRegisterImpl() or virEventRegisterDefaultImpl().
*
* Setting frequency to -1 will disable the timer. Setting the frequency
* to zero will cause it to fire on every event loop iteration.
*
- * Will not fail if timer exists
+ * Will not fail if timer exists.
*/
void
virEventUpdateTimeout(int timer, int timeout)
{
I just stumbled over the last sentence in this function's documentation.
What exactly is this meant to tell me? On first thought I figured this
to be a typo, actually meaning "it will not fail if timer does not
exist" (ie. just ignore the change request)?
Or, is it just to assure that the function will work (ie. change the
frequency of the timer) in any circumstances iff only the timer exists
in the first place?
But, then again, the function cannot fail since its return type is
void. So, I'd assume that the function will just always work anyway...
The same question arises for the virEventUpdateHandle function:
- * Will not fail if fd exists
+ * Will not fail if fd exists.
*/
void
virEventUpdateHandle(int watch, int events)
TIA
Claudio