本节介绍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 valueend

 

七. 协议

    服务器和客户端的协议是基于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"格式表示。