[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