Gearman入门学习

Gearman协议

Gearman协议工作于TCP之上，默认使用4730端口。它之前使用端口7003,但与AFS的端口范围冲突，4730端口是由IANA分配的。client和jobserver间，以及worker与jobserver间存在通信交互，这两种情况下的通信协议都是由请求包和响应包组成。所有发送到jobserver的包都认为是请求，所有由jobserver发送的包都认为是响应。

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上同时运行多个任务。结果包可能不是以任务所提交的顺序来发送，而与其它任务的结果包交错在一起。

Gearman使用说明

安装Gearman

一、安装gearman服务

1.安装libevent
tar zxvf libevent-1.4.14b-stable.tar.gz
cd libevent-1.4.14b-stable
./configure & make & make install

2.安装gearmand
tar xzvf gearmand-0.14.tar.gz
cd gearmand-0.14

./configure --prefix=/usr/local/gearman & make & make install

安装中的错误及解决：

configure: error: could not find boost 错误解决
#yum install boost-devel*
configure: error: could not find gperf 错误解决
#yum install gperf*
configure: error: Unable to find libuuid 错误解决
#yum install libuuid-devel
上面错误的原因是编译器找不到 头文件

mkdir /usr/local/gearman/log
/usr/local/gearman/sbin/gearmand -l /usr/local/gearman/log/trace.log -vvvvv -p 4730 -u root -d

3.安装gearman php扩展

版本依赖关系：gearm C lib为0.14版本的，PHP为5.3.6，其它版本不能保证安装成功

tar xzvf gearman-0.7.0.tgz
cd gearman-0.7.0
/usr/local/php/bin/phpize
./configure --with-gearman=/usr/local/gearman --with-php-config=/usr/local/php/bin/php-config & make & make install
cp /usr/local/gearman/lib/lib* /usr/lib64(32位机为/usr/lib)
vi /usr/local/php/lib/php.ini，增加extension=gearman.so

cd examples
php ./reverse_worker.php
--Starting
--Waiting for job...

php ./reverse_client.php
--Starting
--Sending job
--Success: !olleH

gearman安装成功

4.编译C程序jfy_client.c,jfy_worker.c
/*
  gearman worker 测试程序
  gcc -I/usr/local/mysql/include -I/usr/local/gearman/include -c jfy_worker.c _pub.c
  gcc -o jfy_worker jfy_worker.o _pub.o -L/usr/local/mysql/lib -lmysqlclient -L/usr/local/gearman/lib -lgearman
  ./jfy_worker ./jfy_worker.tr
*/

/*
  gearman client 测试程序
  gcc -I/usr/local/gearman/include -c jfy_client.c
  gcc -o jfy_client jfy_client.o -L/usr/local/gearman/lib -lgearman
  ./jfy_client "this is a test"
*/

二、安装网页监控工具
1.安装Net_Gearman包
方法一：
http://download.pear.php.net/package/Net_Gearman-0.2.3.tgz
tar xzvf Net_Gearman-0.2.3.tgz
拷贝Net_Gearman-0.2.3下的Net目录到/usr/local/php/lib/php下

方法二：
/usr/local/php/bin/pear list
Installed packages, channel pear.php.net:
=========================================
Package          Version State
Archive_Tar      1.3.7   stable
Console_Getopt   1.3.0   stable
PEAR             1.9.2   stable
Structures_Graph 1.0.4   stable
XML_Util         1.2.1   stable

/usr/local/php/bin/pear install Net_Gearman-0.2.3

2.安装Gearman-Monitor
https://github.com/yugene/Gearman-Monitor/zipball/master
解压yugene-Gearman-Monitor-ed34347.zip
将所有内容放到网站能访问php的路径下
修改其下的_config.php文件
$cfgServers[$i]['address'] = 'localhost:4730';   //IP端口
$cfgServers[$i]['name'] = 'Gearman server 1';    //服务名(自定义)

通过网页访问:http://localhost:8084/phptest/Gearman-Monitor/index.php

Gearman使用

gearmand

这个是Job Server的执行主进程，提供了以下参数

General options:
  -b [ --backlog ] arg (=32)            Number of backlog connections for 
                                        listen.
  -d [ --daemon ]                       Daemon, detach and run in the 
                                        background.
  -f [ --file-descriptors ] arg         Number of file descriptors to allow for
                                        the process (total connections will be 
                                        slightly less). Default is max allowed 
                                        for user.
  -h [ --help ]                         Print this help menu.
  -j [ --job-retries ] arg (=0)         Number of attempts to run the job 
                                        before the job server removes it. This 
                                        is helpful to ensure a bad job does not
                                        crash all available workers. Default is
                                        no limit.
  -l [ --log-file ] arg (=/usr/local/var/log/gearmand.log)
                                        Log file to write errors and 
                                        information to. If the log-file 
                                        paramater is specified as 'stderr', 
                                        then output will go to stderr
  -L [ --listen ] arg                   Address the server should listen on. 
                                        Default is INADDR_ANY.
  -p [ --port ] arg (=4730)             Port the server should listen on.
  -P [ --pid-file ] arg (=/usr/local/var/gearmand.pid)
                                        File to write process ID out to.
  -r [ --protocol ] arg                 Load protocol module.
  -R [ --round-robin ]                  Assign work in round-robin order per 
                                        worker connection. The default is to 
                                        assign work in the order of functions 
                                        added by the worker.
  -q [ --queue-type ] arg               Persistent queue type to use.

  #队列持久化类型，libdrizzle=mysql,libmemcached=memcached,libsqlite3=sqlite,libpq=postgresql,libtokyocabinet=tokyocabinet

  --config-file arg (=/usr/local/etc/gearmand.conf)
                                        Can be specified with '@name', too
  --syslog                              Use syslog.
  -t [ --threads ] arg (=4)             Number of I/O threads to use. 
                                        Default=4.
  -u [ --user ] arg                     Switch to given user after startup.
  --verbose arg (=ERROR)                Set verbose level (FATAL, ALERT, 
                                        CRITICAL, ERROR, WARNING, NOTICE, INFO,
                                        DEBUG).
  -V [ --version ]                      Display the version of gearmand and 
                                        exit.
  -w [ --worker-wakeup ] arg (=0)       Number of workers to wakeup for each 
                                        job received. The default is to wakeup 
                                        all available workers.

-b, --backlog= 储备的监听连接数量
-d, --daemon 后台运行
-f, --file-descriptors= 文件描述符的数量
-h, --help 帮助
-j, --job-retries= 在job server移除不可用job之前运行的次数，防止不断运行导致其他可用worker崩溃。默认没有限制
-l, -log-file= 日志文件存放位置(默认记录最简单日志)
-L, --listen= 监听的IP，默认全部接受
-p, --port= 指定监听端口
-P, --pid-file= 指定进程ID写入位置
-r, --protocol= 加载协议模块
-q, --queue-type= 指定持久化队列
-t, --threads= 使用的I/O线程数量。默认为0
-u, --user= 启动后，切换到指定用户
-v, --verbose 增加一级详细程度
-V, --version 显示版本信息

HTTP:
  --http-port arg (=8080) Port to listen on.

#下面是针对--queue-type不同类型时的不同参数
libsqlite3:
  --libsqlite3-db arg                   Database file to use.
  --libsqlite3-table arg (=gearman_queue)
                                        Table to use.

gearmand还有一些其它参数选项，取决于编译时带的参数，如--with-libdrizzle和--with-libmemcached，可以将队列放到MySQL或Memcached中

一般正常使用如下：

/usr/local/sbin/gearmand -l /usr/local/gearman/log/trace.log --verbose INFO -p 4730 -d

gearman

这个模拟client和server的gearman程序

Client mode: gearman [options] [<data>]
Worker mode: gearman -w [options] [<command> [<args> ...]]

Common options to both client and worker modes.
        -f <function> - Function name to use for jobs (can give many)
        -h <host>     - Job server host
        -H            - Print this help menu
        -p <port>     - Job server port
        -t <timeout>  - Timeout in milliseconds
        -i <pidfile>  - Create a pidfile for the process

Client options:
        -b            - Run jobs in the background
        -I            - Run jobs as high priority
        -L            - Run jobs as low priority
        -n            - Run one job per line
        -N            - Same as -n, but strip off the newline
        -P            - Prefix all output lines with functions names
        -s            - Send job without reading from standard input
        -u <unique>   - Unique key to use for job

Worker options:
        -c <count>    - Number of jobs for worker to run before exiting
        -n            - Send data packet for each line
        -N            - Same as -n, but strip off the newline
        -w            - Run in worker mode

如：

#session1

gearman -w -f func1 &

#这实际上就启动了一个worker，并注册一个函数func1在Job Server上

#session2

gearman -I -f func1 test

#这时session1那边就会显示一个"test"

gearadmin

该工具是在0.33版本以后增加的功能

Options:
  --help                         Options related to the program.
  -h [ --host ] arg (=localhost) Connect to the host
  -p [ --port ] arg (=4730)      Port number or service to use for connection
  --server-version               Fetch the version number for the server.
  --server-verbose               Fetch the verbose setting for the server.
  --create-function arg          Create the function from the server.
  --drop-function arg            Drop the function from the server.
  --getpid                       Get Process ID for the server.
  --status                       Status for the server.
  --workers                      Workers for the server.
  --shutdown                     Shutdown server.

command line

用telnet直接连接gearmand，可以以命令行的方式查看Job Server状态

telnet localhost 4830
Trying 127.0.0.1...
Connected to localhost.localdomain (127.0.0.1).
Escape character is '^]'.

workers

30 127.0.0.1 - : jfytest jfytest2    #显示连接的worker及注册的函数

status
jfytest          0       0       1       #某个函数的客户端队列请求
jfytest2        0       0       1       #Function Name，Jobs in queue，Jobs running，Workers registered

maxqueue jfytest 10000        #设置某个函数最大队列数，如果只有两个参数则不限制
OK

version
OK 0.33

shutdown graceful                #graceful代表优雅关闭，否则强制关闭，不管队列状态
OK

verbose                                #当前log级别
OK INFO