最近有需求做全平臺的定時器，業務複雜，效能要求高，linux crontab的方式不適用，調研一些支援定時執行的記憶體佇列系統，其中beanstalkd較適合。先將其協議研究一遍，使用就不是問題了。

總括

beanstalkd協議基於ASCII編碼執行在tcp上。客戶端連線伺服器併發送指令和資料，然後等待響應並關閉連線。對於每個連線，伺服器按照接收命令的序列依次處理並響應。所有整型值都非負的十進位制數，除非有特別宣告。

名稱約定

所有名稱必須是ASCII碼字串，即包括：

字母（A-Z和a-z）

數字（0-9）

加號 +

斜線 /

連字元 -

分號 ;

點 .

美元符號 $

下劃線 _

括號 ()

注意：名稱不能以連字元開始，並且是以空白字元結束，每個名稱至少包含一個字元。

錯誤說明

返回的錯誤 描述

OUT_OF_MEMORY\r\n 伺服器沒有足夠的記憶體分配給特定的job，客戶端應該稍後重試

INTERNAL_ERROR\r\n 伺服器內部錯誤，該錯誤不應該發生，如果發生了，請報告：http://groups.google.com/group/beanstalk-talk.

BAD_FORMAT\r\n 格式不正確，客戶端傳送的指令格式出錯，有可能不是以\r\n結尾，或者要求整型值等等

UNKNOWN_COMMAND\r\n 未知的命令，客戶端傳送的指令伺服器不理解

job的生命週期

一個工作任務job當client使用put命令時建立。在整個生命週期中job可能有四個工作狀態：ready，reserved，delayed，buried。在put之後，一個job的典型狀態是ready，在ready佇列中，它將等待一個worker取出此job並設定為其為reserved狀態。worker佔有此job並執行，當job執行完畢，worker可以傳送一個delete指令刪除此job。

狀態碼 描述

ready 等待被取出並處理

reserved 如果job被worker取出，將被此worker預訂，worker將執行此job

delayed 等待特定時間之後，狀態再遷移為ready狀態

buried 等待喚醒，通常在job處理失敗時

job典型的生命週期

put reserve delete ---------> [READY] ----------------> [RESERVED] ------------> *poof*

job可能的狀態遷移

Tubes

有名的任務佇列，一個伺服器有一個或者我個tubes，用來儲存統一型別的job。每個tube由一個就緒佇列與延遲佇列組成。每個job所有的狀態遷移在一個tube中完成。consumers消費者可以監控感興趣的tube，通過傳送watch指令。consumers消費者可以取消監控tube，通過傳送ignore命令。通過watch list命令返回所有監控的tubes，當客戶端預訂一個job，此job可能來自任何一個它監控的tube。

當一個客戶端連線上伺服器時，客戶端監控的tube預設為defaut，如果客戶端提交job時，沒有使用use命令，那麼這些job就存於名為default的tube中。

tube按需求建立，無論他們在地方被引用到。如果一個tube變為空（即no ready jobs，no delayed jobs，no buried jobs）和沒有任何客戶端引用，它將會被自動刪除。

指令說明（Commands）

生產者指令說明（Producer Commands）

put

說明

插入一個job到佇列

格式

put

\r\n

\r\n

pri 整型值，為優先順序，可以為0-2^32，值越小優先順序越高，預設為1024。

delay 整型值，延遲ready的秒數，在這段時間job為delayed狀態。

ttr 整型值，允許worker執行的最大秒數，如果worker在這段時間不能delete，release，bury job，那麼job超時，伺服器將release此job，此job的狀態遷移為ready。最小為1秒，如果客戶端指定為0將會被重置為1。

bytes 整型值，job body的長度，不包含\r\n，這個值必須小於max-job-size，預設為2^16。

data job body

響應

INSERTED \r\n 表示插入job成功，id為新job的任務標識，整型值

BURIED \r\n 如伺服器為了增加佇列的優先順序而，記憶體不足時返回，id為新job的任務標識，整型值

EXPECTED_CRLF\r\n job body必須以\r\n結尾

JOB_TOO_BIG\r\n job body的長度超過max-job-size

DRAINING\r\n 表示伺服器資源耗盡，表示伺服器已經進入了“drain mode”，伺服器再也不能接受連線，客戶端應該使用另一個伺服器或者斷開稍後重試

use

說明

producer生產者使用，隨後使用put命令，將job放置於對應的tube

格式

use \r\n

tube tube的名稱，最大為200位元組，不存在時將自動建立

響應

USING \r\n tube為正在使用的tube名稱

消費者指令說明（Worker Commands）

reserve

說明

取出（預訂）job，待處理。它將返回一個新預訂的job，如果沒有job，beanstalkd將直到有job時才傳送響應。一旦job狀態遷移為reserved,取出job的client被限制在指定的時間（如果設定了ttr）完成，否則超時，job狀態重灌遷移為ready。

格式

reserve\r\n

可選的一個相似的命令

reserve-with-timeout \r\n 設定取job的超時時間，timeout設定為0時，伺服器立即響應或者TIMED_OUT，積極的設定超時，將會限制客戶端阻塞在取job的請求的時間。

響應

DEADLINE_SOON\r\n During the TTR of a reserved job, the last second is kept by the server as a safety margin, during which the client will not be made to wait for another job. If the client issues a reserve command during the safety margin, or if the safety margin arrives while the client is waiting on a reserve command.

TIMED_OUT\r\n 超時

RESERVED

\r\n

\r\n

成功取出job，id為job id,整型值，job body的長度，不包含\r\n，data為job body

delete

說明

從佇列中刪除一個job

格式

delete \r\n

id為job id

響應

DELETED\r\n 刪除成功

NOT_FOUND\r\n job不存在時，或者job的狀態不為ready和buried（這種情況是在job執行超時之前，client傳送了delete指令）

release

說明

release指令將一個reserved的job放回ready queue。它通常在job執行失敗時使用。

格式

release \r\n

id 為job id，pri為job的優先順序，delay為延遲ready的秒數

響應

RELEASED\r\n 表明成功

BURIED\r\n 如伺服器為了增加佇列的優先順序而，記憶體不足時返回

NOT_FOUND\r\n 如果job不存在或者client沒有預訂此job

bury

說明

將一個job的狀態遷移為buried，通過kick命令喚醒

格式

bury \r\n

id為job id，pri為優先順序

響應

BURIED\r\n 表明成功

NOT_FOUND\r\n 如果job不存在或者client沒有預訂此job

touch

說明

允許worker請求更多的時間執行job，這個很有用當job需要很長的時間來執行，worker可用週期的告訴伺服器它仍然在執行job（可以被DEADLINE_SOON觸發）

格式

touch \r\n

id為job id

響應

TOUCHED\r\n 表明成功 NOT_FOUND\r\n 如果job不存在或者client沒有預訂此job

watch

說明

新增監控的tube到watch list列表，reserve指令將會從監控的tube列表獲取job，對於每個連線，監控的列表預設為default

格式

watch \r\n

tube 為監控的tube名稱，名稱最大為200位元組，如果tube不存在會自動建立

響應

WATCHING \r\n 表明成功

count 整型值，已監控的tube數量

ignore

說明

從已監控的watch list列表中移出特定的tube

格式

ignore \r\n

tube 為移出的tube名稱，名稱最多為200位元組，如果tube不存在會自動建立

響應

WATCHING \r\n 表明成功

count 整型值，已監控的tube數量

NOT_IGNORED\r\n 如果client企圖忽略其僅有的tube時的響應

其他指令說明（Other Command）

peek

說明

讓client在系統中檢查job，有四種形式的命令，其中第一種形式的指令是針對當前使用的tube

格式

peek \r\n 返回id對應的job

peek-ready\r\n 返回下一個ready job

peek-delayed\r\n 返回下一個延遲剩餘時間最短的job

peek-buried\r\n 返回下一個在buried列表中的job

響應

NOT_FOUND\r\n 如果job不存在，或者沒有對應狀態的job

FOUND \r\n \r\n

id 為對應的job id

bytes job body的位元組數

data 為job body

kick

說明

此指令應用在當前使用的tube中，它將job的狀態遷移為ready或者delayed

格式

kick \r\n

bound 整型值，喚醒的job上限

響應

KICKED \r\n

count 為真實喚醒的job數量

kick-job

說明

kick指令的一個變體，可以使單個job被喚醒，使一個狀態為buried或者delayed的job遷移為ready，所有的狀態遷移都在相同的tube中完成

格式

kick-job \r\n

id 為job id

響應

NOT_FOUND\r\n 如果job不存在，或者job是不可喚醒的狀態

KICKED\r\n 表明成功

stats-job

說明

統計job的相關資訊

格式

stats-job \r\n

id 為job id

響應

NOT_FOUND\r\n 如果job不存在

OK \r\n \r\n

bytes 為接下來的data區塊的長度

data 為YAML file的統計資訊

其中YAML file包括的key有：

id 表示job id

tube 表示tube的名稱

state 表示job的當前狀態

pri 表示job的優先順序

age 表示job建立的時間單位秒

time-left 表示job的狀態遷移為ready的時間，僅在job狀態為reserved或者delayed時有意義，當job狀態為reserved時表示剩餘的超時時間。

file 表示包含此job的binlog序號，如果沒有開啟它將為0

reserves 表示job被reserved的次數

timeouts 表示job處理的超時時間

releases 表示job被released的次數

buries 表示job被buried的次數

kicks 表示job被kiced的次數

stats-tube

說明

統計tube的相關資訊

格式

stats-tube \r\n

tube 為對應的tube的名稱，最多為200位元組

響應

NOT_FOUND\r\n 如果tube不存在

OK \r\n \r\n

bytes 為接下來的data區塊的長度

data 為YAML file的統計資訊

其中YAML file包括的key有：

name 表示tube的名稱

current-jobs-urgent 此tube中優先順序小於1024狀態為ready的job數量

current-jobs-ready 此tube中狀態為ready的job數量

current-jobs-reserved 此tube中狀態為reserved的job數量

current-jobs-delayed 此tube中狀態為delayed的job數量

current-jobs-bureid 此tube中狀態為buried的job數量

total-jobs 此tube中建立的所有job數量

current-using 使用此tube開啟的連線數

current-wating 使用此tube開啟連線並且等待響應的連線數

current-watching 開啟的連線監控此tube的數量

pause 此tube暫停的秒數

cmd-delete 此tube中總共執行的delete指令的次數

cmd-pause-tube 此tube中總共執行pause-tube指令的次數

pause-time-left 此tube暫停剩餘的秒數

stats

說明

返回整個訊息佇列系統的整體資訊

格式

stats\r\n

響應

OK \r\n \r\n

bytes 為接下來的data區塊的長度

data 為YAML file的統計資訊

其中YAML file包括的key有（所有的資訊都累積的，自從beanstalkd程序啟動以來，這些資訊不儲存在binlog中）：

current-jobs-urgent 優先順序小於1024狀態為ready的job數量

current-jobs-ready 狀態為ready的job數量

current-jobs-reserved 狀態為reserved的job數量

current-jobs-delayed 狀態為delayed的job數量

current-jobs-bureid 狀態為buried的job數量

相關推薦