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