Beanstalkd中文协议解读

此版本已经合并到了Beanstalkd主仓库，你再也不用担心语言障碍了：

这篇文档的另外一个版本：来自PHPBoy

最近有需求做全平台的定时器，业务复杂，性能要求高，linux crontab的方式不适用，调研一些支持定时执行的内存队列系统，其中beanstalkd较适合。先将其协议研究一遍，使用就不是问题了。

总括

beanstalkd协议基于ASCII编码运行在tcp上。客户端连接服务器并发送指令和数据，然后等待响应并关闭连接。对于每个连接，服务器按照接收命令的序列依次处理并响应。所有整型值都非负的十进制数，除非有特别声明。

名称约定

所有名称必须是ASCII码字符串，即包括：

• 字母 (A-Z and a-z)
• 数字 (0-9)
• 连字符 (“-“)
• 加号 (“+”)
• 斜线 (“/“)
• 分号 (“;”)
• 点 (“.”)
• 美元符 (“$”)
• 下划线 (“_”)
• 括号 (“(“ and “)“)

注意：名称不能以连字符开始，并且是以空白字符结束，每个名称至少包含一个字符。

错误说明

job的生命周期

一个工作任务job当client使用put命令时创建。在整个生命周期中job可能有四个工作状态：ready，reserved，delayed，buried。在put之后，一个job的典型状态是ready，在ready队列中，它将等待一个worker取出此job并设置为其为reserved状态。worker占有此job并执行，当job执行完毕，worker可以发送一个delete指令删除此job。

job典型的生命周期

1

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

job可能的状态迁移

1

put with delay               release with delay----------------> [DELAYED] <------------.                      |                   |               kick   | (time passes)     |                      |                   | put                  v     reserve       |       delete-----------------> [READY] ---------> [RESERVED] --------> *poof*                     ^  ^                |  |                     |   \  release      |  |                     |    `-------------'   |                     |                      |                     | kick                 |                     |                      |                     |       bury           |                  [BURIED] <---------------'                     |                     |  delete                      `--------> *poof*

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到队列

1

put 
         
          
           
           
            \r\n
            \r\n
           
          
         
        

• <pri> 整型值，为优先级，可以为0-2^32（4,294,967,295），值越小优先级越高，默认为1024。
• <delay> 整型值，延迟ready的秒数，在这段时间job为delayed状态。
• <ttr> — time to run —整型值，允许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

响应

1

INSERTED 
        
         \r\n
        

表示插入job成功，id为新job的任务标识，整型值

1

BURIED 
        
         \r\n
        

如服务器为了增加队列的优先级而，内存不足时返回，id为新job的任务标识，整型值

1

EXPECTED_CRLF\r\n

job body必须以\r\n结尾

1

JOB_TOO_BIG\r\n

job body的长度超过max-job-size

1

DRAINING\r\n

表示服务器资源耗尽，表示服务器已经进入了“drain mode”，服务器再也不能接受连接，客户端应该使用另一个服务器或者断开稍后重试

use

说明

1

use 
        
         \r\ntube tube的名称，最大为200字节，不存在时将自动创建
        

响应

1

USING 
        
         \r\n tube为正在使用的tube名称
        

消费者指令说明（Worker Commands）

reserve

说明

1

reserve\r\n

可选的一个相似的命令

失败响应

1

DEADLINE_SOON\r\n

在一个预定的任务的运行时间内,最后一秒会被服务器保持为一个安全边际，在此期间，客户端将无法等候另外一个任务。

1

TIMED_OUT\r\n 超时

成功响应

1

RESERVED 
         
         
          \r\n
          \r\n
         
        

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

delete

说明

1

delete 
        
         \r\n
        

id为job id

release

说明

1

release 
         
          
          
           \r\n
          
         
        

id 为job id，pri为job的优先级，delay为延迟ready的秒数

bury

说明

1

bury 
         
         
          \r\n
         
        

id为job id，pri为优先级

touch

说明

1

touch 
        
         \r\n
        

id为job id

watch

说明

1

watch 
        
         \r\n
        

tube 为监控的tube名称，名称最大为200字节，如果tube不存在会自动创建

1

WATCHING 
        
         \r\n 表明成功
        

count 整型值，已监控的tube数量

ignore

说明

1

ignore 
        
         \r\n
        

tube 为移出的tube名称，名称最多为200字节，如果tube不存在会自动创建

1

WATCHING 
        
         \r\n 表明成功
        

count 整型值，已监控的tube数量

peek

说明

1

peek 
        
         \r\n  返回id对应的jobpeek-ready\r\n 返回下一个ready jobpeek-delayed\r\n 返回下一个延迟剩余时间最短的jobpeek-buried\r\n 返回下一个在buried列表中的job
        

响应

1

FOUND 
         
         
          \r\n 
          \r\n
         
        

id 为对应的job id

kick

说明

1

kick 
        
         \r\n
        

bound 整型值，唤醒的job上限

响应

1

KICKED 
        
         \r\n
        

count 为真实唤醒的job数量

1

kick-job 
        
         \r\n
        

id 为job id

stats-job

说明

1

stats-job 
        
         \r\n
        

id 为job id

1

NOT_FOUND\r\n 如果job不存在OK 
        
         \r\n
         \r\n
        

bytes 为接下来的data区块的长度

• 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

说明

1

stats-tube 
        
         \r\n
        

tube 为对应的tube的名称，最多为200字节

1

NOT_FOUND\r\n 如果tube不存在OK 
        
         \r\n
         \r\n
        

bytes 为接下来的data区块的长度

• 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

说明

1

stats\r\n

响应

1

OK 
        
         \r\n
         \r\n
        

bytes 为接下来的data区块的长度

• 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数量
• cmd-put 总共执行put指令的次数
• cmd-peek 总共执行peek指令的次数
• cmd-peek-ready 总共执行peek-ready指令的次数
• cmd-peek-delayed 总共执行peek-delayed指令的次数
• cmd-peek-buried 总共执行peek-buried指令的次数
• cmd-reserve 总共执行reserve指令的次数
• cmd-use 总共执行use指令的次数
• cmd-watch 总共执行watch指令的次数
• cmd-ignore 总共执行ignore指令的次数
• cmd-release 总共执行release指令的次数
• cmd-bury 总共执行bury指令的次数
• cmd-kick 总共执行kick指令的次数
• cmd-stats 总共执行stats指令的次数
• cmd-stats-job 总共执行stats-job指令的次数
• cmd-stats-tube 总共执行stats-tube指令的次数
• cmd-list-tubes 总共执行list-tubes指令的次数
• cmd-list-tube-used 总共执行list-tube-used指令的次数
• cmd-list-butes-watched 总共执行list-tubes-watched指令的次数
• cmd-pause-tube 总共执行pause-tube指令的次数
• job-timeouts 所有超时的job的总共数量
• total-jobs 创建的所有job数量
• max-job-size job的数据部分最大长度
• current-tubes 当前存在的tube数量
• current-connections 当前打开的连接数
• current-producers 当前所有的打开的连接中至少执行一次put指令的连接数量
• current-workers 当前所有的打开的连接中至少执行一次reserve指令的连接数量
• current-waiting 当前所有的打开的连接中执行reserve指令但是未响应的连接数量
• total-connections 总共处理的连接数
• pid 服务器进程的id
• version 服务器版本号
• rusage-utime 进程总共占用的用户CPU时间
• rusage-stime 进程总共占用的系统CPU时间
• uptime 服务器进程运行的秒数
• binlog-oldest-index 开始储存jobs的binlog索引号
• binlog-current-index 当前储存jobs的binlog索引号
• binlog-max-size binlog的最大容量
• binlog-records-written binlog累积写入的记录数
• binlog-records-migrated is the cumulative number of records written as part of compaction.
• id 一个随机字符串，在beanstalkd进程启动时产生
• hostname 主机名

list-tubes

说明

1

list-tubes\r\n

响应

1

OK 
        
         \r\n
         \r\n
        

bytes 为接下来的data区块的长度

list-tube-used

说明

1

list-tube-used\r\n

响应

1

USING 
        
         \r\n
        

tube 为tube名称

list-tubes-watched

说明

1

list-tubes-watched\r\n

响应

1

OK 
        
         \r\n
         \r\n
        

bytes 为接下来的data区块的长度

quit

说明

1

quit\r\n

pause-tube

说明

此指令针对特定的tube内所有新的job延迟给定的秒数

格式

1

pause-tube 
         
         
          \r\n
         
        

响应

1

PAUSED\r\n 表示成功NOT_FOUND\r\n tube不存在

原创翻译，英文能力此水平，见谅。By PHPboy.