1Beanstalk::Client(3)  User Contributed Perl Documentation Beanstalk::Client(3)
2
3
4

NAME

6       Beanstalk::Client - Client class to talk to beanstalkd server
7

SYNOPSIS

9         use Beanstalk::Client;
10
11         my $client = Beanstalk::Client->new(
12           { server       => "localhost",
13             default_tube => 'mine',
14           }
15         );
16
17         # 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
26         # 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
35         # 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
46         # fetch a job
47         my $job3 = $client->reserve;
48

DESCRIPTION

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

METHODS

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
61   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
67       socket
68           Get the socket connection to the server.
69
70       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
76       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
80       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
86       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
93       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
100       error
101           Fetch the last error that happened.
102
103       connect_timeout ([$timeout])
104           Get/set timeout, in seconds, to use for the connect to the server.
105
106       default_tube ([$tube])
107           Set/get the name of a default tube to put jobs into and fetch from.
108
109           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
115       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
119   Producer Methods
120       These methods are used by clients that are placing work into the queue
121
122       put ($options [, @args])
123           Insert job into the currently used tube. Options may be
124
125           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
130               Defaults to "$self-"priority>
131
132           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
137               Defaults to "$self-"delay>
138
139           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
146           data
147               The job body. Defaults to the result of calling the current
148               encoder passing @args
149
150       use ($tube)
151           Change tube that new jobs are inserted into
152
153   Worker Methods
154       reserve ([$timeout])
155           Reserve a job from the list of tubes currently being watched.
156
157           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
161           Returns undef on error or if $timeout expires.
162
163       delete ($id)
164           Delete the specified job.
165
166       release ($id, [, $options])
167           Release the specified job. Valid options are
168
169           priority
170               New priority to assign to the job
171
172           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
177       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
182           Valid options are
183
184           priority
185               New priority to assign to the job
186
187       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
191       watch ($tube)
192           Specifies a tube to add to the watch list. If the tube doesn't
193           exist, it will be created
194
195       ignore ($tube)
196           Stop watching $tube
197
198       watch_only (@tubes)
199           Watch only the list of given tube names
200
201   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
206       disconnect
207           Disconnect from server. "socket" method will return undef.
208
209       quit
210           Disconnect from server. "socket" method will return undef.
211
212       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
217       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
222       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
227       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
232       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
239       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
246           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
250       stats_job ($id)
251           Return stats for the specified job $id. Returns "undef" on error.
252
253           If the job exists, the return will be a Stats object with the
254           following methods
255
256id - The job id
257
258tube - The name of the tube that contains this job
259
260state - is "ready" or "delayed" or "reserved" or "buried"
261
262pri - The priority value set by the put, release, or bury
263               commands.
264
265age - The time in seconds since the put command that created
266               this job.
267
268time_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
274reserves - The number of times this job has been reserved
275
276timeouts - The number of times this job has timed out during a
277               reservation.
278
279releases - The number of times a client has released this job
280               from a reservation.
281
282buries - The number of times this job has been buried.
283
284kicks - The number of times this job has been kicked.
285
286       stats_tube ($tube)
287           Return stats for the specified tube $tube. Returns "undef" on
288           error.
289
290           If the tube exists, the return will be a Stats object with the
291           following methods
292
293name - The tube's name.
294
295current_jobs_urgent - The number of ready jobs with priority <
296               1024 in this tube.
297
298current_jobs_ready - The number of jobs in the ready queue in
299               this tube.
300
301current_jobs_reserved - The number of jobs reserved by all
302               clients in this tube.
303
304current_jobs_delayed - The number of delayed jobs in this tube.
305
306current_jobs_buried - The number of buried jobs in this tube.
307
308total_jobs - The cumulative count of jobs created in this tube.
309
310current_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
314pause - The number of seconds the tube has been paused for.
315
316cmd_pause_tube - The cumulative number of pause-tube commands
317               for this tube.
318
319pause_time_left - The number of seconds until the tube is un-
320               paused.
321
322       stats
323current_jobs_urgent - The number of ready jobs with priority <
324               1024.
325
326current_jobs_ready - The number of jobs in the ready queue.
327
328current_jobs_reserved - The number of jobs reserved by all
329               clients.
330
331current_jobs_delayed - The number of delayed jobs.
332
333current_jobs_buried - The number of buried jobs.
334
335cmd_put - The cumulative number of put commands.
336
337cmd_peek - The cumulative number of peek commands.
338
339cmd_peek_ready - The cumulative number of peek-ready commands.
340
341cmd_peek_delayed - The cumulative number of peek-delayed
342               commands.
343
344cmd_peek_buried - The cumulative number of peek-buried
345               commands.
346
347cmd_reserve - The cumulative number of reserve commands.
348
349cmd_use - The cumulative number of use commands.
350
351cmd_watch - The cumulative number of watch commands.
352
353cmd_ignore - The cumulative number of ignore commands.
354
355cmd_delete - The cumulative number of delete commands.
356
357cmd_release - The cumulative number of release commands.
358
359cmd_bury - The cumulative number of bury commands.
360
361cmd_kick - The cumulative number of kick commands.
362
363cmd_stats - The cumulative number of stats commands.
364
365cmd_stats_job - The cumulative number of stats-job commands.
366
367cmd_stats_tube - The cumulative number of stats-tube commands.
368
369cmd_list_tubes - The cumulative number of list-tubes commands.
370
371cmd_list_tube_used - The cumulative number of list-tube-used
372               commands.
373
374cmd_list_tubes_watched - The cumulative number of list-tubes-
375               watched commands.
376
377cmd_pause_tube - The cumulative number of pause-tube commands
378
379job_timeouts - The cumulative count of times a job has timed
380               out.
381
382total_jobs - The cumulative count of jobs created.
383
384max_job_size - The maximum number of bytes in a job.
385
386current_tubes - The number of currently-existing tubes.
387
388current_connections - The number of currently open connections.
389
390current_producers - The number of open connections that have
391               each issued at least one put command.
392
393current_workers - The number of open connections that have each
394               issued at least one reserve command.
395
396current_waiting - The number of open connections that have
397               issued a reserve command but not yet received a response.
398
399total_connections - The cumulative count of connections.
400
401pid - The process id of the server.
402
403version - The version string of the server.
404
405rusage_utime - The accumulated user CPU time of this process in
406               seconds and microseconds.
407
408rusage_stime - The accumulated system CPU time of this process
409               in seconds and microseconds.
410
411uptime - The number of seconds since this server started
412               running.
413
414binlog_oldest_index - The index of the oldest binlog file
415               needed to store the current jobs
416
417binlog_current_index - The index of the current binlog file
418               being written to. If binlog is not active this value will be 0
419
420binlog_max_size - The maximum size in bytes a binlog file is
421               allowed to get before a new binlog file is opened
422
423       list_tubes
424           Returns a list of tubes
425
426       list_tube_used
427           Returns the current tube being used. This is the tube which "put"
428           will place jobs.
429
430       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
436       pause_tube ($tube, $delay)
437           Pause from reserving any jobs in $tube for $delay seconds.
438
439           Returns true on success and "undef" on error.
440

TODO

442       More tests
443

ACKNOWLEDGEMTS

445       Large parts of this documention were lifted from the documention that
446       comes with beanstalkd
447

SEE ALSO

449       http://kr.github.com/beanstalkd/
450
451       Beanstalk::Pool, Beanstalk::Job, Beanstalk::Stats
452

AUTHOR

454       Graham Barr <gbarr@pobox.com>
455

CREDITS

457       •   Ask Bjørn Hansen
458
459       •   Rhesa Rozendaal
460
461       •   Ian Docherty
462

BUGS

464       The Git repository is available at
465       http://github.com/gbarr/perl-beanstalk-client
466
467       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
473       This program is free software; you can redistribute it and/or modify it
474       under the same terms as Perl itself.
475
476
477
478perl v5.36.0                      2023-01-20              Beanstalk::Client(3)
Impressum