Repository files navigation

Tick-based timer implemented using the hierarchical timing wheel algorithm.It has amortised O(1) time complexity for all operations (start/stop/tick).The implementation is written in C99 and distributed under the 2-clause BSDlicense.

Reference:

G. Varghese, A. Lauck, Hashed and hierarchical timing wheels:efficient data structures for implementing a timer facility,IEEE/ACM Transactions on Networking, Vol. 5, No. 6, Dec 1997http://www.cs.columbia.edu/~nahum/w6998/papers/ton97-timing-wheels.pdf

• ttimer_t *ttimer_create(time_t maxtimeout, time_t now)

  • Construct a new timer object. Themaxtimeout parameter specifies themaximum timeout value which can be used with this timer. Zero should beused if there is no limit. However, tuning this value to be as small aspossible would allow the implementation to be more efficient. Thenowparameter indicates the initial time value, e.g.time(NULL). Returnsthe timer object on success andNULL on failure.

• void ttimer_destroy(ttimer_t *timer)

  • Destroy the timer object.

• void ttimer_setfunc(ttimer_ref_t *entry, ttimer_func_t handler, void *arg)

  • Setup the timer entry and set a handler function with an arbitraryargument. This function will be called on timeout event. The timer entrystructurettimer_ref_t is typically embedded in the object associatedwith the timer event. It must be treated as an opaque structure.
  • This function should only be called when the timer entry is notactivated i.e. before invoking thettimer_start().

• void ttimer_start(ttimer_t *timer, ttimer_ref_t *entry, time_t timeout)

  • Start the timer for a given entry with a specifiedtimeout value.The handler function must be set withttimer_setfunc before activatingthe timer for given entry.

• bool ttimer_stop(ttimer_t *timer, ttimer_ref_t *enttry)

  • Stop the timer for the given timer entry. It may also be called ifthe timer was not activated. Returnstrue if the entry was activate(i.e.ttimer_start() was invoked) andfalse otherwise.
  • Stopping the timer will not reset the handler function set up by thettimer_setfunc() call. However, after the stop, the handler functionmay be changed if needed.

• void ttimer_run_ticks(ttimer_t *timer, time_t now)

  • Process all expired events and advance the "current time" up to thenew time, specified by thenow parameter. Note that the processingincludes any previously missed ticks since the last run. This is themain "tick" operation which shall occur periodically.

The timeout values would typically represent seconds. However, othertime units can be used with the API as long as they can be represented bythetime_t type. Internally, the mechanism does not assume UNIX time.

This is a tick-based mechanism and the accuracy, as well as the granularity,depends on the tick period. Depending on the use case, for an optimaltick rate, you might want to consider using theNyquist frequency.