Tokyo Tyrant基本規(guī)范，翻譯自Tokyo Tyrant官網(wǎng)。
本節(jié)介紹Tokyo Tyrant的遠(yuǎn)程數(shù)據(jù)庫(kù)API，Lua擴(kuò)展和協(xié)議。部分細(xì)節(jié)內(nèi)容沒(méi)有翻譯。
五. 遠(yuǎn)程數(shù)據(jù)庫(kù)API
遠(yuǎn)程數(shù)據(jù)庫(kù)是一組用于使用Tokyo Cabinet抽象數(shù)據(jù)庫(kù)的接口，由Tokyo Tyrant服務(wù)器作為中介。查看'tcrdb.h'獲取全部說(shuō)明。
注：該API是以.h文件提供，適用于C語(yǔ)言。對(duì)java開發(fā)似乎意義不大，因此考慮跳過(guò)此章節(jié)。
六. Lua 擴(kuò)展
數(shù)據(jù)庫(kù)服務(wù)器可以在啟動(dòng)時(shí)讀取通過(guò)'-ext'選項(xiàng)指定的Lua腳本文件。客戶端可以通過(guò)遠(yuǎn)程數(shù)據(jù)庫(kù)API的'tcrdbext'函數(shù)來(lái)調(diào)用定義在腳本文件中的函數(shù)。
1) 用戶自定義函數(shù)
可以在腳本文件中定義一些任意的函數(shù)。每個(gè)函數(shù)接收2個(gè)字符串參數(shù)(key和value)。返回值將被發(fā)送回客戶端。如果函數(shù)返回'nil'，服務(wù)器發(fā)送錯(cuò)誤碼到客戶端。
'tcrdbext'提供兩種類型的加鎖操作。一種是全局鎖定，意味著同一時(shí)刻僅有一個(gè)線程能操作這個(gè)函數(shù)。另外一種是記錄鎖定，意味著同一時(shí)刻僅有一個(gè)線程能操作這個(gè)指定key的記錄。
注意Lua解釋器的實(shí)例被每個(gè)原生線程分別處理。因?yàn)長(zhǎng)ua的全局變量無(wú)益于在遠(yuǎn)程線程或者會(huì)話中共享數(shù)據(jù)，需要使用數(shù)據(jù)庫(kù)或者stash functions來(lái)共享數(shù)據(jù)。
Built-in Functions
2) 內(nèi)建函數(shù)
下列用于數(shù)據(jù)庫(kù)操作的內(nèi)建函數(shù)可以在用戶自定義函數(shù)中使用。'key'和'value'參數(shù)的類型可以是string或者number。如果給出number，將被轉(zhuǎn)換為十進(jìn)制字符串。
注: 詳細(xì)的內(nèi)建函數(shù)列表就不一一翻譯了，請(qǐng)參考原文。
*****************************
內(nèi)建函數(shù)，名稱以'_'開頭，不能被客戶端直接調(diào)用。當(dāng)服務(wù)器啟動(dòng)時(shí)，如果有定義函數(shù)'_begin'則該函數(shù)被隱式的調(diào)用。當(dāng)服務(wù)器停止時(shí)，如果有定義函數(shù)'_end'則該函數(shù)被隱式的調(diào)用。
以下為內(nèi)建的全局變量：
全局變量 信息
'_version' 服務(wù)器的版本信息
'_pid' 進(jìn)程ID
'_sid' 服務(wù)器ID
'_thnum' 原生線程的數(shù)目
'_thid' 每個(gè)原生線程的ID數(shù)字
3) 實(shí)例代碼
下面的代碼是增加記錄的值并存儲(chǔ)為十進(jìn)制數(shù)字的字符串的例子。這個(gè)函數(shù)可以在調(diào)用時(shí)使用記錄鎖定來(lái)保證原子性。
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
七. 協(xié)議
服務(wù)器和客戶端的協(xié)議是基于TCP/IP。默認(rèn)，服務(wù)端口被綁定在本機(jī)的每個(gè)地址上，端口號(hào)位1978。每個(gè)服務(wù)器和客戶端的會(huì)話由request和response組成。服務(wù)器在同一端口上使用三種協(xié)議。
1) 原始二進(jìn)制協(xié)議
在原始二進(jìn)制協(xié)議中，請(qǐng)求被分類為下列命令。請(qǐng)求和應(yīng)答的結(jié)構(gòu)由命令決定。請(qǐng)求和應(yīng)答的整型字節(jié)碼順序是big endian。
注: 詳細(xì)的二進(jìn)制協(xié)議命令就不一一翻譯了，請(qǐng)參考原文。
*****************************
客戶端可以在任意時(shí)間結(jié)束和關(guān)閉socket來(lái)結(jié)束會(huì)話。如果不關(guān)閉，則連接可以被下一次會(huì)話重用。如果發(fā)生違反協(xié)議或者某些知名錯(cuò)誤，服務(wù)器會(huì)立即終止會(huì)話并關(guān)閉連接。
2) Memcached 兼容協(xié)議
作為memcached (ASCII)兼容協(xié)議，服務(wù)器實(shí)現(xiàn)下列命令: "set", "add", "replace", "get", "delete", "incr", "decr", "stats", "flush_all", "version" 和 "quit". 更新命令的"norely"選項(xiàng)同樣支持。但是, "flags",
"exptime" 和 "cas unique" 參數(shù)將被忽略。
3） HTTP 兼容協(xié)議
作為HTTP (1.1) 兼容協(xié)議, 服務(wù)器實(shí)現(xiàn)下列命令：
命令 類似于
"GET" 'tcrdbget'
"HEAD" 'tcrdbvsiz'
"PUT" 'tcrdbput'
"POST" 'tcrdbext'
"DELETE" 'tcrdbout'
"OPTIONS" 'tcrdbstat'
每個(gè)請(qǐng)求的URI將被作為URL編碼過(guò)的key對(duì)待。而實(shí)體內(nèi)容被作為value。不過(guò)，除"Connection"和"Content-Length"外所有的header被忽略。
"PUT"有header "X-TT-PDMODE"，值可以是1(同'tcrdbputkeep')， 2(同'tcrdbputcat')， 或者其他(同'tcrdbput')。
"POST"可以有header "X-TT-XNAME" 或 header "X-TT-MNAME"中的一個(gè)."X-TT-XNAME"等同于'tcrdbext'，用于指定函數(shù)名。header "X-TT-XOPTS" 用于 bitwise-or 選項(xiàng)，1(記錄鎖)和2(全局鎖). 每個(gè)請(qǐng)求的URI將被作為URL編碼過(guò)
的key對(duì)待。而實(shí)體內(nèi)容被作為value。結(jié)果表示在應(yīng)答的實(shí)體正文中。header"X-TT-MOPTS"用于 bitwise-or 選項(xiàng) , 1(忽略更新日志)。 請(qǐng)求參數(shù)用"application/x-www-form-urlencoded"格式表示在實(shí)體正文中。名字被忽略而值被作
為參數(shù)列表。結(jié)果在應(yīng)答的實(shí)體正文中用"application/x-www-form-urlencoded"格式表示。