ASYNC 模块
作者：Daniel-Constantin Mierla
miconda@gmail.com
编辑：Daniel-Constantin Mierla
miconda@gmail.com
版权所有 © 2011-2016 asipto.com
目录
- 管理员指南
- 概述
- 依赖项
- Kamailio 内置模块
- 外部库与应用
- 配置参数
- workers（整数）
- ms_timer（整数）
- return（整数）
- mode（整数）
- 可用函数
- async_route(routename, seconds)
- async_ms_route(routename, milliseconds)
- async_sleep(seconds)
- async_ms_sleep(milliseconds)
- async_task_route(routename)
- async_task_group_route(routename, groupname)
- async_task_data(routename, data)
- async_task_group_data(routename, groupname, data)
- async_tkv_emit(type, key, value)
示例列表
1.1 配置 workers 参数
1.2 配置 ms_timer 参数
1.3 配置 return 参数
1.4 配置 mode 参数
1.5 async_route 使用示例
1.6 async_ms_route 使用示例
1.7 async_sleep 使用示例
1.8 async_ms_sleep 使用示例
1.9 async_workers 核心参数示例
1.10 async_task_route 使用示例
1.11 async_task_group_route 使用示例
1.12 async_task_data 使用示例
1.13 async_task_group_data 使用示例
1.14 async_tkv_emit 使用示例
第 1 章 管理员指南
1. 概述
本模块为配置脚本中的 SIP 请求处理提供异步操作能力。
异步功能底层依赖 TM 与 TMX 模块提供的t_suspend()和t_continue()函数实现。
注意：触发异步操作后，后续的报文处理会在另一个应用进程中恢复执行。因此不建议使用私有内存变量，若需要在处理恢复后读取数据，请使用共享内存变量（例如$avp(...)、$xavp(...)、$shv(...)、htable 模块的$sht(...)）。
2. 依赖项
2.1 Kamailio 内置模块
加载本模块前必须先加载以下模块：
tm：事务管理模块tmx：事务管理扩展模块
2.2 外部库与应用
无额外外部依赖。
3. 配置参数
3.1workers（整数）
用于处理async_route()和async_sleep()异步任务的工作进程数量。
默认值：1
示例 1.1 配置 workers 参数
... modparam("async", "workers", 2) ...3.2ms_timer（整数）
为async_ms_sleep()和async_ms_route()函数启用毫秒级定时器，参数值为定时器的分辨率（单位：毫秒）。
分辨率数值越小，系统负载越高。设置为 1 代表 1 毫秒精度，设置为 20 代表 20 毫秒精度。
默认值：0（不启用毫秒级定时器）
示例 1.2 配置 ms_timer 参数
... modparam("async", "ms_timer", 10) ...3.3return（整数）
异步函数执行成功时的返回值。该参数仅对会挂起 SIP 事务的异步函数生效，对异步数据类函数无效。
默认值：0
示例 1.3 配置 return 参数
... modparam("async", "return", 1) ...3.4mode（整数）
控制本模块是否绑定 TM 模块：0表示绑定，1表示不绑定。
如果仅使用async_tkv_emit()这类功能，无需依赖 TM 模块函数，可设置为 1。
默认值：0（绑定 TM 模块）
示例 1.4 配置 mode 参数
... modparam("async", "mode", 1) ...4. 可用函数
4.1async_route(routename, seconds)
将当前 SIP 请求挂起指定秒数后，转入route[routename]路由块继续处理。
- 内部发生错误时函数返回 false；
- 执行成功时，函数会直接终止当前脚本的执行（等同于返回 0 的行为）。
参数说明：
routename：目标路由块名称，支持静态字符串或带配置变量的动态字符串；seconds：请求挂起的秒数，最大值为 100，支持静态整数或存储整数的变量。
由于请求恢复后运行在新的进程中，原配置脚本的执行状态会丢失；恢复执行后，跑完指定的路由块就会结束处理，不会回到原调用位置。
可在REQUEST_ROUTE中使用。
示例 1.5 async_route 使用示例
... request_route { ... async_route("RESUME", "4"); ... } route[RESUME] { send_reply("404", "Not found"); exit; } ...4.2async_ms_route(routename, milliseconds)
功能与async_route()一致，时间单位为毫秒。仅当ms_timer参数大于 0 时生效。
- 内部发生错误时函数返回 false；
- 执行成功时终止当前脚本执行。
参数说明：
routename：目标路由块名称，支持静态或动态字符串；milliseconds：请求挂起的毫秒数，最大值为 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.3async_sleep(seconds)
将当前 SIP 请求挂起指定秒数，之后继续执行当前路由块的后续逻辑。
注意：恢复后会一直执行到当前路由块末尾。如果需要更精准地控制等待后的执行逻辑，建议使用async_route()。
由于执行会在新进程中恢复，异步等待前后不要使用私有内存变量。
参数说明：
seconds：请求挂起的秒数，最大值为 100，支持静态整数或变量。
内部发生错误时函数返回 false。
可在REQUEST_ROUTE中使用。
示例 1.7 async_sleep 使用示例
... async_sleep("4"); send_reply("404", "Not found"); exit; ...4.4async_ms_sleep(milliseconds)
功能与async_sleep()一致，时间单位为毫秒。仅当ms_timer参数大于 0 时生效。
参数说明：
milliseconds：请求挂起的毫秒数，最大值为 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.5async_task_route(routename)
将 SIP 请求交给核心异步框架第一组中的空闲工作进程，在指定路由块中继续处理。
使用该功能需要先配置核心参数async_workers以启用异步框架；任务无需等待固定时长，异步工作进程空闲时就会立即执行。
内部发生错误时函数返回 false；执行成功时终止当前脚本执行。
参数说明：
routename：目标路由块名称，支持静态或动态字符串。
请求恢复后原执行状态丢失，目标路由执行完毕即结束。
可在REQUEST_ROUTE中使用。
示例 1.9 async_workers 核心参数示例
... # 启用 8 个工作进程，供 async 及其他模块使用 async_workers=8 ...示例 1.10 async_task_route 使用示例
... request_route { ... async_task_route("RESUME"); ... } route[RESUME] { t_relay(); exit; } ...4.6async_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.7async_task_data(routename, data)
向第一组异步任务进程发送数据，进程会执行指定路由块，并可通过$async(data)读取传入的数据。
该函数不会挂起当前 SIP 报文，异步任务进程中也无法访问原始 SIP 报文，仅使用本地构造的虚拟 SIP 请求。
参数支持嵌入变量。
返回值：成功返回正值（true），失败返回负值（false）。
可在任意路由块（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.8async_task_group_data(routename, groupname, data)
功能与async_task_data()一致，额外支持指定异步工作进程组的名称。更多细节可参考核心全局参数async_workers_group。
返回值：成功返回正值（true），失败返回负值（false）。
可在任意路由块（ANY_ROUTE）中使用。
示例 1.13 async_task_group_data 使用示例
... async_workers_group="name=abc;workers=4;nonblock=0;usleep=0" ... request_route { ... async_task_group_data("RESUME", "abc", "caller: $fU - callee: $tU"); ... } route[RESUME] { xinfo("$async(data)\n"); exit; } ...4.9async_tkv_emit(type, key, value)
触发一个「类型-键-值（TKV）」事件。
可在任意路由块（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; } ...
 agent和组件)