Skip to content

Commit cb4205d

Browse files
author
Chris Boulton
committed
Initial commit
0 parents  commit cb4205d

37 files changed

+2808
-0
lines changed

‎CHANGELOG.markdown

+3
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,3 @@
1+
## 1.0 (2010-04-18) ##
2+
3+
* Initial release

‎LICENSE

+20
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,20 @@
1+
(c) 2010 Chris Boulton <[email protected]>
2+
3+
Permission is hereby granted, free of charge, to any person obtaining
4+
a copy of this software and associated documentation files (the
5+
"Software"), to deal in the Software without restriction, including
6+
without limitation the rights to use, copy, modify, merge, publish,
7+
distribute, sublicense, and/or sell copies of the Software, and to
8+
permit persons to whom the Software is furnished to do so, subject to
9+
the following conditions:
10+
11+
The above copyright notice and this permission notice shall be
12+
included in all copies or substantial portions of the Software.
13+
14+
THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND,
15+
EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF
16+
MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND
17+
NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE
18+
LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION
19+
OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION
20+
WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.

‎README.markdown

+198
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,198 @@
1+
php-resque: PHP Resque Worker (and Enqueue)
2+
===========================================
3+
4+
Resque is a Redis-backed library for creating background jobs, placing
5+
those jobs on multiple queues, and processing them later.
6+
7+
Resque was pioneered and is developed by the fine folks at GitHub (yes,
8+
I am a kiss-ass), and written in Ruby.
9+
10+
What you're seeing here is an almost direct port of the Resque worker
11+
and enqueue system to PHP, which I've thrown together because I'm sure
12+
my PHP developers would have a fit if they had to write a line of Ruby.
13+
14+
For more information on Resque, visit the official GitHub project:
15+
<http://github.com/defunkt/resque/>
16+
17+
And for background information, the launch post on the GitHub blog:
18+
<http://github.com/blog/542-introducing-resque>
19+
20+
The PHP port does NOT include its own web interface for viewing queue
21+
stats, as the data is stored in the exact same expected format as the
22+
Ruby version of Resque.
23+
24+
The PHP port allows for much the same as the Ruby version of Rescue:
25+
26+
* Workers can be distributed between multiple machines
27+
* Includes support for priorities (queues)
28+
* Resilient to memory leaks (fork)
29+
* Expects failure
30+
31+
In addition, it also:
32+
33+
* Has the ability to track the status of jobs
34+
* Will mark a job as failed, if a forked child running a job does
35+
not exit with a status code as 0
36+
37+
## Jobs ##
38+
39+
### Queueing Jobs ###
40+
41+
Jobs are queued as follows:
42+
43+
require_once 'Resque.php';
44+
45+
// Required if redis is located elsewhere
46+
Resque::setBackend('localhost', 6379);
47+
48+
$args = array(
49+
'name' => 'Chris'
50+
);
51+
Resque::enqueue('default', 'My_Job', $args);
52+
53+
### Defining Jobs ###
54+
55+
Each job should be in it's own class, and include a `perform` method.
56+
It's important to note that classes are called statically.
57+
58+
class My_Job
59+
{
60+
public static function perform($args)
61+
{
62+
// Work work work
63+
}
64+
}
65+
66+
Any exception thrown by a job will result in the job failing - be
67+
careful here and make sure you handle the exceptions that shouldn't
68+
result in a job failing.
69+
70+
### Tracking Job Statuses ###
71+
72+
php-resque has the ability to perform basic status tracking of a queued
73+
job. The status information will allow you to check if a job is in the
74+
queue, currently being run, has finished, or failed.
75+
76+
To track the status of a job, pass `true` as the fourth argument to
77+
`Resque::enqueue`. A token used for tracking the job status will be
78+
returned:
79+
80+
$token = Resque::enqueue('default', 'My_Job', $args);
81+
echo $token;
82+
83+
To fetch the status of a job:
84+
85+
$status = new Resque_Job_Status($token);
86+
echo $status->get(); // Outputs the status
87+
88+
Job statuses are defined as constants in the `Resque_Job_Status` class.
89+
Valid statuses include:
90+
91+
* `Resque_Job_Status::STATUS_WAITING` - Job is still queued
92+
* `Resque_Job_Status::STATUS_RUNNING` - Job is currently running
93+
* `Resque_Job_Status::STATUS_FAILED` - Job has failed
94+
* `Resque_Job_Status::STATUS_COMPLETE` - Job is complete
95+
* `false` - Failed to fetch the status - is the token valid?
96+
97+
Statuses are available for up to 24 hours after a job has completed
98+
or failed, and are then automatically expired. A status can also
99+
forcefully be expired by calling the `stop()` method on a status
100+
class.
101+
102+
## Workers ##
103+
104+
Workers work in the exact same way as the Ruby workers. For complete
105+
documentation on workers, see the original documentation.
106+
107+
A basic "up-and-running" resque.php file is included that sets up a
108+
running worker environment is included in the root directory.
109+
110+
The exception to the similarities with the Ruby version of resque is
111+
how a worker is initially setup. To work under all environments,
112+
not having a single environment such as with Ruby, the PHP port makes
113+
*no* assumptions about your setup.
114+
115+
To start a worker, it's very similar to the Ruby version:
116+
117+
$ QUEUE=file_serve php resque.php
118+
119+
It's your responsibility to tell the worker which file to include to get
120+
your application underway. You do so by setting the `APP_INCLUDE` environment
121+
variable:
122+
123+
$ QUEUE=file_serve APP_INCLUDE=../application/init.php php resque.php
124+
125+
Getting your application underway also includes telling the worker your job
126+
classes, by means of either an autoloader or including them.
127+
128+
### Logging ###
129+
130+
The port supports the same environment variables for logging to STDOUT.
131+
Setting `VERBOSE` will print basic debugging information and `VVERBOSE`
132+
will print detailed information.
133+
134+
$ VERBOSE QUEUE=file_serve php resque.php
135+
$ VVERBOSE QUEUE=file_serve php resque.php
136+
137+
### Priorities and Queue Lists ###
138+
139+
Similarly, priority and queue list functionality works exactly
140+
the same as the Ruby workers. Multiple queues should be separated with
141+
a comma, and the order that they're supplied in is the order that they're
142+
checked in.
143+
144+
As per the original example:
145+
146+
$ QUEUES=file_serve,warm_cache php resque.php
147+
148+
The `file_serve` queue will always be checked for new jobs on each
149+
iteration before the `warm_cache` queue is checked.
150+
151+
### Running All Queues ###
152+
153+
All queues are supported in the same manner and processed in alphabetical
154+
order:
155+
156+
$ QUEUES=* php resque.php
157+
158+
### Running Multiple Workers ###
159+
160+
Multiple workers ca be launched and automatically worked by supplying
161+
the `COUNT` environment variable:
162+
163+
$ COUNT=5 php resque.php
164+
165+
### Forking ###
166+
167+
Similarly to the Ruby versions, supported platforms will immediately
168+
fork after picking up a job. The forked child will exit as soon as
169+
the job finishes.
170+
171+
The difference with php-resque is that if a forked child does not
172+
exit nicely (PHP error or such), php-resque will automatically fail
173+
the job.
174+
175+
### Signals ###
176+
177+
Signals also work on supported platforms exactly as in the Ruby
178+
version of Resque:
179+
180+
* `QUIT` - Wait for child to finish processing then exit
181+
* `TERM` / `INT` - Immediately kill child then exit
182+
* `USR1` - Immediately kill child but don't exit
183+
* `USR2` - Pause worker, no new jobs will be processed
184+
* `CONT` - Resume worker.
185+
186+
### Process Titles/Statuses ###
187+
188+
The Ruby version of Resque has a nifty feature whereby the process
189+
title of the worker is updated to indicate what the worker is doing,
190+
and any forked children also set their process title with the job
191+
being run. This helps identify running processes on the server and
192+
their resque status.
193+
194+
**PHP does not have this functionality by default.**
195+
196+
A PECL module (<http://pecl.php.net/package/proctitle>) exists that
197+
adds this funcitonality to PHP, so if you'd like process titles updated,
198+
install the PECL module as well. php-resque will detect and use it.

‎TODO.markdown

+6
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,6 @@
1+
* Write tests for:
2+
* `Resque_Failure`
3+
* `Resque_Failure_Redis`
4+
* Plugin/hook type system similar to Ruby version
5+
* Change to preforking worker model
6+
* Clean up /bin and /demo

‎bin/resque

+1
Original file line numberDiff line numberDiff line change
@@ -0,0 +1 @@
1+
#!/bin/sh

‎build.xml

+17
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,17 @@
1+
<project name="php-resque" default="build">
2+
<target name="clean">
3+
<delete dir="${basedir}/build" />
4+
</target>
5+
<target name="prepare">
6+
<mkdir dir="${basedir}/build" />
7+
<mkdir dir="${basedir}/build/logs" />
8+
</target>
9+
<target name="phpunit">
10+
<exec dir="${basedir}" executable="phpunit" failonerror="true">
11+
<arg line="--log-junit ${basedir}/build/logs/phpunit.xml
12+
--coverage-clover ${basedir}/build/logs/clover.xml
13+
--coverage-html ${basedir}/build/coverage" />
14+
</exec>
15+
</target>
16+
<target name="build" depends="clean,prepare,phpunit" />
17+
</project>

‎demo/bad_job.php

+9
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,9 @@
1+
<?php
2+
class Bad_PHP_Job
3+
{
4+
public function perform()
5+
{
6+
throw new Exception('Unable to run this job!');
7+
}
8+
}
9+
?>

‎demo/check_status.php

+20
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,20 @@
1+
<?php
2+
if(empty($argv[1])) {
3+
die('Specify the ID of a job to monitor the status of.');
4+
}
5+
6+
require '../lib/resque.php';
7+
date_default_timezone_set('GMT');
8+
Resque::setBackend('127.0.0.1:6379');
9+
10+
$status = new Resque_Job_Status($argv[1]);
11+
if(!$status->isTracking()) {
12+
die("Resque is not tracking the status of this job.\n");
13+
}
14+
15+
echo "Tracking status of ".$argv[1].". Press [break] to stop.\n\n";
16+
while(true) {
17+
fwrite(STDOUT, "Status of ".$argv[1]." is: ".$status->get()."\n");
18+
sleep(1);
19+
}
20+
?>

‎demo/job.php

+10
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,10 @@
1+
<?php
2+
class PHP_Job
3+
{
4+
public function perform()
5+
{
6+
sleep(120);
7+
fwrite(STDOUT, 'Hello!');
8+
}
9+
}
10+
?>

‎demo/long_job.php

+9
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,9 @@
1+
<?php
2+
class Long_PHP_Job
3+
{
4+
public function perform()
5+
{
6+
sleep(600);
7+
}
8+
}
9+
?>

‎demo/php_error_job.php

+9
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,9 @@
1+
<?php
2+
class PHP_Error_Job
3+
{
4+
public function perform()
5+
{
6+
callToUndefinedFunction();
7+
}
8+
}
9+
?>

‎demo/queue.php

+19
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,19 @@
1+
<?php
2+
if(empty($argv[1])) {
3+
die('Specify the name of a job to add. e.g, php queue.php PHP_Job');
4+
}
5+
6+
require '../lib/Resque.php';
7+
date_default_timezone_set('GMT');
8+
Resque::setBackend('127.0.0.1:6379');
9+
10+
$class = new stdClass;
11+
$class->test = 'test';
12+
13+
$args = array(
14+
time(),
15+
$class
16+
);
17+
$jobId = Resque::enqueue('default', $argv[1], $args, true);
18+
echo "Queued job ".$jobId."\n\n";
19+
?>

‎demo/resque.php

+8
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,8 @@
1+
<?php
2+
date_default_timezone_set('GMT');
3+
require 'bad_job.php';
4+
require 'job.php';
5+
require 'php_error_job.php';
6+
7+
require '../resque.php';
8+
?>

‎lib/Redisent/LICENSE

+22
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,22 @@
1+
Copyright (c) 2009 Justin Poliey <[email protected]>
2+
3+
Permission is hereby granted, free of charge, to any person
4+
obtaining a copy of this software and associated documentation
5+
files (the "Software"), to deal in the Software without
6+
restriction, including without limitation the rights to use,
7+
copy, modify, merge, publish, distribute, sublicense, and/or sell
8+
copies of the Software, and to permit persons to whom the
9+
Software is furnished to do so, subject to the following
10+
conditions:
11+
12+
The above copyright notice and this permission notice shall be
13+
included in all copies or substantial portions of the Software.
14+
15+
THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND,
16+
EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES
17+
OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND
18+
NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT
19+
HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY,
20+
WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING
21+
FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR
22+
OTHER DEALINGS IN THE SOFTWARE.

0 commit comments

Comments
 (0)