Beanstalk Protocol 摘记

协议概况

  • beanstalk protocol 是建立在TCP之上的应用层协议。
  • 协议采用ASCII编码
  • 针对每一个连接，服务端按照接收指令的次序处理和发送响应。
  • 协议中所有整型都已十进制小数表示（除非另作说明），并且非负数
  • 协议中的名称都是ASICC字符串，由 a-zA-Z0-9-+/;.$_() 组成，但是不能以减号开头，以空字符或者换行结束，每个名称至少一个字符。
  • 协议包含两种数据
    • 行文本，被用作：
      • 客户端指令
      • 服务端响应
    • 非结构化数据块，被用作：
      • 传递job体（一段字节序列）
      • 传递统计信息
  • 服务端不对job体做任何检查或修改，总会按其原有格式返回
  • 客户端负责解析job体
  • 当结束连接时客户端发送“quit”指令，或者直接断开tcp连接即可
  • beanstalkd 支持大量连接，因此最好的做法是客户端保持连接，并尽量复用。
  • 当客户端发送协议错误或者服务端出错时会报出下面中的一个错误：
    • OUT_OF_MEMORY 服务端无法为job分配足够的内存。
    • INTERNAL_ERROR 服务器内部错误，一般不会发生。
    • BAD_FORMAT 客户端发送的指令格式非法。
    • UNKNOWN_COMMAND 指令不存在
  • 当服务端发生错误无法继续服务于当前客户端时，将主动关闭连接

 

Job 生命周期

job由客户端通过“put”指令创建。 job生命周期中的四个状态：

  • ready
  • reserved
  • delayed
  • buried

状态变化：

put                reserve                    delete

—–> [READY] ———> [RESERVED] ——–> *poof*

 

 

  • beanstalk系统可以有一个或多个tube
  • 每一个tuple由一个ready 队列和一个 delay 队列组成
  • 每个job的生命周期都在一个tube内流转
  • consumer可以发送“watch”，“ignore”来关注或忽略一个tube。
  • 设置“watch”的tube将进入consumer的watch list
  • consumer可以获取其watch list 中的任意一个tube的job
  • 当客户端建立连接，watch list中会有一个名为default的默认tube
  • 客户端提交job前如果未使用“use”指令，job则被放入默认tube（default）
  • tube在被引用时按需创建
  • 如果tube为空（不存在任何 ready,delay,buried jobs）且 没有客户端引用，则被删除

 

Producer 指令

put

用来将job插入客户端当前tube的队列 格式如下： put <pri> <delay> <ttr> <bytes>\r\n<data>\r\n

  • <pri> 优先级（priority） < 2^32 ，数字越小优先级越高，最高优先级0，最低 4,294,967,295
  • <delay> 单位秒，整型；表示延迟多少时间将job放入ready队列，job状态为delayed
  • <ttr> 单位秒，整型；允许worker执行job的超时时间。从worker reserve一个job开始计时
    • 如果worker执行超时（指定时间内未 release\delete\bury）服务端将release job。
    • 最小时间1s，客户端设置0，服务端会自动置为1
  • <bytes> 整型数字，表示<body>部分字节大小，不包含\r\n，必须小于 max-job-size(默认2^16)
  • <data> job体，啥内容都可以，服务端不关心

服务端响应

  • “INSERTED <id>\r\n” 表示执行成功，<id> 新put的job id，整型
  • “EXPECTED_CRLF\r\n” 表示job体少了”\r\n” 这个两个字符不计入<bytes>
  • “JOB_TOO_BIG\r\n” job体大于max-job-size
  • “DRAINING\r\n” 服务端处于饱和状态，无法接收新job

use

格式如下： use <tube>\r\n < tube>最长200字节的名字，不存在则（服务端）创建

服务端响应：

USING <tube>\r\n

 

Worker 指令

欲从服务端队列中消费job的进程。

消费动作包括：reserve\delete\release\bury

reserve

指令格式（两种）

  • reserve\r\n
  • reserve-with-timeout <seconds>\r\n

服务端响应：

  • 如果没有可用job，则会一直阻塞。
  • 当获得可用job，如果时间超过<ttr>设置，服务端会被job放回ready队列。
  • 可以使用stats-job 来获取job的实际可用时间以及设置的<ttr>
  • reserved状态job的<ttr>的最后一秒被服务端用作安全边界。
  • 在这一秒内，reserve 该job的客户端无法请求其他job。
  • 如果在这一秒内，客户端发起reserve或者在之前发起，但在这一秒还没有返回，服务端返回：
    • DEADLINE_SOON\r\n
  • 当使用reserve-with-timeout 并设置了一个非负值，超时后返回TIMED_OUT\r\n
  • 其他情况将是正常响应，服务端返回：RESERVED <id> <bytes>\r\n<data>\r\n
    • <id> job id
    • <bytes> job body length
    • <data> job body

delete

指令格式：

delete <job_id>\r\n

服务端响应：

  • DELETED\r\n 表示成功
  • NOT_FOUND\r\n job不存在

release

指令格式：

release <id> <pri> <delay>\r\n

  • <id> job id
  • <pri> priority 可以重置优先级
  • <delay>

服务端响应：

  • RELEASED\r\n 表示成功
  • BURIED\r\n 服务端没有足够内存将job放入优先级队列数据结构中
  • NOT_FOUND\r\n job不存在

bury

指令格式：

bury <id> <pri>\r\n

服务端响应：

BURIED\r\n 表示成功

NOT_FOUND\r\n job不存在，或者是当前客户端并未获取该job

 

touch

告诉服务端用来延长当前执行的job

指令格式：

touch <id>\r\n

<id> 被当前连接reserved的job id

服务端响应：

TOUCHED\r\n 表示成功

NOT_FOUND\r\n 不存在，或job未被当前客户端reserve

watch

指令格式：

watch <tube>\r\n

服务端响应：

WATCHING <count>\r\n

<count>表示现在在watch list中的数量

ignore

从watch list中移除tube

指令格式：

ignore <tube>\r\n

服务端响应：

WATCHING <count>\r\n 表示成功

NOT_IGNORED\r\n 试图移除watch list 中最后一个tube

peek

客户端预览服务端的job情况

  1. peek <id>\r\n
  2. peek-ready\r\n
  3. peek-delayed\r\n
  4. peek-buried\r\n

服务端响应：

1. NOT_FOUND\r\n job不存在，或者没有指定状态的job

2. FOUND <id> <bytes>\r\n<data>\r\n

kick

只作用域当前使用的tube，将job从buried转移到ready

  • 如果存在buried jobs 则只转移 buried jobs
  • 如果不存在buried jobs，则转移 delayed jobs

指令格式：

kick <bound>\r\n

<bound> 整型，表示要kick的job数量

服务端响应：

KICKED <count>\r\n

<count> 表示实际被kicked的job数量

stats-job

获取某一个job的相关信息

指令格式：

stats-job <id>\r\n

服务端响应：

  • NOT_FOUND\r\n
  • OK <bytes>\r\n<data>\r\n

<data> 是一个yaml (什么是YAML)文件，包含下面的key

  • id – job id
  • tube – 包含该job的tube名称
  • state – ready, delayed, reserved, buried
  • pri – job 的优先级
  • age – job 被创建的时间，单位秒
  • time-left – 距离被放入ready队列的时间，只针对buried,delayed状态的job
  • reserves – 被预订的次数
  • timeouts – 超时次数
  • release – 被释放的次数
  • buries – 被隐藏的次数
  • kicks – 被kick的次数

stats-tube

获取某一个tube的信息

指令格式：

status-tube <tube>\r\n

服务端响应：

  • NOT_FOUND\r\n
  • OK <bytes>\r\n<data>\r\n

<data> 是一个yaml 文件，包含下面的key

  • name : tube名称
  • current-jobs-urgent: 优先级小于1024的ready状态job数量
  • current-jobs-ready:ready状态job数量
  • current-jobs-reserved: reserved状态job数量
  • current-job-delayed:delayed状态job数量
  • current-job-buried:buried状态job数量
  • total-jobs: job总数
  • current-waiting:阻塞在reserve指令的连接数
  • pause: tube被暂停的时间，单位：秒
  • cmd-pause-tube:tube被暂停的次数
  • pause-time-left: 距离暂停结束的时间，单位：秒

stats

获得全局状态

指令格式：

status\r\n

服务端响应：

OK <bytes>\r\n<data>\r\n

<data> 是一个yaml 文件，包含下面的key

  • current-jobs-urgent: 优先级小于1024的ready状态job数量
  • current-jobs-ready:ready状态job数量
  • current-jobs-reserved: reserved状态job数量
  • current-job-delayed:delayed状态job数量
  • current-job-buried:buried状态job数量
  • cmd-指令名称 : 累指令执行次数
  • job-timeouts : 累计job超时次数
  • total-jobs: 累计job数
  • max-job-size: job<bytes>最大值
  • current-tubes: tubes数量
  • current-connections: 当前打开的连接数
  • current-producers : 连接中至少执行过一次put的数量
  • current-workers: 连接中至少执行过一次reserve的数量
  • current-waiting: 当前阻塞在reserve指令中的连接数量
  • total-connections: 累计的连接数量
  • pid : 服务端进程id
  • version ： 服务端版本
  • rusage-utime:
  • rusage-stime:
  • uptime:
  • binlog-oldest-index:
  • binlog-current-index:
  • binlog-max-size:

list-tubes，list-tube-used, list-tube-watched

指令格式：

list-tubes\r\n

服务端响应：

OK <bytes>\r\n<data>\r\n

<data> 是一个yaml 文件，包含tube名称的一个数组

quit

客户端断开连接

pause-tube

暂停某一个tube，在delay期内tube内的job无法被预订。

指令格式：

pause-tube <tube> <delay>\r\n

服务端响应：

  • PAUSED\r\n
  • NOT_FOUND\r\n

查看原文

posted on 2012-01-31 19:41  panzh  阅读(832)  评论(0)  编辑  收藏  举报