1Gearman::Worker(3) User Contributed Perl Documentation Gearman::Worker(3)
2
3
4
6 Gearman::Worker - Worker for gearman distributed job system
7
9 use Gearman::Worker;
10 my $worker = Gearman::Worker->new;
11 $worker->job_servers('127.0.0.1');
12 $worker->register_function($funcname => $subref);
13 $worker->work while 1;
14
16 Gearman::Worker is a worker class for the Gearman distributed job sys‐
17 tem, providing a framework for receiving and serving jobs from a Gear‐
18 man server.
19
20 Callers instantiate a Gearman::Worker object, register a list of func‐
21 tions and capabilities that they can handle, then enter an event loop,
22 waiting for the server to send jobs.
23
24 The worker can send a return value back to the server, which then gets
25 sent back to the client that requested the job; or it can simply exe‐
26 cute silently.
27
29 Gearman::Worker->new(%options)
30
31 Creates a new Gearman::Worker object, and returns the object.
32
33 If %options is provided, initializes the new worker object with the
34 settings in %options, which can contain:
35
36 * job_servers
37 Calls job_servers (see below) to initialize the list of job
38 servers. It will be ignored if this worker is running as a child
39 process of a gearman server.
40
41 * prefix
42 Calls prefix (see below) to set the prefix / namespace.
43
44 $worker->job_servers(@servers)
45
46 Initializes the worker $worker with the list of job servers in
47 @servers. @servers should contain a list of IP addresses, with
48 optional port numbers. For example:
49
50 $worker->job_servers('127.0.0.1', '192.168.1.100:7003');
51
52 If the port number is not provided, 7003 is used as the default.
53
54 Calling this method will do nothing in a worker that is running as a
55 child process of a gearman server.
56
57 $worker->register_function($funcname, $subref)
58
59 $worker->register_function($funcname, $timeout, $subref)
60
61 Registers the function $funcname as being provided by the worker
62 $worker, and advertises these capabilities to all of the job servers
63 defined in this worker.
64
65 $subref must be a subroutine reference that will be invoked when the
66 worker receives a request for this function. It will be passed a Gear‐
67 man::Job object representing the job that has been received by the
68 worker.
69
70 $timeout is an optional parameter specifying how long the jobserver
71 will wait for your subroutine to give an answer. Exceeding this time
72 will result in the jobserver reassigning the task and ignoring your
73 result. This prevents a gimpy worker from ruining the 'user experience'
74 in many situations.
75
76 The subroutine reference can return a return value, which will be sent
77 back to the job server.
78
79 $client->prefix($prefix)
80
81 Sets the namespace / prefix for the function names. This is useful for
82 sharing job servers between different applications or different
83 instances of the same application (different development sandboxes for
84 example).
85
86 The namespace is currently implemented as a simple tab separated conca‐
87 tentation of the prefix and the function name.
88
89 Gearman::Job->arg
90
91 Returns the scalar argument that the client sent to the job server.
92
93 Gearman::Job->set_status($numerator, $denominator)
94
95 Updates the status of the job (most likely, a long-running job) and
96 sends it back to the job server. $numerator and $denominator should
97 represent the percentage completion of the job.
98
99 Gearman::Job->work(%opts)
100
101 Do one job and returns (no value returned). You can pass "on_start"
102 "on_complete" and "on_fail" callbacks in %opts.
103
105 Gearman workers can be run run as child processes of a parent process
106 which embeds Gearman::Server. When such a parent process fork/execs a
107 worker, it sets the environment variable GEARMAN_WORKER_USE_STDIO to
108 true before launching the worker. If this variable is set to true, then
109 the jobservers function and option for new() are ignored and the unix
110 socket bound to STDIN/OUT are used instead as the IO path to the gear‐
111 man server.
112
114 Summation
115
116 This is an example worker that receives a request to sum up a list of
117 integers.
118
119 use Gearman::Worker;
120 use Storable qw( thaw );
121 use List::Util qw( sum );
122 my $worker = Gearman::Worker->new;
123 $worker->job_servers('127.0.0.1');
124 $worker->register_function(sum => sub { sum @{ thaw($_[0]->arg) } });
125 $worker->work while 1;
126
127 See the Gearman::Client documentation for a sample client sending the
128 sum job.
129
130
131
132perl v5.8.8 2007-05-04 Gearman::Worker(3)