1Gearman::Worker(3)    User Contributed Perl Documentation   Gearman::Worker(3)
2
3
4

NAME

6       Gearman::Worker - Worker for gearman distributed job system
7

SYNOPSIS

9           use Gearman::Worker;
10           my $worker = Gearman::Worker->new;
11           $worker->job_servers(
12             '127.0.0.1',
13             {
14               host      => '10.0.0.1',
15               port      => 4730,
16               socket_cb => sub {...},
17               use_ssl   => 1,
18               ca_file   => ...,
19               cert_file => ...,
20               key_file  => ...,
21             }
22           );
23
24           $worker->register_function($funcname => sub {
25               ...
26             }
27           );
28
29           $worker->work(
30             on_start => sub {
31               my ($jobhandle) = @_;
32               ...
33             },
34             on_complete => sub {
35               my ($jobhandle, $result) = @_;
36               ...
37             },
38             on_fail => sub {
39               my ($jobhandle, $err) = @_;
40               ..
41             },
42             stop_if => sub {
43               my ($is_idle, $last_job_time) = @_;
44               # stop idle worker
45               return $is_idle;
46             },
47           );
48

DESCRIPTION

50       Gearman::Worker is a worker class for the Gearman distributed job
51       system, providing a framework for receiving and serving jobs from a
52       Gearman server.
53
54       Callers instantiate a Gearman::Worker object, register a list of
55       functions and capabilities that they can handle, then enter an event
56       loop, waiting for the server to send jobs.
57
58       The worker can send a return value back to the server, which then gets
59       sent back to the client that requested the job; or it can simply
60       execute silently.
61

USAGE

63   Gearman::Worker->new(%options)
64       Creates a new Gearman::Worker object, and returns the object.
65
66       If %options is provided, initializes the new worker object with the
67       settings in %options, which can contain:
68
69       Gearman::Worker is derived from Gearman::Objects
70
71       •   job_servers
72
73           List of job servers. Value should be an array reference, hash
74           reference or scalar.  It will be ignored if this worker is running
75           as a child process of a gearman server.
76
77       •   prefix
78
79           Calls prefix (see below) to set the prefix / namespace.
80
81       •   client_id
82
83           Unique worker identifier for "job_servers".
84
85   $worker->prefix($prefix)
86       Sets the namespace / prefix for the function names.  This is useful for
87       sharing job servers between different applications or different
88       instances of the same application (different development sandboxes for
89       example).
90
91       The namespace is currently implemented as a simple tab separated
92       concatenation of the prefix and the function name.
93

EXAMPLES

95   Summation
96       This is an example worker that receives a request to sum up a list of
97       integers.
98
99           use Gearman::Worker;
100           use Storable qw( thaw );
101           use List::Util qw( sum );
102           my $worker = Gearman::Worker->new;
103           $worker->job_servers('127.0.0.1');
104           $worker->register_function(sum => sub { sum @{ thaw($_[0]->arg) } });
105           $worker->work while 1;
106
107       See the Gearman::Client documentation for a sample client sending the
108       sum job.
109

NOTE

111       If you intend to send or receive UTF-8 data over SSL connections,
112       beware that there is no UTF-8 support in the underlying Net::SSLeay.
113       "Forcing-Unicode-in-Perl-(Or-Unforcing-Unicode-in-Perl)" in perlunicode
114       describes proper workarounds.
115

METHODS

117   reset_abilities
118       This tells all the job servers that this worker can no longer do any
119       tasks.
120
121       return true if "reset_abilities" request successfully transmitted to
122       "job_servers"
123
124   work(%opts)
125       This endlessly loops. It takes an applicable job, if available, does
126       the job, and then waits for the next one.  You can pass "stop_if",
127       "on_start", "on_complete" and "on_fail" callbacks in %opts.  See
128       "SYNOPSIS"
129
130   $worker->register_function($funcname, $subref)
131   $worker->register_function($funcname, $timeout, $subref)
132       Registers the function $funcname as being provided by the worker
133       $worker, and advertises these capabilities to all of the job servers
134       defined in this worker.
135
136       $subref must be a subroutine reference that will be invoked when the
137       worker receives a request for this function. It will be passed a
138       Gearman::Job object representing the job that has been received by the
139       worker.
140
141       $timeout is an optional parameter specifying how long the jobserver
142       will wait for your subroutine to give an answer. Exceeding this time
143       will result in the jobserver reassigning the task and ignoring your
144       result. This prevents a gimpy worker from ruining the 'user experience'
145       in many situations.
146
147       return true if $funcname registration successfully transmitted to
148       "job_servers"
149
150   unregister_function($funcname)
151       send cant_do $funcname request to job_servers
152
153       return true if CANT_DO $funcname request successfully transmitted to
154       "job_servers"
155
156   job_servers(@servers)
157       Override Gearman::Objects method to skip job server initialization if
158       working with Gearman::Server.
159
160       Calling this method will do nothing in a worker that is running as a
161       child process of a gearman server.
162
163   send_work_complete($job, $v)
164       notify the server (and listening clients) that job completed
165       successfully
166
167   send_work_data($job, $data)
168       Use this method to update the client with data from a running job.
169
170   send_work_warning($job, $message)
171       Use this method to send a warning $message to the server (and any
172       listening clients) with regard to the running "job".
173
174   send_work_exception($job, $exception)
175       Use this method to notify the server (and any listening clients) that
176       the "job" failed with the given $exception.
177
178       If you are using Gearman::Client, you have to set parameter exceptions
179       properly to get worker exception notifications.
180
181   send_work_fail($job)
182       Use this method to notify the server (and any listening clients) that
183       the job failed.
184
185   send_work_status($job, $numerator, $denominator)
186       Use this method to send periodically to the server status update for
187       long running jobs to update the percentage complete.
188
189   _uncache_sock($js, $reason)
190       close TCP connection
191

WORKERS AS CHILD PROCESSES

193       Gearman workers can be run as child processes of a parent process which
194       embeds Gearman::Server.  When such a parent process fork/execs a
195       worker, it sets the environment variable GEARMAN_WORKER_USE_STDIO to
196       true before launching the worker. If this variable is set to true, then
197       the job_servers function and option for new() are ignored and the unix
198       socket bound to STDIN/OUT are used instead as the IO path to the
199       gearman server.
200
201
202
203perl v5.36.0                      2023-01-20                Gearman::Worker(3)
Impressum