[libvirt] [PATCH] event: improve public API docs
Daniel P. Berrange
berrange at redhat.com
Tue Feb 4 10:23:22 UTC 2014
On Tue, Feb 04, 2014 at 10:07:58AM +0100, Claudio Bley wrote:
> 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...
Yes, it is basically saying that unless you have called it with a timer
id that is invalid, it is guaranteed to succeed to change the frequency.
Daniel
--
|: http://berrange.com -o- http://www.flickr.com/photos/dberrange/ :|
|: http://libvirt.org -o- http://virt-manager.org :|
|: http://autobuild.org -o- http://search.cpan.org/~danberr/ :|
|: http://entangle-photo.org -o- http://live.gnome.org/gtk-vnc :|
More information about the libvir-list
mailing list