Jiri
Kuthan
FhG FOKUS

    		    jiri@iptel.org

2003
FhG FOKUS
$Revision: 1.3 $
$Date: 2005/08/24 22:26:20 $

# TM Module

## Overview

TM module enables stateful processing of SIP transactions. The main use of stateful logic, which is costly in terms of memory and CPU, is some services inherently need state. For example, transaction-based accounting (module acc) needs to process transaction state as opposed to individual messages, and any kinds of forking must be implemented statefully. Other use of stateful processing is it trading CPU caused by retransmission processing for memory. That makes however only sense if CPU consumption per request is huge. For example, if you want to avoid costly DNS resolution for every retransmission of a request to an unresolvable destination, use stateful mode. Then, only the initial message burdens server by DNS queries, subsequent retransmissions will be dropped and will not result in more processes blocked by DNS resolution. The price is more memory consumption and higher processing latency.

From user's perspective, there are these major functions : t_relay, t_relay_to_udp and t_relay_to_tcp. All of them setup transaction state, absorb retransmissions from upstream, generate downstream retransmissions and correlate replies to requests. t_relay forwards to current URI (be it original request's URI or a URI changed by some of URI-modifying functions, such as sethost). t_relay_to_udp and t_relay_to_tcp forward to a specific address over UDP or TCP respectively.

In general, if TM is used, it copies clones of received SIP messages in shared memory. That costs the memory and also CPU time (memcpys, lookups, shmem locks, etc.) Note that non-TM functions operate over the received message in private memory, that means that any core operations will have no effect on statefully processed messages after creating the transactional state. For example, calling record_route after t_relay is pretty useless, as the RR is added to privately held message whereas its TM clone is being forwarded.

TM is quite big and uneasy to program--lot of mutexes, shared memory access, malloc and free, timers--you really need to be careful when you do anything. To simplify TM programming, there is the instrument of callbacks. The callback mechanisms allow programmers to register their functions to specific event. See t_hooks.h for a list of possible events.

Other things programmers may want to know is UAC--it is a very simplistic code which allows you to generate your own transactions. Particularly useful for things like NOTIFYs or IM gateways. The UAC takes care of all the transaction machinery: retransmissions , FR timeouts, forking, etc. See t_uac prototype in uac.h for more details. Who wants to see the transaction result may register for a callback.

## Known Issues

- We don't have authentication merging on forking.

- Local ACK/CANCELs copy'n'pastes Route and ignores deleted Routes.

- 6xx should be delayed.

- Possibly, performance could be improved by not parsing non-INVITEs, as they do not be replied with 100, and do not result in ACK/CANCELs, and other things which take parsing. However, we need to rethink whether we don't need parsed headers later for something else. Remember, when we now conserver a request in sh_mem, we can't apply any pkg_mem operations to it any more. (that might be redesigned too).

- Another performance improvement may be achieved by not parsing CSeq in replies until reply branch matches branch of an INVITE/CANCEL in transaction table.

- `t_replicate` should be done more cleanly--Vias, Routes, etc. should be removed from a message prior to replicating it (well, does not matter any longer so much as there is a new replication module).

- SNMP support (as nobody cares about SNMP, in particular for TM, I will drop this item soon).