Gearman协议(翻译)

Gearman协议(翻译)
2011年06月19日
　　Gearman  协议工作于TCP 之上，默认使用4730 端口。它之前使用端口7003,  但与AFS 的端口范围冲突，4730 端口是由IANA 分配的。client 和job server 间，以及worker 与job server 间存在通信交互，这两种情况下的通信协议都是由请求包和响应包组成。所有发送到job server 的包都认为是请求，所有由job server 发送的包都认为是响应。一种简单的配置例子是这样的:
　　---------- ---------- ---------- ----------
　　| Client | | Client | | Client | | Client |
　　---------- ---------- ---------- ----------
　　\             /             \          /
　　\          /               \        /
　　-------------- --------------
　　| Job Server | | Job Server |
　　-------------- --------------
　　|                 |
　　----------------------------------------------
　　|               |              |             |
　　---------- ---------- ---------- ----------
　　| Worker | | Worker | | Worker | | Worker |
　　---------- ---------- ---------- ----------
　　初始化时，worker 向每个job server 注册其所能执行的function 。client 可以连接到一个job server 并请求运行一个任务,  然后Job server  通知每个可以执行这个任务的worker （基于worker 注册的function ）：一个新的任务来了。第一个唤醒的worker 取得该任务并执行它。
　　worker 或client 跟job server 间的所有通信都是使用二进制的。也有一个用于管理操作的基于文本行的客户端协议。正因为采用文本协议，没有必要再定制管理工具（可以用"telnet" 或"nc" ）。详见"管理协议(Administrative Protocol)" 。  二进制数据包  请求与响应封装于二进制数据包中。一个二进制数据包是由一个消息头和可选的后续数据组成。消息头的构成：
　　4  字节 魔数：请求包是 "\0REG" ，响应包是 "\0RES"
　　4  字节 类型：大端存储( 网络字节序) 的整数，数据包的类型。可取值： 序号 包类型 魔数 通信端 1 CAN_DO REQ Worker 2 CANT_DO REQ Worker 3 RESET_ABILITIES REQ Worker 4 PRE_SLEEP REQ Worker 5 (unused) - - 6 NOOP RES Worker 7 SUBMIT_JOB REQ Client 8 JOB_CREATED RES Client 9 GRAB_JOB REQ Worker 10 NO_JOB RES Worker 11 JOB_ASSIGN RES Worker 12 WORK_STATUS REQ Worker     RES Client 13 WORK_COMPLETE REQ Worker     RES Client 14 WORK_FAIL REQ Worker     RES Client 15 GET_STATUS REQ Client 16 ECHO_REQ REQ Client/Worker 17 ECHO_RES RES Client/Worker 18 SUBMIT_JOB_BG REQ Client 19 ERROR RES Client/Worker 20 STATUS_RES RES Client 22 SET_CLIENT_ID REQ Worker 23 CAN_DO_TIMEOUT REQ Worker 24 ALL_YOURS REQ Worker 25 WORK_EXCEPTION REQ Worker     RES Client 26 OPTION_REQ REQ Client/Worker 27 OPTION_RES RES Client/Worker 28 WORK_DATA REQ Worker     RES Client 29 WORK_WARNING REQ Worker     RES Client 30 GRAB_JOB_UNIQ REQ Worker 31 JOB_ASSIGN_UNIQ RES Worker 32 SUBMIT_JOB_HIGH_BG REQ Client 33 SUBMIT_JOB_LOW REQ Client 34 SUBMIT_JOB_LOW_BG REQ Client 35 SUBMIT_JOB_SCHED REQ Client 36 SUBMIT_JOB_EPOCH REQ Client 4  字节长度：大端存储( 网络字节序) 的整数，指示消息头后的数据长度。  位于数据部分的参数由一个NULL 字节分隔，最后一个参数由最后一个NULL 分隔符后的数据长度决定。所有的任务句柄(job handle)  参数都不能超过64 字节，包括NULL 终止符。
　　Client/Worker 请求
　　这部分请求类型可以由client 或worker 发送：
　　ECHO_REG  当job server 收到这个请求后，它会发送一个ECHO_RES 包，包含（发送的）数据。这主要用于测试或调试。  参数： Client/Worker 响应 这部分响应可以发送到client 或worker ：
　　ECHO_RES  这是作为ECHO_RES 的请求的响应。服务器不会解析或改变数据参数，只是简单地回传。  参数 ERROR  当服务器发现错误时发送这种数据包通告client 或worker 。  参数： Client 请求 这部分请求只可以由client 发送：
　　SUBMIT_JOB, SUBMIT_JOB_BG,
　　SUBMIT_JOB_HIGH, SUBMIT_JOB_HIGH_BG,
　　SUBMIT_JOB_LOW, SUBMIT_JOB_LOW_BG
　　client 发送其中一个来发起任务请求。服务器会分配一个任务句柄(job handle) 并发送JOB_CREATED 包作为响应。
　　如果使用了BG 系列的包，client 不会得到任务状态信息或任务完成通知（它已与服务器脱离）。
　　Gearman job server 队列实现了三种级别：normal, high, low 。由HIGH 系列提交的任务总是有较高优先级，普通系列提交的任务比由LOW 系列提交的优先。
　　参数： SUBMIT_JOB_SCHED  与SUBMIT_JOB_BG 相似，但在指定的时间执行任务，而不是立即执行。这在当前并没有使用，并且有可能被去除。  参数： 以NULL 终止的function   以NULL 终止的唯一ID 以NULL 终止的分钟 (0-59) 以NULL 终止的小时(0-23) 以NULL 终止的日(1-31) 以NULL 终止的月(1-12) 以NULL 终止的周(0-6, 0 是周一) 透传数据，作为function 的参数 SUBMIT_JOB_EPOCH  与SUBMIT_JOB_BG 相似，但在指定的时间执行任务，而不是立即执行。这在当前并没有使用，并且有可能被去除。  参数： GET_STATUS  Client 发送此来获取提交任务的状态信息。  参数： OPTION_REQ  Client 通过此来设置与job server 的连接选项。成功时返回OPTION_RES 包，失败时返回ERROR 包。  参数： Client 响应 这部分响应只发送到client 。
　　JOB_CREATED  这作为SUBMIT_JOB* 包的响应。它告示client 任务已由服务器成功接收并排队由worker 运行。  参数： WORK_DATA, WORK_WARNING, WORK_STATUS, WORK_COMPLETE, WORK_FAIL, WORK_EXCEPTION  对于非后台任务，服务器转发这些来自worker 包到client 。更多信息及参数格式请参见 "Worker 请求"。
　　STATUS_RES  这作为对GET_STATUS 请求的响应。这用于一个以SUBMIT_JOB_BG 提交任务的client 来得知任务是否完成，如果没有的话，得到完成的百分比。  参数： NULL 终止的任务句柄 NULL 终止的状态，0 (false), 1(true) NULL 终止的运行状态， 0 (false), 1(true) NULL 终止的百分比分子 百分比分母 OPTION_RES  是OPTION_RES 请求的成功响应。  参数： 选项的名称，参见 OPTION_REQ 的可取值。 Worker 请求 这部分请求只能由worker 发送：
　　CAN_DO  发送到server 告知worker 可以执行给定的function 。然后此worker 被放入一个列表中，当job server 收到一个该function 类型的job 时唤醒该列表的worker 。  参数： CAN_DO_TIMEOUT  与CAN_DO 相似，但带有超时值，表示该任务可以运行多长时间。在超时后，job server 会标记该任务为失败，并且告知所有监听的client 。  参数： CANT_DO  这告知服务器该worker 已经不能再执行该function 。  参数： RESET_ABILITIES  这告知服务器该worker 已不再能执行此前任一由CAN_DO 和CAN_DO_TIMEOUT 注册的function 。  参数：  无
　　PRE_SLEEP  这告知服务器该worker 将进入睡眠状态，如果一个可由该worker 执行的任务到来，应该发送一个NOOP 包来唤醒它。  参数：  无
　　GRAB_JOB
　　向服务器请求一个的有效的队列任务。服务器会根据是否有一个有效任务返回NO_JOB 或JOB_ASSIGN 。
　　参数：
　　无
　　GRAB_JOB_UNIQ  与GRAB_JOB 相似，不同之处在于当有一个任务时返回JOB_ASSIGN_UNIQ 。  参数
　　无
　　WORK_DATA  用于向client 返回运行任务的最新数据。当运行长任务时，worker 应该用此来发送更新，发送部分结果，或刷新数据。它也可用于分割结果数据，这样worker 不必在发送WORK_COMPLETE 包前缓存整个结果集。  参数： WORK_WARNING  这发送一个告警状态更新给client 。这与WORK_DATA 相似，但这应被视为是一种警告数据，而不是普通的返回数据。 WORK_STATUS  这发送一个运行任务状态更新到服务器（和任何监听的客户端）。对于长任务，worker 应该周期性地发送它来更新完成的百分比。Job server  应该保存这种信息，这样一个提交了后台任务的客户端可以通过GET_STATUS 请求获取它。  参数： WORK_COMPLETE  告知服务器（和任何监听的客户端）任务已成功完成。  参数： WORK_FAIL  告知服务器（和任何监听的客户端）任务失败。 WORK_EXCEPTION  告知服务器（和任何监听的客户端）任务异常。  参数： SET_CLIENT_ID  向job server 设置 worker ID ，这样监控和报告命令可以唯一标识不同的worker ，以及来自同一个worker 的到job server 的不同连接。  参数： ALL_YOURS  还没有实现。这似乎是用来告知job server 这是该worker 连接的唯一job server ，所以一个任务可以直接通过JOB_ASSIGN 给worker ，不需要唤醒机制。  参数：  无
　　Woker 响应
　　这部分响应只发送给worker ：
　　NOOP  用于唤醒一个正在睡眠的worker ，这样它可以去获取一个正挂起的任务。  参数：  无
　　NO_JOB  这用作GRAB_JOB 请求的响应，告知worker 没有需要运行任务。  参数：  无
　　JOB_ASSIGN  这用作GRAB_JOB 请求的响应，给worker 运行该任务的必需的信息。所有关于此任务的通信过程（例如状态更新和完成响应）应该使用此句柄，并且worker 必须用指定的参数运行所给的function 。  参数： JOB_ASSIGN_UNIQ  此用作GRAB_JOB_UNIQ 请求的响应，并和JOB_ASSIGN 的行为类似，但带有client 设置的唯一标识。  参数： 管理协议
　　Gearman job server 也支持文本行协议来提取信息和运行一些管理任务。它运行于与二进制协议相同的端口，server 用第一个字符来区分这两种协议：如果它是NULL(\0) 则是二进制的，如果是非NULL 则尝试解析成文本命令。以下是支持 的命令：
　　workers  回送一个worker 列表，它们的文件描述符、IP 、ID 和可执行的注册函数列表。这个列表终止于由一个点"." 组成的行。格式是：
　　FD IP-ADDRESS CLIENT-ID : FUNCTION ...  参数：  无
　　status  回送一个所有注册函数的列表。在function 后的是队列中的任务数，正在运行的任务数，以及有该功能的worker 数。列间以tab 分隔。这个列表终止于由一个点"." 组成的行。格式是：
　　FUNCTION\tTOTAL\tRUNNING\tAVAILABLE_WORKERS
　　参数：
　　无
　　maxqueue  设置该function 的最大队列长度。如果没有指定大小，使用默认大小。如果大小是负值，则队列是无限大的。一个由"OK" 组成的单行作为响应。  参数： shutdown  关闭服务器。如果使用了可选参数"graceful" ，关闭监听连接，等待正关闭的连接完成。
　　参数： version  返回服务器的版本号。  参数：  无
　　Perl 版本还有一个"gladiator" 命令，它使用"Devel::Gladiator" Perl 模块，用于调试。
　　二进制协议例子
　　该例子会逐步察看一个交互过程：worker 连接并注册一个叫"reverse" 的function ，client 连接并提交一个该function 的任务，worker 执行该任务并返回一个结果。这显示了要完成一个任务所需发送的每个字节。
　　worker 注册：
　　Worker -> Job Server
　　00 52 45 51 \0REQ (Magic)
　　00 00 00 01 1 (Packet type: CAN_DO)
　　00 00 00 07 7 (Packet length)
　　72 65 76 65 72 73 65 reverse (Function)
　　Worker check for job:
　　worker 检测任务：
　　Worker -> Job Server
　　00 52 45 51 \0REQ (Magic)
　　00 00 00 09 9 (Packet type: GRAB_JOB)
　　00 00 00 00 0 (Packet length)
　　Job Server -> Worker
　　00 52 45 53 \0RES (Magic)
　　00 00 00 0a 10 (Packet type: NO_JOB)
　　00 00 00 00 0 (Packet length)
　　Worker -> Job Server
　　00 52 45 51 \0REQ (Magic)
　　00 00 00 04 4 (Packet type: PRE_SLEEP)
　　00 00 00 00 0 (Packet length)
　　Client job submission:
　　Client -> Job Server
　　00 52 45 51 \0REQ (Magic)
　　00 00 00 07 7 (Packet type: SUBMIT_JOB)
　　00 00 00 0d 13 (Packet length)
　　72 65 76 65 72 73 65 00 reverse\0 (Function)
　　00 \0 (Unique ID)
　　74 65 73 74 test (Workload)
　　Job Server -> Client
　　00 52 45 53 \0RES (Magic)
　　00 00 00 08 8 (Packet type: JOB_CREATED)
　　00 00 00 07 7 (Packet length)
　　48 3a 6c 61 70 3a 31 H:lap:1 (Job handle)
　　唤醒Worker:
　　Job Server -> Worker
　　00 52 45 53 \0RES (Magic)
　　00 00 00 06 6 (Packet type: NOOP)
　　00 00 00 00 0 (Packet length)
　　Worker 检测任务:
　　Worker -> Job Server
　　00 52 45 51 \0REQ (Magic)
　　00 00 00 09 9 (Packet type: GRAB_JOB)
　　00 00 00 00 0 (Packet length)
　　Job Server -> Worker 00 52 45 53 \0RES (Magic) 00 00 00 0b 11 (Packet type: JOB_ASSIGN) 00 00 00 14 20 (Packet length) 74 65 73 74 test (Workload) Worker  对任务的响应:
　　Worker -> Job Server
　　00 52 45 51 \0REQ (Magic)
　　00 00 00 0d 13 (Packet type: WORK_COMPLETE)
　　00 00 00 0c 12 (Packet length)
　　48 3a 6c 61 70 3a 31 00 H:lap:1\0 (Job handle)
　　74 73 65 74 tset (Response)
　　Job server  对client 的响应:
　　Job Server -> Client
　　00 52 45 53 \0RES (Magic)
　　00 00 00 0d 13 (Packet type: WORK_COMPLETE)
　　00 00 00 0c 12 (Packet length)
　　48 3a 6c 61 70 3a 31 00 H:lap:1\0 (Job handle)
　　74 73 65 74 tset (Response)
　　至此，worker 可以请求更多的任务来运行，client 也可以提交更多的任务。注意，client 是完全多路复用的，可能在一个socket 上同时运行多个任务。结果包可能不是以任务所提交的顺序来发送，而与其它任务的结果包交错在一起。