# TM Module

## Admin Guide

### Overview

The TM module enables stateful processing of SIP transactions. Stateful logic is costly in terms of memory and CPU. The main use is services that inherently need state. For example, transaction-based accounting (module acc) needs to process transaction state as opposed to individual messages. Any kind of forking must be implemented transaction statefully. By using transaction states you trade CPU caused by retransmission processing for memory. That only makes 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 the admin's perspective, these are the major functions : t_relay, t_relay_to_udp and t_relay_to_tcp. All of them set up 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 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.

The TM module is quite big and uneasy to program --lots 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 a 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. If you want to see the transaction result the code can register for a callback.

Several Kamailio TM module functions are now implemented in the TMX module. Check it to see if what you are looking for is there.

### Serial Forking Based on Q Value

A single SIP INVITE request may be forked to multiple destinations. We call the set of all such destinations a destination set. Individual elements within the destination sets are called branches. The script writer can add URIs to the destination set from the configuration file, or they can be loaded from the user location database. Each registered contact then becomes one branch in the destination set.

The default behavior of the TM module, if it encounters a SIP message with multiple branches in the destination set, is to forward the SIP message to all the branches in parallel. That means it sends the message to all the branch destinations before it waits for replies from any of them. This is the default behavior if you call `t_relay()` and similar functions without any other arguments.

Another approach of handling multiple branches in a destination set is serial forking. When configured to do serial forking, the server takes the first branch out of the destination set, forwards the message to its destination and waits for a reply or timeout. Only after a reply has been received or a timeout occurred, the server takes another destination from the destination set and tries again, until it receives a positive final reply or until all branches from the destination set have been tried.

Yet another, more sophisticated, way of handling multiple branches is combined serial/parallel forking, where individual branches within the destination set are assigned priorities. The order in which individual branches are tried is then determined by their relative priority within the destination set. Branches can be tried sequentially in the descending priority order and all branches that have the same priority can be tried in parallel. Such combined serial/parallel forking can be achieved in the TM module with the help of functions `t_load_contacts()` and `t_next_contacts()`.

Every branch in the destination set is assigned a priority number, also known as the q value. The q value is a floating point number in a range 0 to 1.0. The higher the q value number, the more priority is given to the particular branch in the destination set. Branches with q value 1.0 have maximum priority, such branches should always be tried first in serial forking. Branches with q value 0 have the lowest priority and they should by tried after all other branches with higher priority in the destination set.

As an example, consider the following simple configuration file. When the server receives an INVITE, it creates four branches with usernames A through D and then forwards the request using `t_relay()`:

    request_route {
      seturi("sip:a@example.com");
      append_branch("sip:b@example.com");
      append_branch("sip:c@example.com");
      append_branch("sip:d@example.com");

      t_relay();
      break;
    }

With this configuration the server forwards the request to all four branches at once, performing parallel forking as described above. We did not set the q value for individual branches in this example but we can do that by slightly modifying the arguments given to `append_branch()`:

    request_route {
      seturi("sip:a@example.com");
      append_branch("sip:b@example.com", "0.5");
      append_branch("sip:c@example.com", "0.5");
      append_branch("sip:d@example.com", "1.0");

      t_relay();
      break;
    }

Here we assigned q value 0.5 to branches B and C and q value 1.0 to branch D. We did not specify any q value for branch A and in that case it is assumed that its q value is the lowest from all branches within the destination set. If you try to run this example again, you will figure out that nothing changed, `t_relay()` still forward the message to all branches in parallel.

We now want to implement the combined serial/parallel forking. Branch D should be tried first, because its q value is 1.0. Branches B and C should be tried in parallel, but only after D finishes. Branch A should be tried after B and C finished, because its q value (the default) is the lowest of all. To do that, we need to introduce two new functions into our example and two tm module parameters:

    modparam("tm", "contacts_avp", "tm_contacts");
    modparam("tm", "contact_flows_avp", "tm_contact_flows");

    request_route {
      seturi("sip:a@example.com");
      append_branch("sip:b@example.com", "0.5");
      append_branch("sip:c@example.com", "0.5");
      append_branch("sip:d@example.com", "1.0");

      t_load_contacts();

      t_next_contacts();
      t_relay();
      break;
    }

First of all, the tm module parameters are mandatory if the two new functions are used. Function `t_load_contacts()` takes all branches from the destination set, sorts them according to their q values and stores them in the AVP configured in the modparam. The function also clears the destination set, which means that it removes all branches configured before with `seturi()` and `append_branch()`.

Function `t_next_contacts()` takes the AVP created by the previous function and extracts the branches with highest q values from it. In our example it is branch D. That branch is then put back into the destination set and when the script finally reaches `t_relay()`, the destination set only contains branch D and the request will be forwarded there.

We achieved the first step of serial forking, but this is not sufficient. Now we also need to forward to other branches with lower priority values when branch D finishes. To do that, we need to extend the configuration file again and introduce a failure_route section:

    modparam("tm", "contacts_avp", "tm_contacts");

    request_route {
      seturi("sip:a@example.com");
      append_branch("sip:b@example.com", "0.5");
      append_branch("sip:c@example.com", "0.5");
      append_branch("sip:d@example.com", "1.0");

      t_load_contacts();

      t_next_contacts();
      t_on_failure("serial");
      t_relay();
      break;
    }

    failure_route["serial"]
    {
      if (!t_next_contacts()) {
        exit;
      }

      t_on_failure("serial");
      t_relay();
    }

The failure_route section will be executed when branch D finishes. It executes `t_next_contacts()` again and this time the function retrieves branches B and C from the AVP and adds them to the destination set. Here we need to check the return value of the function, because a negative value indicates that there were no more branches, in that case the failure_route should just terminate and forward the response from branch D upstream.

If `t_next_contact()` returns a positive value then we have more new branches to try and we need to set up the failure_route again and call `t_relay()`. In our example the request will now be forwarded to branches B and C in parallel, because they were both added to the destination set by `t_next_contacts()` at the same time.

When branches B and C finish, the failure_route block is executed again, this time `t_next_contacts()` puts the final branch A into the destination set and `t_relay()` forwards the request there.

And that's the whole example, we achieved combined serial/parallel forking based on the q value of individual branches. In real-world configuration files the script writer would need to check the return value of all functions and `restart_fr_on_each_reply`. The destination set would not be configured directly in the configuration file, but can be retrieved from the user location database. In that case registered contacts will be stored in the destination set as branches and their q values (provided by UAs) will be used.

### Known Issues

- Possibly, performance could be improved by not parsing non-INVITEs, as they are not 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 store 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).