Documentation for qb_loop_timer_expire_time_get seems misleading

[cmurphycode]

When a timer is registered using timerlist_add_duration, the field expire_time is set to the current time plus a user-requested amount of time. That value is plainly returned by timerlist_expire_time.

The only caller of timerlist_expire_time is qb_loop_timer_expire_time_get.

The function documentation reads as follows:

libqb/include/qb/qbloop.h

Line 190 in b46a574

* Get the time remaining before it expires.

Which, to me, implies that the time value returned is not an absolute time, but rather the amount left in the user specified duration. That is, roughly, expire_time - current_time().

I would have filed this with a pull request to fix it, however, that would surely break any existing caller who has already worked around this. I noticed that currently, qb_loop_timer_expire_time_get is not used by anything in libqb* or corosync, but it is exposed by apidef_corosync_api_v1, so I'm guessing we don't want to change it.
NOTE: it is used by qb_loop_timer_is_running, but only the part of the behavior which returns 0 if it's expired, which we could keep.

Maybe the best thing to do is to fix the comment and then specify a new function?

Any thoughts are welcome. If it helps, I would be happy to contribute a patch with whichever direction you see fit.

Thank you!

[chrissie-c]

Thanks for pointing this out! I think it would be wrong to change the behaviour of the call as it stands - that would be an ABI change. So I think what needs to be done is to fix the documentation and optionally add a new call to do it properly. As I'm slowly building up to a 2.0 release (don't hold your breath) now is a good time to add that new call if you want :)

[chrissie-c]

Closing this as it was merged in #391