Timer_q documentation -- functions

Functions to add/delete base objects

This function is used to create and add a new (Timer_q_base) object to the list of known (Timer_q_base) objects.

If you add the (Timer_q_base) with the _MOVE_WHEN_EMPTY flag then the base will be added to the empty list, so to get maximum performance when you are going to add a (Timer_q_node) imediatlely you want to create the (Timer_q_base) without the _MOVE_WHEN_EMPTY flag and then add the node, and then add the flag to the base.

It's worth pointing out that the nodes are sorted in time order within the base list, so you might want to specify _INSERT_FROM_END depending on the timestamps of nodes you will be adding.

This functions is used to add a new (Timer_q_base) object that you have previuosly allocated yourself to the list of known (Timer_q_base) objects.

When you call *_del_base(), if Parameter[1] is used, the object will not be destoryed. This allows you to statically allocate objects, or allocate them as members of a larger object.

If you have enabled debugging in the library then you'll need to initialise the base with TIMER_Q_DEBUG_INIT_BASE;

The function deletes a (Timer_q_base) object to be from the list of known base objects and if applicable destroyes it. It will also always destroy all of the (Timer_q_node)s accociated with the base.

This function _cannot_ be called from a timer node call back. If it is then the library may crash. See timer_q_quick_del_base().

The function marks a (Timer_q_base) object to be deleted from the list of known base objects and if applicable to be destroyed. When the base is deleted from the list of known base objects all the nodes accociated with it will also be deleted.

The function doesn't delete the (Timer_q_base) object immediatlely, this allows this function can be called inside a (Timer_q_node) call back where it isn't safe to delete (Timer_q_base) objects immediately. When the object is eventually deleted...

     timer_q_cntl_base(base, ... _GET_FLAG_HAVE_DELETED ... );

Functions to add/delete node objects

This function allocates and adds a (Timer_q_node) to the base (Parameter[1]).

The node is initialised with the call back data as Parameter[2] and the time as a copy of Parameter[3].

If you do not specify one of _SINGLE, _DOUBLE or _FUNC then the default will be taken from the base. If you do specify a type then that type will be created.

If you specify _SINGLE and _DOUBLE then the _SINGLE will be ignored.

It's worth pointing out that the nodes are sorted in time order within the base list.

This function adds a (Timer_q_node) (Parameter[1]) to the base (Parameter[2]).

The node is initialised with the call back data as Parameter[2] and the time as Parameter[3].

If you allocate a (Timer_q_node) and pass the flags to use a (Timer_q_double_node) then the library will not know that the object you passed in Parameter[1] wasn't correct and so will probably crash. Always pass the correct flags or just use timer_q_add_node().

Also if you don't pass one of _SINGLE, _DOUBLE or _FUNC then the function will not use the passed argument as act just like timer_q_add_node(). This is a saftey measure to help the first note not happen.

When you call *_del_node(), if Parameter[1] is used, the object will not be destoryed. This allows you to statically allocate objects, or allocate them as members of a larger object.

If you have enabled debugging in the library then you'll need to initialise the node with one of the TIMER_Q_DEBUG_INIT_NODE constants.

This function will delete the node (Parameter[2]) from the base (Parameter[1]), and will also destory the node, if applicable, after calling the call back with the _DEL argument.

It is assumed that Parameter[2] is in the base you supply as Parameter[1] if this is not the case the library may crash.

This function will mark the node (Parameter[1]) to be removed, and if applicable, to be destroyed. The call back will be called just before the removal is done.

This function is faster than timer_q_del_node() in some cases.

The function doesn't delete the (Timer_q_node) object immediatlely.

This function will mark the node (Parameter[2]) to be removed, and if applicable, to be destroyed. The call back will be called just before the removal is done. The base (Parameter[1]) should be the base that the node has been added to.

This MACRO will run timer_q_del_node() in when the library has debugging enabled and timer_q_quick_del_node() at other times.

This function trys to find the (Timer_q_node) accociated with the node call back data (Parameter[2]) in the base (Parameter[1]). If it finds a node it will delete it from the base (Parameter[2]) and call the call back with _DEL.

This is semantically equivilant to...

     if ((node = timer_q_find_data(base, data)))
       timer_q_del_node(base, node);

     if ((node = timer_q_find_data(base, data)))
       timer_q_quick_del_node(node);

Functions for finding objects

This function trys to find the (Timer_q_node) accociated with the node call back data (Parameter[2]) in the base (Parameter[1]).

If a node is not found NULL is returned and nothing bad happens.

Functions for running the timer q

This function runs the call backs for all nodes that have a timestamp less than or equal to the timestamp (Parameter[1]). The type is equal to _RUN_NORM.

After a call to the call back the (Timer_q_node) is removed from the base it belonged to and if applicable is destroyed.

This function runs the call backs for all nodes that are in a base with the _RUN_ALL flag set. The type is equal to _RUN_ALL.

After a call to the call back the (Timer_q_node) is _not_ removed from the base it belonged to and hence is not destroyed. If timer_q_run_norm() is called after this function, with a timestamp greater than or equal to the timestamp of a (Timer_q_node), then the (Timer_q_node) call back will get called twice.

The idea is that you can call this if you have to shutdown, and timed jobs like saving data etc. will get done.

This function returns the lowest timestamp of any of the (Timer_q_nodes) in any one of the (Timer_q_base), this allows you to find out how long it will be before _at least one_ of the (Timer_q_nodes) will "go off".

This function will sometimes have to look through every base that is in the list of bases. However when timer_q_run_norm() is called it will return immediatelty, as long as you haven't deleted a node in the mean time.

If you call timer_q_first_tv() twice, without calling anything else in between, the second call will return the same value without having to do any work.

Functions for normalising timestamps and adding time to them

This function normalises a struct timeval, Ie. the tv_usec member will never be > 1_000_000 after a call to this function.

This function is should rarely be called explicitly.

This function adds the seconds (Parameter[2]) and micro seconds (Parameter[3]) onto the timestamp (Parameter[1]).

This function automatically normalises the timestamp (Parameter[1]) before it returns.

This function adds the minutes (Parameter[2]) and micro seconds (Parameter[3]) onto the timestamp (Parameter[1]).

This function automatically normalises the timestamp (Parameter[1]) before it returns.

This function adds the hours (Parameter[2]) and micro seconds (Parameter[3]) onto the timestamp (Parameter[1]).

This function automatically normalises the timestamp (Parameter[1]) before it returns.

This function adds the days (Parameter[2]) and micro seconds (Parameter[3]) onto the timestamp (Parameter[1]).

This function automatically normalises the timestamp (Parameter[1]) before it returns.

Functions for comparing/diffing timestamps

This function is the equivilant of...

   strcmp(Parameter[1], Parameter[2])

   Parameter[1] - Parameter[2]

Both arguments are expected to be normalised. If this could be the case then you need to call TIMER_Q_TIMEVAL_NORM().

This function returns the difference in microseconds between the 2 timestamps. The return value is how you would expect Parameter[1] - Parameter[2] to work.

If the difference in time is >= LONG_MAX then LONG_MAX will be returned, likewise for LONG_MIN.

This function returns how much bigger the first timestamp (Parameter[1]) is over the second timestamp (Parameter[2]), in microseconds.

If the difference in time is negative then 0 is returned.

This function returns the difference in milliseconds between the 2 timestamps. The return value is how you would expect Parameter[1] - Parameter[2] to work.

If the difference in time is >= LONG_MAX then LONG_MAX will be returned, likewise for LONG_MIN.

This function returns how much bigger the first timestamp (Parameter[1]) is over the second timestamp (Parameter[2]), in milliseconds.

If the difference in time is negative then 0 is returned.

This function returns the difference in seconds between the 2 timestamps. The return value is how you would expect Parameter[1] - Parameter[2] to work.

If the difference in time is >= LONG_MAX then LONG_MAX will be returned, likewise for LONG_MIN.

This function returns how much bigger the first timestamp (Parameter[1]) is over the second timestamp (Parameter[2]), in seconds.

If the difference in time is negative then 0 is returned.

Functions for miscellaneous control of options

See the TIMER_Q_CNTL_OPT_ macros for options.

This function isn't needed for simple uses of timer_q.

See the TIMER_Q_CNTL_NODE_ macros for options.

This function isn't needed for simple uses of timer_q.

See the TIMER_Q_CNTL_BASE_ macros for options.

This function isn't needed for simple uses of timer_q.