[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