Tokyo Tyrant基本规范(4)--协议
Tokyo Tyrant基本规范，翻译自Tokyo Tyrant官网。
本节介绍Tokyo Tyrant的远程数据库API，Lua扩展和协议。部分细节内容没有翻译。
五. 远程数据库API
远程数据库是一组用于使用Tokyo Cabinet抽象数据库的接口，由Tokyo Tyrant服务器作为中介。查看'tcrdb.h'获取全部说明。
注：该API是以.h文件提供，适用于C语言。对java开发似乎意义不大，因此考虑跳过此章节。
六. Lua 扩展
数据库服务器可以在启动时读取通过'-ext'选项指定的Lua脚本文件。客户端可以通过远程数据库API的'tcrdbext'函数来调用定义在脚本文件中的函数。
1) 用户自定义函数
可以在脚本文件中定义一些任意的函数。每个函数接收2个字符串参数(key和value)。返回值将被发送回客户端。如果函数返回'nil'，服务器发送错误码到客户端。
'tcrdbext'提供两种类型的加锁操作。一种是全局锁定，意味着同一时刻仅有一个线程能操作这个函数。另外一种是记录锁定，意味着同一时刻仅有一个线程能操作这个指定key的记录。
注意Lua解释器的实例被每个原生线程分别处理。因为Lua的全局变量无益于在远程线程或者会话中共享数据，需要使用数据库或者stash functions来共享数据。
Built-in Functions
2) 内建函数
下列用于数据库操作的内建函数可以在用户自定义函数中使用。'key'和'value'参数的类型可以是string或者number。如果给出number，将被转换为十进制字符串。
注: 详细的内建函数列表就不一一翻译了，请参考原文。
*****************************
内建函数，名称以'_'开头，不能被客户端直接调用。当服务器启动时，如果有定义函数'_begin'则该函数被隐式的调用。当服务器停止时，如果有定义函数'_end'则该函数被隐式的调用。
以下为内建的全局变量：
全局变量
信息
'_version'
服务器的版本信息
'_pid'
进程ID
'_sid'
服务器ID
'_thnum'
原生线程的数目
'_thid'
每个原生线程的ID数字
3) 实例代码
下面的代码是增加记录的值并存储为十进制数字的字符串的例子。这个函数可以在调用时使用记录锁定来保证原子性。
function incr(key, value)
value = tonumber(value)
if not value then
return nil
end
local old = tonumber(_get(key))
if old then
value = value + old
end
if not _put(key, value) then
return nil
end
return value
end
七. 协议
服务器和客户端的协议是基于TCP/IP。默认，服务端口被绑定在本机的每个地址上，端口号位1978。每个服务器和客户端的会话由request和response组成。服务器在同一端口上使用三种协议。
1) 原始二进制协议
在原始二进制协议中，请求被分类为下列命令。请求和应答的结构由命令决定。请求和应答的整型字节码顺序是big endian。
注: 详细的二进制协议命令就不一一翻译了，请参考原文。
*****************************
客户端可以在任意时间结束和关闭socket来结束会话。如果不关闭，则连接可以被下一次会话重用。如果发生违反协议或者某些知名错误，服务器会立即终止会话并关闭连接。
2) Memcached 兼容协议
作为memcached (ASCII)兼容协议，服务器实现下列命令: "set", "add", "replace", "get", "delete", "incr", "decr", "stats", "flush_all", "version" 和 "quit". 更新命令的"norely"选项同样支持。但是, "flags",
"exptime" 和 "cas unique" 参数将被忽略。
3） HTTP 兼容协议
作为HTTP (1.1) 兼容协议, 服务器实现下列命令：
命令
类似于
"GET"
'tcrdbget'
"HEAD"
'tcrdbvsiz'
"PUT"
'tcrdbput'
"POST"
'tcrdbext'
"DELETE"
'tcrdbout'
"OPTIONS"
'tcrdbstat'
每个请求的URI将被作为URL编码过的key对待。而实体内容被作为value。不过，除"Connection"和"Content-Length"外所有的header被忽略。
"PUT"有header "X-TT-PDMODE"，值可以是1(同'tcrdbputkeep')， 2(同'tcrdbputcat')， 或者其他(同'tcrdbput')。
"POST"可以有header "X-TT-XNAME" 或 header "X-TT-MNAME"中的一个."X-TT-XNAME"等同于'tcrdbext'，用于指定函数名。header "X-TT-XOPTS" 用于 bitwise-or 选项，1(记录锁)和2(全局锁). 每个请求的URI将被作为URL编码过
的key对待。而实体内容被作为value。结果表示在应答的实体正文中。header"X-TT-MOPTS"用于 bitwise-or 选项 , 1(忽略更新日志)。 请求参数用"application/x-www-form-urlencoded"格式表示在实体正文中。名字被忽略而值被作
为参数列表。结果在应答的实体正文中用"application/x-www-form-urlencoded"格式表示。