beanstalk队列服务for php

beakspeak是一个基于beakstalk队列服务的php-c扩展，高性能支持分布式内存队列服务，且很轻量级。

目前国内还没有比较详细的关于Beanspeak的中文说明，本文是根据源码提炼、整理的一份中文文档。

Beanstalk特性

1. 高性能，内存操作
2. 持久化，通过binlog来记录和恢复job状态
3. 优先级，支持0-2**32优先级，默认1024
4. 精确的超时控制

至于Beanstalk的安装这里不赘述，主要整理一下Beanspeak for php扩展的使用说明。

Queue Usage

$queue = new Client([
    'host'       => '127.0.0.1', // beanstalk服务地址
    'port'       => 11300,       // Beanstalk端口
    'timeout'    => 60,          // 连接超时时间
    'persistent' => true,        // 是否长连接
    'wretries'   => 8,           // 连接重试次数
]);

注意这里的timeout指的是通过socket连接Beanstalk服务的超时时间，建立连接后并没有设置超时时间，相当于长连接。

connect()

返回一个socket长连接资源

$queue->connect();

return resource

disconnect()

关闭socket连接

$quere->disconnect();

return boolean

isConnected()

连接是否已成功建立

$quere->isConnected();

return boolean

put()

将任务放进默认的tube

$task = [
    'recipient' => 'user@mail.com',
    'subject'   => 'Welcome',
    'content'   => $content,
];

$queue->put($task, 999, 60 * 60, 3600);

return：int|boolean，jobid
data：array，job所需数据
priority：int，优先级，默认1024，值越小优先级越高，取值范围0-2^32（4,294,967,295）
delay：int，延迟时间，在这段时间job为delayed状态
ttr：int，允许worker执行的最大秒数，如果worker在这段时间不能delete，release，bury job，那么job超时，服务器将release此job，此job的状态迁移为ready。最小为1秒，如果客户端指定为0将会被重置为1。

putInTube()

将job放到指定tube

$task = [
    'recipient' => 'user@mail.com',
    'subject'   => 'Welcome',
    'content'   => $content,
];

$queue->putInTube('tube-name', $task, 999, 60 * 60, 3600);

return：boolean|int
tube：string，tube name，管道名称
data：array，job数据
priority：int，优先级
delay：int，延迟执行时间
ttr：int，超时时间

useTube()

切换当前tube

$queue->useTube('tube name');

return：this，client对象
tube：string，tube name

peekJob()

查看指定job

$job = $queue->peek($jobId);

return false|job object
id：int，job id

peekDelay()

查看最短延迟的job

$queue->peekDelayed();

return false|job object

peekBuried()

查看下一个buried的job

$queue->peekBuried();

return false|job object

peekReady()

查看下一个ready的job

$queue->peekReady();

return false|job object

kick()

将当前tube里的job踢回队列，将buried状态改为ready或delayed

$queue->kick(3);

return：false|int，实际唤醒的数量
bound：int，唤醒的job上限

watch()

添加监控的tube到watch list列表，reserve指令将会从监控的tube列表获取job

$queue->watch($tube);

return：this，client对象
tube：string，tube name

watchOnly()

添加监控的tube到watch list列表，同时忽略除当前指定tube外的任何tube

$queue->watchOnly($tube);

return：this，client对象
tube：string，tube name

reserve()

从默认tube里取出job，待处理

$job = $queue->reserve(-1);

return boolean|job object
timeout：int，默认为-1

reserveFromTube()

从指定tube里取出job，待处理

$job = $queue->reserveFromTube('tube name, -1');

return boolean|job object
tube：string，tube name
timeout：int，默认-1

ignore()

将指定tube从watch列表中移除

$queue->ignore('tube-name);

return this，client对象
tube：string，tube name

stats()

获取所有状态信息

$queue->stats();

return boolean|array

返回值：

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 主机名

statsTube()

获取指定stats-tube的信息

$stats = $queue->statsTube('tube name');

return boolean|array
tube：string，tube name

返回值：

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暂停剩余的秒数

listTubes()

列出所有tube

$tubes = $queue->listTubes();

return boolean|array

listTubeUsed()

输出当前被使用的tube

$tubes = $queue->listTubeUsed(); // local cache
$tubes = $queue->listTubeUsed(true); // ask server

return string，tube name
ask：boolean，ask，默认为false，访问的是本地cache，true则发送服务器请求获取即时tube

listTubesWatched()

输出当前被watch的tube

$tubes = $queue->listTubesWatched(); // local cache
$tubes = $queue->listTubesWatched(true); // ask server

return string，tube name
ask：boolean，ask，默认为false，访问的是本地cache，true则发送服务器请求获取即时tube

pauseTube()

暂停将新的job放入tube待处理

$queue->pauseTube('tube name', 60 * 60);

return boolean
tube：string，tube name
delay：暂停时间，单位为秒

resumeTube()

重启tube

$queue->resumeTube('tube name');

return boolean
tube：string，tube name

quit()

关闭客户端连接

$queue->quit();

return boolean

以上是queue相关的函数，以下是job：

Job Usage

getId()

return int，jobId

$job->getId();

getBody()

return mix，job body

$job->getBody();

delete()

删除当前job

$job->delete();

return boolean

touch()

让job有更多的时间处理请求

$job->touch();

return boolean

release()

让一个reserved job放到一个ready queue队列里

$job->release(10, 60 * 60);

return boolean
priority：优先级，默认1024
delay：int，延迟时间

bury()

将一个job放到buried列表

$job->bury()

return boolean
priority：int，默认1024

stats()

获取stats-job详细信息

$stats = $job->stats();

return boolean|array

返回值：

id 表示job id
tube 表示tube的名称
state 表示job的当前状态
pri 表示job的优先级
age 表示job创建的时间单位秒
delay 是延迟job放入ready队列的整数秒数
ttr 指允许worker执行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的次数

kick()

将当前job踢回到ready状态

$job->kick();

实例

先生产出一批待处理数据，然后加入队列。再依次将每条数据写入日志。

生产者

<?php
use Beanspeak\Client;
$client = new Client(['host'=>'x.x.x.x','post'=>11300]);
$client->connect();
$tube_name = 'tube_1';
$client->useTube($tube_name);
for ($i = 0; $i < 100; $i++) {
    $data = 'data-'.$i."\n";
    $client->put($data);
}

消费者

<?php
use Beanspeak\Client;
$client = new Client(['host'=>'x.x.x.x','post'=>11300]);
$client->connect();
$tube_name = 'tube_1';
$client->useTube($tube_name);
// watch tube
$client->watch($tube_name);
while (1) {
	// 取出待处理的job
    $job = $client->reserve();
    // jobId和jobBody可以用getId和getBody获取
    $jobBody= $job->getBody();
    $success = file_put_contents('test.log', $jobBody, FILE_APPEND);
    if ($success) {
        $job->delete();
    } else {
        $job->bury();
    }
    sleep(1);
}