Beanstalk::Client - Client class to talk to beanstalkd server
use Beanstalk::Client; my $client = Beanstalk::Client->new( { server => "localhost", default_tube => 'mine', } ); # Send a job with explicit data my $job = $client->put( { data => "data", priority => 100, ttr => 120, delay => 5, } ); # Send job, data created by encoding @args. By default with YAML my $job2 = $client->put( { priority => 100, ttr => 120, delay => 5, }, @args ); # Send job, data created by encoding @args with JSON use JSON::XS; $client->encoder(sub { encode_json(\@_) }); my $job2 = $client->put( { priority => 100, ttr => 120, delay => 5, }, @args ); # fetch a job my $job3 = $client->reserve;
Beanstalk::Client provides a Perl API of protocol version 1.0 to the beanstalkd server, a fast, general-purpose, in-memory workqueue service by Keith Rarick.
The constructor accepts a single argument, which is a reference to a hash containing options. The options can be any of the accessor methods listed below.
Get/set the hostname, and port, to connect to. The port, which defaults to 11300, can be specified by appending it to the hostname with a : (eg "localhost:1234"). (Default: localhost:11300)
:
"localhost:1234"
localhost:11300
Get the socket connection to the server.
Set/get a default value, in seconds, for job delay. A job with a delay will be placed into a delayed state and will not be placed into the ready queue until the time period has passed. This value will be used by put and release as a default. (Default: 0)
put
release
Set/get a default value, in seconds, for job ttr (time to run). This value will be used by put as a default. (Default: 120)
Set/get a default value for job priority. The highest priority job is the job where the priority value is the lowest (ie jobs with a lower priority value are run first). This value will be used by put, release and bury as a default. (Default: 10000)
bury
Set/get serialization encoder. $encoder is a reference to a subroutine that will be called when arguments to put need to be encoded to send to the beanstalkd server. The subroutine should accept a list of arguments and return a string representation to pass to the server. (Default: YAML::Syck::Dump)
$encoder
Set/get the serialization decoder. $decoder is a reference to a subroutine that will be called when data from the beanstalkd server needs to be decoded. The subroutine will be passed the data fetched from the beanstalkd server and should return a list of values the application can use. (Default: YAML::Syck::Load)
$decoder
Fetch the last error that happened.
Get/set timeout, in seconds, to use for the connect to the server.
Set/get the name of a default tube to put jobs into and fetch from.
By default a connection to a beanstalkd server will put into the default queue and also watch the default queue. If default_tube is set when connect is called the connection will be initialized so that put will put into the given tube and reserve will fetch jobs from the given tube. (Default: none)
default
default_tube
connect
reserve
Set/get debug value. If set to a true value then all communication with the server will be output with warn
warn
These methods are used by clients that are placing work into the queue
Calling touch with the id of a reserved job will reset the time left for the job to complete back to the original ttr value.
touch
Connect to server. If sucessful, set the tube to use and tube to watch if a default_tube was specified.
Disconnect from server. socket method will return undef.
socket
Peek at the job id specified. If the job exists returns a Beanstalk::Job object. Returns undef on error or if job does not exist.
undef
Peek at the first job that is in the ready queue. If there is a job in the ready queue returns a Beanstalk::Job object. Returns undef on error or if there are no ready jobs.
Peek at the first job that is in the delayed queue. If there is a job in the delayed queue returns a Beanstalk::Job object. Returns undef on error or if there are no delayed jobs.
Peek at the first job that is in the buried queue. If there is a job in the buried queue returns a Beanstalk::Job object. Returns undef on error or if there are no buried jobs.
The kick command applies only to the currently used tube. It moves jobs into the ready queue. If there are any buried jobs, it will only kick buried jobs. Otherwise it will kick delayed jobs. The server will not kick more than $bound jobs. Returns the number of jobs kicked, or undef if there was an error.
$bound
Return stats for the specified job $id. Returns undef on error.
$id
If the job exists, the return will be a Stats object with the following methods
id - The job id
tube - The name of the tube that contains this job
state - is "ready" or "delayed" or "reserved" or "buried"
pri - The priority value set by the put, release, or bury commands.
age - The time in seconds since the put command that created this job.
time_left - The number of seconds left until the server puts this job into the ready queue. This number is only meaningful if the job is reserved or delayed. If the job is reserved and this amount of time elapses before its state changes, it is considered to have timed out.
timeouts - The number of times this job has timed out during a reservation.
releases - The number of times a client has released this job from a reservation.
buries - The number of times this job has been buried.
kicks - The number of times this job has been kicked.
Return stats for the specified tube $tube. Returns undef on error.
$tube
If the tube exists, the return will be a Stats object with the following methods
name - The tube's name.
current_jobs_urgent - The number of ready jobs with priority < 1024 in this tube.
current_jobs_ready - The number of jobs in the ready queue in this tube.
current_jobs_reserved - The number of jobs reserved by all clients in this tube.
current_jobs_delayed - The number of delayed jobs in this tube.
current_jobs_buried - The number of buried jobs in this tube.
total_jobs - The cumulative count of jobs created in this tube.
current_waiting - The number of open connections that have issued a reserve command while watching this tube but not yet received a response.
current_jobs_urgent - The number of ready jobs with priority < 1024.
current_jobs_ready - The number of jobs in the ready queue.
current_jobs_reserved - The number of jobs reserved by all clients.
current_jobs_delayed - The number of delayed jobs.
current_jobs_buried - The number of buried jobs.
cmd_put - The cumulative number of put commands.
cmd_peek - The cumulative number of peek commands.
cmd_peek_ready - The cumulative number of peek-ready commands.
cmd_peek_delayed - The cumulative number of peek-delayed commands.
cmd_peek_buried - The cumulative number of peek-buried commands.
cmd_reserve - The cumulative number of reserve commands.
cmd_use - The cumulative number of use commands.
cmd_watch - The cumulative number of watch commands.
cmd_ignore - The cumulative number of ignore commands.
cmd_delete - The cumulative number of delete commands.
cmd_release - The cumulative number of release commands.
cmd_bury - The cumulative number of bury commands.
cmd_kick - The cumulative number of kick commands.
cmd_stats - The cumulative number of stats commands.
cmd_stats_job - The cumulative number of stats-job commands.
cmd_stats_tube - The cumulative number of stats-tube commands.
cmd_list_tubes - The cumulative number of list-tubes commands.
cmd_list_tube_used - The cumulative number of list-tube-used commands.
cmd_list_tubes_watched - The cumulative number of list-tubes-watched commands.
job_timeouts - The cumulative count of times a job has timed out.
total_jobs - The cumulative count of jobs created.
max_job_size - The maximum number of bytes in a job.
current_tubes - The number of currently-existing tubes.
current_connections - The number of currently open connections.
current_producers - The number of open connections that have each issued at least one put command.
current_workers - The number of open connections that have each issued at least one reserve command.
current_waiting - The number of open connections that have issued a reserve command but not yet received a response.
total_connections - The cumulative count of connections.
pid - The process id of the server.
version - The version string of the server.
rusage_utime - The accumulated user CPU time of this process in seconds and microseconds.
rusage_stime - The accumulated system CPU time of this process in seconds and microseconds.
uptime - The number of seconds since this server started running.
Returns a list of tubes
Returns the current tube being used. This is the tube which put will place jobs.
Returns a list of tubes being watched. These are the tubes that reserve will check to find jobs.
More tests
Large parts of this documention were lifted from the documention that comes with beanstalkd
http://xph.us/software/beanstalkd/
Beanstalk::Pool, Beanstalk::Job, Beanstalk::Stats
Graham Barr <gbarr@pobox.com>
Ask Bjørn Hansen
Rhesa Rozendaal
Copyright (C) 2008 by Graham Barr.
This program is free software; you can redistribute it and/or modify it under the same terms as Perl itself.
To install Beanstalk::Client, copy and paste the appropriate command in to your terminal.
cpanm
cpanm Beanstalk::Client
CPAN shell
perl -MCPAN -e shell install Beanstalk::Client
For more information on module installation, please visit the detailed CPAN module installation guide.