1Beanstalk::Client(3) User Contributed Perl Documentation Beanstalk::Client(3)
2
6 Beanstalk::Client - Client class to talk to beanstalkd server
7
9 use Beanstalk::Client;
10 my $client = Beanstalk::Client->new(
12 { server => "localhost",
13 default_tube => 'mine',
14 }
15 );
16 # Send a job with explicit data
18 my $job = $client->put(
19 { data => "data",
20 priority => 100,
21 ttr => 120,
22 delay => 5,
23 }
24 );
25 # Send job, data created by encoding @args. By default with YAML
27 my $job2 = $client->put(
28 { priority => 100,
29 ttr => 120,
30 delay => 5,
31 },
32 @args
33 );
34 # Send job, data created by encoding @args with JSON
36 use JSON::XS;
37 $client->encoder(sub { encode_json(\@_) });
38 my $job2 = $client->put(
39 { priority => 100,
40 ttr => 120,
41 delay => 5,
42 },
43 @args
44 );
45 # fetch a job
47 my $job3 = $client->reserve;
48
50 Beanstalk::Client provides a Perl API of protocol version 1.0 to the
51 beanstalkd server, a fast, general-purpose, in-memory workqueue service
52 by Keith Rarick.
53
55 Constructor
56 new ($options)
57 The constructor accepts a single argument, which is a reference to
58 a hash containing options. The options can be any of the accessor
59 methods listed below.
60 Accessor Methods
62 server ([$hostname])
63 Get/set the hostname, and port, to connect to. The port, which
64 defaults to 11300, can be specified by appending it to the hostname
65 with a ":" (eg "localhost:1234"). (Default: "localhost:11300")
66 socket
68 Get the socket connection to the server.
69 delay ([$delay])
71 Set/get a default value, in seconds, for job delay. A job with a
72 delay will be placed into a delayed state and will not be placed
73 into the ready queue until the time period has passed. This value
74 will be used by "put" and "release" as a default. (Default: 0)
75 ttr ([$ttr])
77 Set/get a default value, in seconds, for job ttr (time to run).
78 This value will be used by "put" as a default. (Default: 120)
79 priority ([$priority])
81 Set/get a default value for job priority. The highest priority job
82 is the job where the priority value is the lowest (ie jobs with a
83 lower priority value are run first). This value will be used by
84 "put", "release" and "bury" as a default. (Default: 10000)
85 encoder ([$encoder])
87 Set/get serialization encoder. $encoder is a reference to a
88 subroutine that will be called when arguments to "put" need to be
89 encoded to send to the beanstalkd server. The subroutine should
90 accept a list of arguments and return a string representation to
91 pass to the server. (Default: YAML::Syck::Dump)
92 decoder ([$decoder])
94 Set/get the serialization decoder. $decoder is a reference to a
95 subroutine that will be called when data from the beanstalkd server
96 needs to be decoded. The subroutine will be passed the data fetched
97 from the beanstalkd server and should return a list of values the
98 application can use. (Default: YAML::Syck::Load)
99 error
101 Fetch the last error that happened.
102 connect_timeout ([$timeout])
104 Get/set timeout, in seconds, to use for the connect to the server.
105 default_tube ([$tube])
107 Set/get the name of a default tube to put jobs into and fetch from.
108 By default a connection to a beanstalkd server will put into the
110 "default" queue and also watch the "default" queue. If
111 "default_tube" is set when "connect" is called the connection will
112 be initialized so that "put" will put into the given tube and
113 "reserve" will fetch jobs from the given tube. (Default: none)
114 debug ([$debug])
116 Set/get debug value. If set to a true value then all communication
117 with the server will be output with "warn"
118 Producer Methods
120 These methods are used by clients that are placing work into the queue
121 put ($options [, @args])
123 Insert job into the currently used tube. Options may be
124 priority
126 priority to use to queue the job. Jobs with smaller priority
127 values will be scheduled before jobs with larger priorities.
128 The most urgent priority is 0
129 Defaults to "$self-"priority>
131 delay
133 An integer number of seconds to wait before putting the job in
134 the ready queue. The job will be in the "delayed" state
135 during this time
136 Defaults to "$self-"delay>
138 ttr "time to run" - An integer number of seconds to allow a worker
140 to run this job. This time is counted from the moment a worker
141 reserves this job. If the worker does not delete, release, or
142 bury the job within "ttr" seconds, the job will time out and
143 the server will release the job. The minimum ttr is 1. If the
144 client sends 0, the server will silently increase the ttr to 1.
145 data
147 The job body. Defaults to the result of calling the current
148 encoder passing @args
149 use ($tube)
151 Change tube that new jobs are inserted into
152 Worker Methods
154 reserve ([$timeout])
155 Reserve a job from the list of tubes currently being watched.
156 Returns a Beanstalk::Job on success. $timeout is the maximum number
158 of seconds to wait for a job to become ready. If $timeout is not
159 given then the client will wait indefinitely.
160 Returns undef on error or if $timeout expires.
162 delete ($id)
164 Delete the specified job.
165 release ($id, [, $options])
167 Release the specified job. Valid options are
168 priority
170 New priority to assign to the job
171 delay
173 An integer number of seconds to wait before putting the job in
174 the ready queue. The job will be in the "delayed" state during
175 this time
176 bury ($id [, $options])
178 The bury command puts a job into the "buried" state. Buried jobs
179 are put into a FIFO linked list and will not be touched by the
180 server again until a client kicks them with the "kick" command.
181 Valid options are
183 priority
185 New priority to assign to the job
186 touch ($id)
188 Calling "touch" with the id of a reserved job will reset the time
189 left for the job to complete back to the original ttr value.
190 watch ($tube)
192 Specifies a tube to add to the watch list. If the tube doesn't
193 exist, it will be created
194 ignore ($tube)
196 Stop watching $tube
197 watch_only (@tubes)
199 Watch only the list of given tube names
200 Other Methods
202 connect
203 Connect to server. If sucessful, set the tube to use and tube to
204 watch if a "default_tube" was specified.
205 disconnect
207 Disconnect from server. "socket" method will return undef.
208 quit
210 Disconnect from server. "socket" method will return undef.
211 peek ($id)
213 Peek at the job id specified. If the job exists returns a
214 Beanstalk::Job object. Returns "undef" on error or if job does not
215 exist.
216 peek_ready
218 Peek at the first job that is in the ready queue. If there is a job
219 in the ready queue returns a Beanstalk::Job object. Returns "undef"
220 on error or if there are no ready jobs.
221 peek_delayed
223 Peek at the first job that is in the delayed queue. If there is a
224 job in the delayed queue returns a Beanstalk::Job object. Returns
225 "undef" on error or if there are no delayed jobs.
226 peek_buried
228 Peek at the first job that is in the buried queue. If there is a
229 job in the buried queue returns a Beanstalk::Job object. Returns
230 "undef" on error or if there are no buried jobs.
231 kick ($bound)
233 The kick command applies only to the currently used tube. It moves
234 jobs into the ready queue. If there are any buried jobs, it will
235 only kick buried jobs. Otherwise it will kick delayed jobs. The
236 server will not kick more than $bound jobs. Returns the number of
237 jobs kicked, or undef if there was an error.
238 kick_job ($id)
240 The kick-job command is a variant of kick that operats with a
241 single job identified by its job id. If the given job id exists and
242 is in a buried or delayed state, it will be moved to the ready
243 queue of the same tube where it currently belongs. Returns "undef"
244 on error.
245 Note: the kick_job command was only introduced on version 1.8 of
247 beanstalk. If you have a version of beanstalk prior to this then
248 the command will return an error.
249 stats_job ($id)
251 Return stats for the specified job $id. Returns "undef" on error.
252 If the job exists, the return will be a Stats object with the
254 following methods
255 • id - The job id
257 • tube - The name of the tube that contains this job
259 • state - is "ready" or "delayed" or "reserved" or "buried"
261 • pri - The priority value set by the put, release, or bury
263 commands.
264 • age - The time in seconds since the put command that created
266 this job.
267 • time_left - The number of seconds left until the server puts
269 this job into the ready queue. This number is only meaningful
270 if the job is reserved or delayed. If the job is reserved and
271 this amount of time elapses before its state changes, it is
272 considered to have timed out.
273 • reserves - The number of times this job has been reserved
275 • timeouts - The number of times this job has timed out during a
277 reservation.
278 • releases - The number of times a client has released this job
280 from a reservation.
281 • buries - The number of times this job has been buried.
283 • kicks - The number of times this job has been kicked.
285 stats_tube ($tube)
287 Return stats for the specified tube $tube. Returns "undef" on
288 error.
289 If the tube exists, the return will be a Stats object with the
291 following methods
292 • name - The tube's name.
294 • current_jobs_urgent - The number of ready jobs with priority <
296 1024 in this tube.
297 • current_jobs_ready - The number of jobs in the ready queue in
299 this tube.
300 • current_jobs_reserved - The number of jobs reserved by all
302 clients in this tube.
303 • current_jobs_delayed - The number of delayed jobs in this tube.
305 • current_jobs_buried - The number of buried jobs in this tube.
307 • total_jobs - The cumulative count of jobs created in this tube.
309 • current_waiting - The number of open connections that have
311 issued a reserve command while watching this tube but not yet
312 received a response.
313 • pause - The number of seconds the tube has been paused for.
315 • cmd_pause_tube - The cumulative number of pause-tube commands
317 for this tube.
318 • pause_time_left - The number of seconds until the tube is un-
320 paused.
321 stats
323 • current_jobs_urgent - The number of ready jobs with priority <
324 1024.
325 • current_jobs_ready - The number of jobs in the ready queue.
327 • current_jobs_reserved - The number of jobs reserved by all
329 clients.
330 • current_jobs_delayed - The number of delayed jobs.
332 • current_jobs_buried - The number of buried jobs.
334 • cmd_put - The cumulative number of put commands.
336 • cmd_peek - The cumulative number of peek commands.
338 • cmd_peek_ready - The cumulative number of peek-ready commands.
340 • cmd_peek_delayed - The cumulative number of peek-delayed
342 commands.
343 • cmd_peek_buried - The cumulative number of peek-buried
345 commands.
346 • cmd_reserve - The cumulative number of reserve commands.
348 • cmd_use - The cumulative number of use commands.
350 • cmd_watch - The cumulative number of watch commands.
352 • cmd_ignore - The cumulative number of ignore commands.
354 • cmd_delete - The cumulative number of delete commands.
356 • cmd_release - The cumulative number of release commands.
358 • cmd_bury - The cumulative number of bury commands.
360 • cmd_kick - The cumulative number of kick commands.
362 • cmd_stats - The cumulative number of stats commands.
364 • cmd_stats_job - The cumulative number of stats-job commands.
366 • cmd_stats_tube - The cumulative number of stats-tube commands.
368 • cmd_list_tubes - The cumulative number of list-tubes commands.
370 • cmd_list_tube_used - The cumulative number of list-tube-used
372 commands.
373 • cmd_list_tubes_watched - The cumulative number of list-tubes-
375 watched commands.
376 • cmd_pause_tube - The cumulative number of pause-tube commands
378 • job_timeouts - The cumulative count of times a job has timed
380 out.
381 • total_jobs - The cumulative count of jobs created.
383 • max_job_size - The maximum number of bytes in a job.
385 • current_tubes - The number of currently-existing tubes.
387 • current_connections - The number of currently open connections.
389 • current_producers - The number of open connections that have
391 each issued at least one put command.
392 • current_workers - The number of open connections that have each
394 issued at least one reserve command.
395 • current_waiting - The number of open connections that have
397 issued a reserve command but not yet received a response.
398 • total_connections - The cumulative count of connections.
400 • pid - The process id of the server.
402 • version - The version string of the server.
404 • rusage_utime - The accumulated user CPU time of this process in
406 seconds and microseconds.
407 • rusage_stime - The accumulated system CPU time of this process
409 in seconds and microseconds.
410 • uptime - The number of seconds since this server started
412 running.
413 • binlog_oldest_index - The index of the oldest binlog file
415 needed to store the current jobs
416 • binlog_current_index - The index of the current binlog file
418 being written to. If binlog is not active this value will be 0
419 • binlog_max_size - The maximum size in bytes a binlog file is
421 allowed to get before a new binlog file is opened
422 list_tubes
424 Returns a list of tubes
425 list_tube_used
427 Returns the current tube being used. This is the tube which "put"
428 will place jobs.
429 list_tubes_watched
431 Returns a list of tubes being watched, or the number of tubes being
432 watched in a scalar context. These are the tubes that "reserve"
433 will check to find jobs. On error an empty list, or undef in a
434 scalar context, will be returned.
435 pause_tube ($tube, $delay)
437 Pause from reserving any jobs in $tube for $delay seconds.
438 Returns true on success and "undef" on error.
440
442 More tests
443
445 Large parts of this documention were lifted from the documention that
446 comes with beanstalkd
447
449 http://kr.github.com/beanstalkd/
450 Beanstalk::Pool, Beanstalk::Job, Beanstalk::Stats
452
454 Graham Barr <gbarr@pobox.com>
455
457 • Ask Bjørn Hansen
458 • Rhesa Rozendaal
460 • Ian Docherty
462
464 The Git repository is available at
465 http://github.com/gbarr/perl-beanstalk-client
466 Please report any bugs or feature requests to the issue tracker at
468 http://github.com/gbarr/perl-beanstalk-client/issues
469
471 Copyright (C) 2008-2012 by Graham Barr.
472 This program is free software; you can redistribute it and/or modify it
474 under the same terms as Perl itself.
475perl v5.36.0 2023-01-20 Beanstalk::Client(3)