Back to libut API Reference


   #include "libut/ut.h"
   void UT_tmr_set(char *name, unsigned msec, UT_tmr_cb *cb, void *data);


This function creates a new timer with the given name which will expire in msec milliseconds. Upon expiration, the callback cb is invoked and the name, msec, and the opaque data argument are passed back to it.

The callback cb has this prototype: int (UT_tmr_cb)(char *name, unsigned msec, void *data);

The callback's return value specifies whether the timer should recur. It is either negative (to clear the timer), 0 (to recur in the same number of milliseconds), or positive (to recur in the number of milliseconds indicated by the return value itself).

The timer name is silently copied, and truncated if too long.

If a timer with the given name already exists when this function is called, it is deleted, and the new timer replaces it. In other words, a timer can be reset just by calling this function a second time.


The tmr control port command lists the pending (unexpired) timers.


Timers are not meant as a high-resolution mechanism. The delay between a timer's expiration and when its callback is invoked can increase if other I/O or timer callbacks are being serviced at that time.

Timer callbacks are one of the two main mechanisms by which libut-based servers do their work. (The other mechanism is I/O-driven callbacks, established using UT_fd_reg(3).) In this type of event-driven framework, callbacks should not run for too long before returning, otherwise servicing of other events may become delayed.




Troy D. Hanson <>