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

Daniel P. Berrange berrange at redhat.com
Tue Feb 4 15:36:23 UTC 2014


On Tue, Feb 04, 2014 at 04:32:10PM +0100, Claudio Bley wrote:
> At Tue, 4 Feb 2014 10:23:22 +0000,
> Daniel P. Berrange wrote:
> > 
> > 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.
> 
> Thank you, that clears it up.
> 
> Would it make sense to reword or even remove that sentence? Because it
> implies that it will fail when the timer does NOT exist?

Sure, patches welcome :-)

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