modules/tm/timer.h File Reference

TM :: timer support. More...

#include "defs.h"
#include "../../compiler_opt.h"
#include "lock.h"
#include "../../timer.h"
#include "h_table.h"
#include "config.h"

Include dependency graph for modules/tm/timer.h:

This graph shows which files directly or indirectly include this file:

Go to the source code of this file.

Defines

• #define TM_FAST_RETR_TIMER

  try to do fast retransmissions (but fall back to slow timer for FR
  

Functions

• int timer_fixup (void *handle, str *gname, str *name, void **val)

  Fixup function for the timer values.
  

• int timer_fixup_ms (void *handle, str *gname, str *name, void **val)

  fixup function for timer values that are kept in ms.
  

• int tm_init_timers (void)

  fix timer values to ticks
  

---

Detailed Description

TM timer support. It has been designed for high performance using some techniques of which timer users need to be aware.

• One technique is "fixed-timer-length". We maintain separate timer lists, all of them include elements of the same time to fire. That allows *appending* new events to the list as opposed to inserting them by time, which is costly due to searching time spent in a mutex. The performance benefit is noticeable. The limitation is you need a new timer list for each new timer length.
• Another technique is the timer process slices off expired elements from the list in a mutex, but executes the timer after the mutex is left. That saves time greatly as whichever process wants to add/remove a timer, it does not have to wait until the current list is processed. However, be aware the timers may hit in a delayed manner; you have no guarantee in your process that after resetting a timer, it will no more hit. It might have been removed by timer process, and is waiting to be executed.

The following example shows it:

PROCESS1 TIMER PROCESS

• 0. timer hits, it is removed from queue and about to be executed
• 1. process1 decides to reset the timer
• 2. timer is executed now
• 3. if the process1 naively thinks the timer could not have been executed after resetting the timer, it is WRONG -- it was (step 2.)

So be careful when writing the timer handlers. Currently defined timers don't hurt if they hit delayed, I hope at least. Retransmission timer may results in a useless retransmission -- not too bad. FR timer not too bad either as timer processing uses a REPLY mutex making it safe to other processing affecting transaction state. Wait timer not bad either -- processes putting a transaction on wait don't do anything with it anymore.

Example when it does not hurt:

PROCESS1 TIMER PROCESS

• 0. RETR timer removed from list and scheduled for execution
• 1. 200/BYE received-> reset RETR, put_on_wait
• 2. RETR timer executed -- too late but it does not hurt
• 3. WAIT handler executed

The rule of thumb is don't touch data you put under a timer. Create data, put them under a timer, and let them live until they are safely destroyed from wait/delete timer. The only safe place to manipulate the data is from timer process in which delayed timers cannot hit (all timers are processed sequentially).

A "bad example" -- rewriting content of retransmission buffer in an unprotected way is bad because a delayed retransmission timer might hit. Thats why our reply retransmission procedure is enclosed in a REPLY_LOCK.

Definition in file modules/tm/timer.h.

---

Function Documentation

int timer_fixup	(	void *	handle,
		str *	gname,
		str *	name,
		void **	val
	)

Fixup function for the timer values, (called by the configuration framework)

Parameters:

	handle	not used
	gname	not used
	name	not used
	val	fixed timer value

Returns:

0 on success, -1 on error

Definition at line 255 of file modules/tm/timer.c.

References IF_IS_TIMER_NAME, and MS_TO_TICKS.

int timer_fixup_ms	(	void *	handle,
		str *	gname,
		str *	name,
		void **	val
	)

(called by the configuration framework) It checks if the value fits in the tm structures

Definition at line 282 of file modules/tm/timer.c.

References IF_IS_TIMER_NAME.