Skip to content

Update Gearman::Worker documentation #2

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Open
wants to merge 1 commit into
base: master
Choose a base branch
from
Open
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
3 changes: 3 additions & 0 deletions CHANGES
Original file line number Diff line number Diff line change
@@ -1,3 +1,6 @@
-- Worker argument stop_if was supported but undocumentated, added documentation and fixed
RT bug #46373 (stop_if worked but the last jobs return value got lost).

-- Make a jobserver connection use the command timeout during exception negotiation.

-- Make $taskset->add_task use the command timeout to not hang during job submission.
Expand Down
83 changes: 74 additions & 9 deletions lib/Gearman/Worker.pm
Original file line number Diff line number Diff line change
Expand Up @@ -416,13 +416,13 @@ sub work {

$is_idle = 0 if keys %active_js;

return if $stop_if->($is_idle, $last_job_time);

my $update_since = time - (15 + rand 60);

while (my ($js, $last_update) = each %last_update_time) {
$active_js{$js} = 1 if $last_update < $update_since;
}

return if $stop_if->($is_idle, $last_job_time);
}

}
Expand Down Expand Up @@ -513,7 +513,7 @@ Gearman::Worker - Worker for gearman distributed job system
my $worker = Gearman::Worker->new;
$worker->job_servers('127.0.0.1');
$worker->register_function($funcname => $subref);
$worker->work while 1;
$worker->work;

=head1 DESCRIPTION

Expand Down Expand Up @@ -585,7 +585,7 @@ a gimpy worker from ruining the 'user experience' in many situations.
The subroutine reference can return a return value, which will be sent back
to the job server.

=head2 $client-E<gt>prefix($prefix)
=head2 $worker-E<gt>prefix($prefix)

Sets the namespace / prefix for the function names. This is useful
for sharing job servers between different applications or different
Expand All @@ -595,6 +595,76 @@ example).
The namespace is currently implemented as a simple tab separated
concatentation of the prefix and the function name.

=head2 $worker-E<gt>work(%opts)

Waits for jobs for registered functions and processes them.

You can pass "on_start", "on_complete", "on_fail" and "stop_if" callbacks in
I<%opts>. None, some or all of them may be passed.

A new L<Gearman::Job> object is created for every incoming job and is passed
as the only argument when calling the CODE reference specified at
I<register_function>. All Gearman::Job methods mentioned later in this document
refert to this L<Gearman::Job> object.

=head3 on_start callback

$worker-E<gt>work(on_start => sub { print "Running jobid ".shift."\n"; } );

A CODE reference which is called just before a job is started. The job has been
acknowledged to the job dispatcher server and the job id is being passed to the
callback.

Any return value is discarded.

=head3 on_complete

$worker-E<gt>work(on_complete => sub {
my ($jobid, $job_return_value) = @_;
print "Jobid $jobid completed and returned $job_return_value\n";
} );

A CODE reference which is called after each successful job. Two values are passed,
the job id and the return value of the completed job.

Any return value from the callback is discarded.

=head3 on_fail

$worker-E<gt>work(on_fail => sub {
my ($jobid, $job_error) = @_;
print "Jobid $jobid dies because of $job_error\n";
} );

A CODE reference which is called after each successful job. Two values are passed,
the job id and the error code (die value) of the completed job.

Any return value from the callback is discarded.

=head3 stop_if

$worker-E<gt>work(stop if => sub {
my ($is_idle, $last_job_time) = @_;
return 1 if $is_idle and int(rand(2));
} );

A CODE reference which is called after each successful job. While I<on_complete>
and I<on_fail> are called before the job's result is send to the Gearman server,
stop_if is called when everything is done and before the next job has been fetched.

Use stop_if if the client should stop processing jobs (and usually exit itself).

The first value is true when the worker is idle and false if there is any job
pending for execution but it's still safe to exit.

The second value passed to this callback is the unix timestamp just before the last
job was started. Don't use it to calculate the "run time" of a job because the time
elapsed since this timestamp includes network transfer for the return value and wait
time for a new job (some seconds).

The I<stop_if> callback is expected to return true if the worker loop should be left
and false otherwise.

=head2 Gearman::Job->arg

Returns the scalar argument that the client sent to the job server.
Expand All @@ -605,11 +675,6 @@ Updates the status of the job (most likely, a long-running job) and sends
it back to the job server. I<$numerator> and I<$denominator> should
represent the percentage completion of the job.

=head2 Gearman::Job->work(%opts)

Do one job and returns (no value returned).
You can pass "on_start" "on_complete" and "on_fail" callbacks in I<%opts>.

=head1 WORKERS AS CHILD PROCESSES

Gearman workers can be run run as child processes of a parent process
Expand Down