1Gearman::Worker(3) User Contributed Perl Documentation Gearman::Worker(3)
2
6 Gearman::Worker - Worker for gearman distributed job system
7
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 $worker->register_function($funcname => sub {
25 ...
26 }
27 );
28 $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
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 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 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
63 Gearman::Worker->new(%options)
64 Creates a new Gearman::Worker object, and returns the object.
65 If %options is provided, initializes the new worker object with the
67 settings in %options, which can contain:
68 Gearman::Worker is derived from Gearman::Objects
70 • job_servers
72 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 • prefix
78 Calls prefix (see below) to set the prefix / namespace.
80 • client_id
82 Unique worker identifier for "job_servers".
84 $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 The namespace is currently implemented as a simple tab separated
92 concatenation of the prefix and the function name.
93
95 Summation
96 This is an example worker that receives a request to sum up a list of
97 integers.
98 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 See the Gearman::Client documentation for a sample client sending the
108 sum job.
109
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
117 reset_abilities
118 This tells all the job servers that this worker can no longer do any
119 tasks.
120 return true if "reset_abilities" request successfully transmitted to
122 "job_servers"
123 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 $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 $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 $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 return true if $funcname registration successfully transmitted to
148 "job_servers"
149 unregister_function($funcname)
151 send cant_do $funcname request to job_servers
152 return true if CANT_DO $funcname request successfully transmitted to
154 "job_servers"
155 job_servers(@servers)
157 Override Gearman::Objects method to skip job server initialization if
158 working with Gearman::Server.
159 Calling this method will do nothing in a worker that is running as a
161 child process of a gearman server.
162 send_work_complete($job, $v)
164 notify the server (and listening clients) that job completed
165 successfully
166 send_work_data($job, $data)
168 Use this method to update the client with data from a running job.
169 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 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 If you are using Gearman::Client, you have to set parameter exceptions
179 properly to get worker exception notifications.
180 send_work_fail($job)
182 Use this method to notify the server (and any listening clients) that
183 the job failed.
184 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 _uncache_sock($js, $reason)
190 close TCP connection
191
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.
200perl v5.36.0 2022-07-22 Gearman::Worker(3)