Commit ec1c0c11 authored by Pekka Pessi's avatar Pekka Pessi

su/su_timer.c: updated documentation.

darcs-hash:20060724180444-65a35-2668bc51945d15dbc1b70ee4a8d0eb6a2728f694.gz
parent 8af5a3ef
......@@ -59,9 +59,11 @@
* as follows:
* - su_timer_create(),
* - su_timer_destroy(),
* - su_timer_set_interval(),
* - su_timer_set_at(),
* - su_timer_set(),
* - su_timer_set_for_ever(),
* - su_timer_run(),
* - su_timer_set_at(),
* - su_timer_reset(), and
* - su_timer_root().
*
......@@ -87,25 +89,29 @@
* The default duration is given in milliseconds.
*
* Usually, timer wakeup function should be called at regular intervals. In
* such case, the timer is activated using function su_timer_run(). When the
* timer is run it is given the wakeup function and pointer to context
* data:
* such case, the timer is activated using function su_timer_set_for_ever().
* When the timer is activated it is given the wakeup function and pointer to
* context data:
* @code
* su_timer_run(timer, timer_wakeup, args);
* su_timer_set_for_ever(timer, timer_wakeup, args);
* @endcode
*
* When run, the timer invokes the wakeup function approximately at the
* intervals of the default duration given in su_timer_create(). When the
* interval has passed, the root event loop calls the wakeup function:
* When the interval has passed, the root event loop calls the wakeup
* function:
* @code
* timer_wakeup(root, timer, args);
* @endcode
*
* Timer ceases running when su_timer_reset() is called.
* If the number of calls to callback function is important, use
* su_timer_run() instead. The run timer tries to compensate for missed time
* and invokes the callback function several times if needed. (Because the
* real-time clock can be adjusted or the program suspended, e.g., while
* debugged, the callback function can be called thousends of times in a
* row.) Note that while the timer tries to compensate for delays occurred
* before and during the callback, it cannot be used as an exact source of
* timing information.
*
* @note While the timer tries to compensate for delays occurred before and
* during the callback, it cannot be used as an exact source of timing
* information.
* Timer ceases running when su_timer_reset() is called.
*
* Alternatively, the timer can be @b set for one-time event invocation.
* When the timer is set, it is given the wakeup function and pointer to
......@@ -269,11 +275,9 @@ void su_timer_destroy(su_timer_t *t)
}
}
/** Set the timer for the default interval.
*
* Sets (starts) the given timer to expire after the default duration.
/** Set the timer for the given @a interval.
*
* The timer must have an default duration.
* Sets (starts) the given timer to expire after the specified duration.
*
* @param t pointer to the timer object
* @param wakeup pointer to the wakeup function
......@@ -506,7 +510,7 @@ int su_timer_reset(su_timer_t *t)
* the next timer expires.
*
* @param timers pointer to the timer queue
* @param timeout timeout in milliseconds [IN/OU]
* @param timeout timeout in milliseconds [IN/OUT]
* @param now current timestamp
*
* @return
......
Markdown is supported
0% or
You are about to add 0 people to the discussion. Proceed with caution.
Finish editing this message first!
Please register or to comment