kamailio-ASYNC模块详解【以下内容来源于官网，该文章仅作为翻译】

ASYNC 模块

作者
Daniel-Constantin Mierla
miconda@gmail.com

编辑
Daniel-Constantin Mierla
miconda@gmail.com

版权
© 2011-2016 asipto.com
*
官网链接
🔗https://kamailio.org/docs/modules/6.0.x/modules/async.html

目录

1. 管理员指南
   1. 概述
   2. 依赖
      2.1 Kamailio 模块
      2.2 外部库或应用程序
   3. 参数
      3.1 workers（整数）
      3.2 ms_timer（整数）
      3.3 return（整数）
      3.4 mode（整数）
   4. 函数
      4.1 async_route(routename, seconds)
      4.2 async_ms_route(routename, milliseconds)
      4.3 async_sleep(seconds)
      4.4 async_ms_sleep(milliseconds)
      4.5 async_task_route(routename)
      4.6 async_task_group_route(routename, groupname)
      4.7 async_task_data(routename, data)
      4.8 async_task_group_data(routename, groupname, data)
      4.9 async_tkv_emit(type, key, value)

1. 概述

该模块提供了在配置文件中处理 SIP 请求的异步操作功能。

ASYNC 模块使用 TM 和 TMX 模块中的 t_suspend() 和 t_continue() 函数。

注意：在调用异步操作后，处理将在另一个应用进程中继续。因此，不应使用存储在私有内存中的变量。如果希望在处理恢复后获取值，请尝试使用共享内存（例如 $avp(...)、$xavp(...)、$shv(...)、htable $sht(...)）。

2. 依赖

2.1 Kamailio 模块

以下模块必须在此模块之前加载：

• tm：事务管理模块。
• tmx：事务管理扩展模块。

2.2 外部库或应用程序

无。

3. 参数

3.1 workers（整数）

用于处理 async_route() 和 async_sleep() 异步任务的工作进程数。
默认值为 1。

示例 1.1. 设置 workers 参数

modparam("async", "workers", 2)

3.2 ms_timer（整数）

启用 async_ms_sleep() 和 async_ms_route() 函数的毫秒计时器。整数值表示计时器的分辨率（以毫秒为单位）。较小的计时器分辨率会增加系统负载。如果设置为 1，则计时器分辨率为 1 毫秒；设置为 20，则分辨率为 20 毫秒。
默认值为 0。

示例 1.2. 设置 ms_timer 参数

modparam("async", "ms_timer", 10)

3.3 return（整数）

异步函数成功时返回的值。此参数不适用于异步数据函数，仅适用于挂起 SIP 事务的函数。
默认值为 0。

示例 1.3. 设置 return 参数

modparam("async", "return", 1)

3.4 mode（整数）

控制模块是否应绑定到 tm 模块。如果不需要使用 tm 函数（例如仅需使用 async_tkv_emit()），则可以设置为 1。
默认值为 0（绑定到 tm 模块）。

示例 1.4. 设置 mode 参数

modparam("async", "mode", 1)

4. 函数

4.1 async_route(routename, seconds)

模拟休眠 seconds 秒，然后继续使用 route[routename] 处理 SIP 请求。如果发生内部错误，函数返回 false，否则函数会退出脚本的执行（返回 0 的行为）。

参数说明：

• routename：路由名称，可以是静态字符串或包含配置变量的动态字符串。
• seconds：挂起 SIP 请求处理的秒数，最大值为 100。可以是静态整数或包含整数的变量。

注意：由于 SIP 请求处理在另一个进程中恢复，配置文件执行状态实际上会丢失。因此，请确保在恢复后执行的配置在 route[routename] 完成后结束。

使用范围：
可以在 REQUEST_ROUTE 中使用。

示例 1.5. async_route 使用示例

request_route {
    ...
    async_route("RESUME", "4");
    ...
}
route[RESUME] {
   send_reply("404", "Not found");
   exit;
}

4.2 async_ms_route(routename, milliseconds)

模拟休眠 milliseconds 毫秒，然后继续使用 route[routename] 处理 SIP 请求。此函数仅在 ms_timer 参数大于 0 时有效。

参数说明：

• routename：路由名称，可以是静态字符串或包含配置变量的动态字符串。
• milliseconds：挂起 SIP 请求处理的毫秒数，最大值为 30000（30 秒）。可以是静态整数或包含整数的变量。

使用范围：
可以在 REQUEST_ROUTE 中使用。

示例 1.6. async_ms_route 使用示例

request_route {
    ...
    async_ms_route("RESUME", "250");
    ...
}
route[RESUME] {
   send_reply("404", "Not found");
   exit;
}

4.3 async_sleep(seconds)

模拟休眠 seconds 秒，然后继续处理 SIP 请求。注意：处理会继续到当前路由块中的最后一个操作。如果需要更好地控制等待时间后的执行内容，请考虑使用 async_route()。

参数说明：

• seconds：挂起 SIP 请求处理的秒数，最大值为 100。可以是静态整数或包含整数的变量。

使用范围：
可以在 REQUEST_ROUTE 中使用。

示例 1.7. async_sleep 使用示例

async_sleep("4");
send_reply("404", "Not found");
exit;

4.4 async_ms_sleep(milliseconds)

类似于 async_sleep()，但参数为毫秒。此函数仅在 ms_timer 参数大于 0 时有效。

参数说明：

• milliseconds：挂起 SIP 请求处理的毫秒数，最大值为 30000（30 秒）。可以是静态整数或包含整数的变量。

使用范围：
可以在 REQUEST_ROUTE 中使用。

示例 1.8. async_ms_sleep 使用示例

route[REQUESTSHAPER] {
    $var(res) = http_connect("leakybucket", "/add?key=$fd", $null, $null, "$avp(delay)");
    $var(d) = $(avp(delay){s.int});
    if ($var(d) > 0) {
        # 延迟请求 $avp(delay) 毫秒
        async_ms_sleep("$var(d)");
        if (!t_relay()) {
            sl_reply_error();
        }
        exit;
    }
    # 无延迟
    if (!t_relay()) {
        sl_reply_error();
    }
    exit;
}

4.5 async_task_route(routename)

在核心异步框架的第一组进程中使用 route[routename] 继续处理 SIP 请求。任务在异步框架进程空闲时立即执行，没有像 async_route(...) 那样的等待时间。

注意：需要设置核心参数 async_workers 以启用异步框架。

使用范围：
可以在 REQUEST_ROUTE 中使用。

示例 1.10. async_task_route 使用示例

request_route {
    ...
    async_task_route("RESUME");
    ...
}
route[RESUME] {
   t_relay();
   exit;
}

4.6 async_task_group_route(routename, groupname)

类似于 async_task_route()，但允许指定异步工作组的名称。参见核心全局参数 async_workers_group。

使用范围：
可以在 REQUEST_ROUTE 中使用。

示例 1.11. async_task_group_route 使用示例

async_workers_group="name=abc;workers=4;nonblock=0;usleep=0"
...
request_route {
    ...
    async_task_route("RESUME", "abc");
    ...
}
route[RESUME] {
   t_relay();
   exit;
}

4.7 async_task_data(routename, data)

将数据发送到异步任务进程（第一组），该进程执行 route[routename] 并通过 $async(data) 使数据可用。

注意：当前 SIP 消息不会挂起，也不会在异步任务进程中可用，那里使用了一个本地伪造的 SIP 请求。

使用范围：
可以在 ANY_ROUTE 中使用。

示例 1.12. async_task_data 使用示例

async_workers_group="name=abc;workers=4;nonblock=0;usleep=0"
...
request_route {
    ...
    async_task_data("RESUME", "caller: $fU - callee: $tU");
    ...
}
route[RESUME] {
   xinfo("$async(data)\n");
   exit;
}

4.8 async_task_group_data(routename, groupname, data)

类似于 async_task_route()，但允许指定异步工作组的名称。参见核心全局参数 async_workers_group。

使用范围：
可以在 ANY_ROUTE 中使用。

示例 1.13. async_task_group_data 使用示例

async_workers_group="name=abc;workers=4;nonblock=0;usleep=0"
...
request_route {
    ...
    async_task_data("RESUME", "abc", "caller: $fU - callee: $tU");
    ...
}
route[RESUME] {
   xinfo("$async(data)\n");
   exit;
}

4.9 async_tkv_emit(type, key, value)

发出一个类型-键-值事件。

使用范围：
可以在 ANY_ROUTE 中使用。

示例 1.14. async_tkv_emit 使用示例

async_workers_group="name=tkv;workers=1;nonblock=0;usleep=0"
...
request_route {
    ...
    async_tkv_emit("8000", "call", "caller='$fU';callee='$tU'");
    ...
}
event_route[core:tkv] {
    xinfo("$atkv(type) / $atkv(key) / $atkv(val)\n");
    exit;
}

总结

ASYNC 模块提供了强大的异步操作功能，允许在 Kamailio 配置文件中实现延迟处理、任务分发和事件触发等功能。通过合理配置参数和使用函数，可以显著提升 SIP 请求处理的灵活性和效率。