.\" Automatically generated by Pod::Man 4.14 (Pod::Simple 3.42)
.\"
.\" Standard preamble:
.\" ========================================================================
.de Sp \" Vertical space (when we can't use .PP)
.if t .sp .5v
.if n .sp
..
.de Vb \" Begin verbatim text
.ft CW
.nf
.ne \\$1
..
.de Ve \" End verbatim text
.ft R
.fi
..
.\" Set up some character translations and predefined strings.  \*(-- will
.\" give an unbreakable dash, \*(PI will give pi, \*(L" will give a left
.\" double quote, and \*(R" will give a right double quote.  \*(C+ will
.\" give a nicer C++.  Capital omega is used to do unbreakable dashes and
.\" therefore won't be available.  \*(C` and \*(C' expand to `' in nroff,
.\" nothing in troff, for use with C<>.
.tr \(*W-
.ds C+ C\v'-.1v'\h'-1p'\s-2+\h'-1p'+\s0\v'.1v'\h'-1p'
.ie n \{\
.    ds -- \(*W-
.    ds PI pi
.    if (\n(.H=4u)&(1m=24u) .ds -- \(*W\h'-12u'\(*W\h'-12u'-\" diablo 10 pitch
.    if (\n(.H=4u)&(1m=20u) .ds -- \(*W\h'-12u'\(*W\h'-8u'-\"  diablo 12 pitch
.    ds L" ""
.    ds R" ""
.    ds C` ""
.    ds C' ""
'br\}
.el\{\
.    ds -- \|\(em\|
.    ds PI \(*p
.    ds L" ``
.    ds R" ''
.    ds C`
.    ds C'
'br\}
.\"
.\" Escape single quotes in literal strings from groff's Unicode transform.
.ie \n(.g .ds Aq \(aq
.el       .ds Aq '
.\"
.\" If the F register is >0, we'll generate index entries on stderr for
.\" titles (.TH), headers (.SH), subsections (.SS), items (.Ip), and index
.\" entries marked with X<> in POD.  Of course, you'll have to process the
.\" output yourself in some meaningful fashion.
.\"
.\" Avoid warning from groff about undefined register 'F'.
.de IX
..
.nr rF 0
.if \n(.g .if rF .nr rF 1
.if (\n(rF:(\n(.g==0)) \{\
.    if \nF \{\
.        de IX
.        tm Index:\\$1\t\\n%\t"\\$2"
..
.        if !\nF==2 \{\
.            nr % 0
.            nr F 2
.        \}
.    \}
.\}
.rr rF
.\"
.\" Accent mark definitions (@(#)ms.acc 1.5 88/02/08 SMI; from UCB 4.2).
.\" Fear.  Run.  Save yourself.  No user-serviceable parts.
.    \" fudge factors for nroff and troff
.if n \{\
.    ds #H 0
.    ds #V .8m
.    ds #F .3m
.    ds #[ \f1
.    ds #] \fP
.\}
.if t \{\
.    ds #H ((1u-(\\\\n(.fu%2u))*.13m)
.    ds #V .6m
.    ds #F 0
.    ds #[ \&
.    ds #] \&
.\}
.    \" simple accents for nroff and troff
.if n \{\
.    ds ' \&
.    ds ` \&
.    ds ^ \&
.    ds , \&
.    ds ~ ~
.    ds /
.\}
.if t \{\
.    ds ' \\k:\h'-(\\n(.wu*8/10-\*(#H)'\'\h"|\\n:u"
.    ds ` \\k:\h'-(\\n(.wu*8/10-\*(#H)'\`\h'|\\n:u'
.    ds ^ \\k:\h'-(\\n(.wu*10/11-\*(#H)'^\h'|\\n:u'
.    ds , \\k:\h'-(\\n(.wu*8/10)',\h'|\\n:u'
.    ds ~ \\k:\h'-(\\n(.wu-\*(#H-.1m)'~\h'|\\n:u'
.    ds / \\k:\h'-(\\n(.wu*8/10-\*(#H)'\z\(sl\h'|\\n:u'
.\}
.    \" troff and (daisy-wheel) nroff accents
.ds : \\k:\h'-(\\n(.wu*8/10-\*(#H+.1m+\*(#F)'\v'-\*(#V'\z.\h'.2m+\*(#F'.\h'|\\n:u'\v'\*(#V'
.ds 8 \h'\*(#H'\(*b\h'-\*(#H'
.ds o \\k:\h'-(\\n(.wu+\w'\(de'u-\*(#H)/2u'\v'-.3n'\*(#[\z\(de\v'.3n'\h'|\\n:u'\*(#]
.ds d- \h'\*(#H'\(pd\h'-\w'~'u'\v'-.25m'\f2\(hy\fP\v'.25m'\h'-\*(#H'
.ds D- D\\k:\h'-\w'D'u'\v'-.11m'\z\(hy\v'.11m'\h'|\\n:u'
.ds th \*(#[\v'.3m'\s+1I\s-1\v'-.3m'\h'-(\w'I'u*2/3)'\s-1o\s+1\*(#]
.ds Th \*(#[\s+2I\s-2\h'-\w'I'u*3/5'\v'-.3m'o\v'.3m'\*(#]
.ds ae a\h'-(\w'a'u*4/10)'e
.ds Ae A\h'-(\w'A'u*4/10)'E
.    \" corrections for vroff
.if v .ds ~ \\k:\h'-(\\n(.wu*9/10-\*(#H)'\s-2\u~\d\s+2\h'|\\n:u'
.if v .ds ^ \\k:\h'-(\\n(.wu*10/11-\*(#H)'\v'-.4m'^\v'.4m'\h'|\\n:u'
.    \" for low resolution devices (crt and lpr)
.if \n(.H>23 .if \n(.V>19 \
\{\
.    ds : e
.    ds 8 ss
.    ds o a
.    ds d- d\h'-1'\(ga
.    ds D- D\h'-1'\(hy
.    ds th \o'bp'
.    ds Th \o'LP'
.    ds ae ae
.    ds Ae AE
.\}
.rm #[ #] #H #V #F C
.\" ========================================================================
.\"
.IX Title "TheSchwartz 3pm"
.TH TheSchwartz 3pm "2022-06-28" "perl v5.34.0" "User Contributed Perl Documentation"
.\" For nroff, turn off justification.  Always turn off hyphenation; it makes
.\" way too many mistakes in technical documents.
.if n .ad l
.nh
.SH "NAME"
TheSchwartz \- reliable job queue
.SH "SYNOPSIS"
.IX Header "SYNOPSIS"
.Vb 2
\&    # MyApp.pm
\&    package MyApp;
\&
\&    sub work_asynchronously {
\&        my %args = @_;
\&
\&        my $client = TheSchwartz\->new( databases => $DATABASE_INFO );
\&        $client\->insert(\*(AqMyWorker\*(Aq, \e%args);
\&    }
\&
\&
\&    # myworker.pl
\&    package MyWorker;
\&    use base qw( TheSchwartz::Worker );
\&
\&    sub work {
\&        my $class = shift;
\&        my TheSchwartz::Job $job = shift;
\&
\&        print "Workin\*(Aq hard or hardly workin\*(Aq? Hyuk!!\en";
\&
\&        $job\->completed();
\&    }
\&
\&    package main;
\&
\&    my $client = TheSchwartz\->new( databases => $DATABASE_INFO );
\&    $client\->can_do(\*(AqMyWorker\*(Aq);
\&    $client\->work();
.Ve
.SH "DESCRIPTION"
.IX Header "DESCRIPTION"
TheSchwartz is a reliable job queue system. Your application can put jobs into
the system, and your worker processes can pull jobs from the queue atomically
to perform. Failed jobs can be left in the queue to retry later.
.PP
\&\fIAbilities\fR specify what jobs a worker process can perform. Abilities are the
names of \f(CW\*(C`TheSchwartz::Worker\*(C'\fR sub-classes, as in the synopsis: the \f(CW\*(C`MyWorker\*(C'\fR
class name is used to specify that the worker script can perform the job. When
using the \f(CW\*(C`TheSchwartz\*(C'\fR client's \f(CW\*(C`work\*(C'\fR functions, the class-ability duality
is used to automatically dispatch to the proper class to do the actual work.
.PP
TheSchwartz clients will also prefer to do jobs for unused abilities before
reusing a particular ability, to avoid exhausting the supply of one kind of job
while jobs of other types stack up.
.PP
Some jobs with high setup times can be performed more efficiently if a group of
related jobs are performed together. TheSchwartz offers a facility to
\&\fIcoalesce\fR jobs into groups, which a properly constructed worker can find and
perform at once. For example, if your worker were delivering email, you might
store the domain name from the recipient's address as the coalescing value. The
worker that grabs that job could then batch deliver all the mail for that
domain once it connects to that domain's mail server.
.SH "USAGE"
.IX Header "USAGE"
.ie n .SS """TheSchwartz\->new( %args )"""
.el .SS "\f(CWTheSchwartz\->new( %args )\fP"
.IX Subsection "TheSchwartz->new( %args )"
Optional members of \f(CW%args\fR are:
.IP "\(bu" 4
\&\f(CW\*(C`databases\*(C'\fR
.Sp
An arrayref of database information. TheSchwartz workers can use multiple
databases, such that if any of them are unavailable, the worker will search for
appropriate jobs in the other databases automatically.
.Sp
Each member of the \f(CW\*(C`databases\*(C'\fR value should be a hashref containing either:
.RS 4
.IP "\(bu" 4
\&\f(CW\*(C`dsn\*(C'\fR
.Sp
The database \s-1DSN\s0 for this database.
.IP "\(bu" 4
\&\f(CW\*(C`user\*(C'\fR
.Sp
The user name to use when connecting to this database.
.IP "\(bu" 4
\&\f(CW\*(C`pass\*(C'\fR
.Sp
The password to use when connecting to this database.
.RE
.RS 4
.Sp
or
.IP "\(bu" 4
\&\f(CW\*(C`driver\*(C'\fR
.Sp
A \f(CW\*(C`Data::ObjectDriver::Driver::DBI\*(C'\fR object.
.Sp
See note below.
.RE
.RS 4
.RE
.IP "\(bu" 4
\&\f(CW\*(C`verbose\*(C'\fR
.Sp
A value indicating whether to log debug messages. If \f(CW\*(C`verbose\*(C'\fR is a coderef,
it is called to log debug messages. If \f(CW\*(C`verbose\*(C'\fR is not a coderef but is some
other true value, debug messages will be sent to \f(CW\*(C`STDERR\*(C'\fR. Otherwise, debug
messages will not be logged.
.IP "\(bu" 4
\&\f(CW\*(C`prioritize\*(C'\fR
.Sp
A value indicating whether to utilize the job 'priority' field when selecting
jobs to be processed. If unspecified, jobs will always be executed in a
randomized order.
.IP "\(bu" 4
\&\f(CW\*(C`floor\*(C'\fR
.Sp
A value indicating the minimum priority a job needs to be for this worker to 
perform. If unspecified all jobs are considered.
.IP "\(bu" 4
\&\f(CW\*(C`batch_size\*(C'\fR
.Sp
A value indicating how many jobs should be fetched from the \s-1DB\s0 for consideration.
.IP "\(bu" 4
\&\f(CW\*(C`driver_cache_expiration\*(C'\fR
.Sp
Optional value to control how long database connections are cached for in seconds.
By default, connections are not cached. To re-use the same database connection for
five minutes, pass driver_cache_expiration => 300 to the constructor. Improves job
throughput in cases where the work to process a job is small compared to the database
connection set-up and tear-down time.
.IP "\(bu" 4
\&\f(CW\*(C`retry_seconds\*(C'\fR
.Sp
The number of seconds after which to try reconnecting to apparently dead
databases. If not given, TheSchwartz will retry connecting to databases after
30 seconds.
.IP "\(bu" 4
\&\f(CW\*(C`strict_remove_ability\*(C'\fR
.Sp
By default when work_once does not find a job it will reset current_abilities to
all_abilities and look for a job. Setting this option will prevent work_once from
resetting abilities if it can't find a job for the current capabilities.
.ie n .SS """$client\->list_jobs( %args )"""
.el .SS "\f(CW$client\->list_jobs( %args )\fP"
.IX Subsection "$client->list_jobs( %args )"
Returns a list of \f(CW\*(C`TheSchwartz::Job\*(C'\fR objects matching the given arguments. The
required members of \f(CW%args\fR are:
.IP "\(bu" 4
\&\f(CW\*(C`funcname\*(C'\fR
.Sp
the name of the function or a reference to an array of functions
.IP "\(bu" 4
\&\f(CW\*(C`run_after\*(C'\fR
.Sp
the value you want to check <= against on the run_after column
.IP "\(bu" 4
\&\f(CW\*(C`grabbed_until\*(C'\fR
.Sp
the value you want to check <= against on the grabbed_until column
.IP "\(bu" 4
\&\f(CW\*(C`coalesce_op\*(C'\fR
.Sp
defaults to '=', set it to whatever you want to compare the coalesce field too
if you want to search, you can use '\s-1LIKE\s0'
.IP "\(bu" 4
\&\f(CW\*(C`coalesce\*(C'\fR
.Sp
coalesce value to search for, if you set op to '\s-1LIKE\s0' you can use '%' here,
do remember that '%' searches anchored at the beginning of the string are
much faster since it is can do a btree index lookup
.IP "\(bu" 4
\&\f(CW\*(C`want_handle\*(C'\fR
.Sp
if you want all your jobs to be set up using a handle.  defaults to true.
this option might be removed, as you should always have this on a Job object.
.IP "\(bu" 4
\&\f(CW\*(C`jobid\*(C'\fR
.Sp
if you want a specific job you can pass in it's \s-1ID\s0 and if it's available it
will be listed.
.PP
It is important to remember that this function does not lock anything, it just
returns as many jobs as there is up to amount of databases * \f(CW$client\fR\->{batch_size}
.ie n .SS """$client\->lookup_job( $handle_id )"""
.el .SS "\f(CW$client\->lookup_job( $handle_id )\fP"
.IX Subsection "$client->lookup_job( $handle_id )"
Returns a \f(CW\*(C`TheSchwartz::Job\*(C'\fR corresponding to the given handle \s-1ID.\s0
.ie n .SS """$client\->set_verbose( $verbose )"""
.el .SS "\f(CW$client\->set_verbose( $verbose )\fP"
.IX Subsection "$client->set_verbose( $verbose )"
Sets the current logging function to \f(CW$verbose\fR if it's a coderef. If not a
coderef, enables debug logging to \f(CW\*(C`STDERR\*(C'\fR if \f(CW$verbose\fR is true; otherwise,
disables logging.
.SH "POSTING JOBS"
.IX Header "POSTING JOBS"
The methods of TheSchwartz clients used by applications posting jobs to the
queue are:
.ie n .SS """$client\->insert( $job )"""
.el .SS "\f(CW$client\->insert( $job )\fP"
.IX Subsection "$client->insert( $job )"
Adds the given \f(CW\*(C`TheSchwartz::Job\*(C'\fR to one of the client's job databases.
.ie n .SS """$client\->insert( $funcname, $arg )"""
.el .SS "\f(CW$client\->insert( $funcname, $arg )\fP"
.IX Subsection "$client->insert( $funcname, $arg )"
Adds a new job with function name \f(CW$funcname\fR and arguments \f(CW$arg\fR to the queue.
.ie n .SS """$client\->insert_jobs( @jobs )"""
.el .SS "\f(CW$client\->insert_jobs( @jobs )\fP"
.IX Subsection "$client->insert_jobs( @jobs )"
Adds the given \f(CW\*(C`TheSchwartz::Job\*(C'\fR objects to one of the client's job
databases. All the given jobs are recorded in \fIone\fR job database.
.ie n .SS """$client\->set_prioritize( $prioritize )"""
.el .SS "\f(CW$client\->set_prioritize( $prioritize )\fP"
.IX Subsection "$client->set_prioritize( $prioritize )"
Set the \f(CW\*(C`prioritize\*(C'\fR value as described in the constructor.
.ie n .SS """$client\->set_floor( $floor )"""
.el .SS "\f(CW$client\->set_floor( $floor )\fP"
.IX Subsection "$client->set_floor( $floor )"
Set the \f(CW\*(C`floor<gt\*(C'\fR value as described in the constructor.
.ie n .SS """$client\->set_batch_size( $batch_size )"""
.el .SS "\f(CW$client\->set_batch_size( $batch_size )\fP"
.IX Subsection "$client->set_batch_size( $batch_size )"
Set the \f(CW\*(C`batch_size<gt\*(C'\fR value as described in the constructor.
.ie n .SS """$client\->set_strict_remove_ability( $strict_remove_ability )"""
.el .SS "\f(CW$client\->set_strict_remove_ability( $strict_remove_ability )\fP"
.IX Subsection "$client->set_strict_remove_ability( $strict_remove_ability )"
Set the \f(CW\*(C`strict_remove_ability<gt\*(C'\fR value as described in the constructor.
.SH "WORKING"
.IX Header "WORKING"
The methods of TheSchwartz clients for use in worker processes are:
.ie n .SS """$client\->can_do( $ability )"""
.el .SS "\f(CW$client\->can_do( $ability )\fP"
.IX Subsection "$client->can_do( $ability )"
Adds \f(CW$ability\fR to the list of abilities \f(CW$client\fR is capable of performing.
Subsequent calls to that client's \f(CW\*(C`work\*(C'\fR methods will find jobs requiring the
given ability.
.ie n .SS """$client\->work_once()"""
.el .SS "\f(CW$client\->work_once()\fP"
.IX Subsection "$client->work_once()"
Find and perform one job \f(CW$client\fR can do.
.ie n .SS """$client\->work_until_done()"""
.el .SS "\f(CW$client\->work_until_done()\fP"
.IX Subsection "$client->work_until_done()"
Find and perform jobs \f(CW$client\fR can do until no more such jobs are found in
any of the client's job databases.
.ie n .SS """$client\->work( [$delay] )"""
.el .SS "\f(CW$client\->work( [$delay] )\fP"
.IX Subsection "$client->work( [$delay] )"
Find and perform any jobs \f(CW$client\fR can do, forever. When no job is available,
the working process will sleep for \f(CW$delay\fR seconds (or 5, if not specified)
before looking again.
.ie n .SS """$client\->work_on($handle)"""
.el .SS "\f(CW$client\->work_on($handle)\fP"
.IX Subsection "$client->work_on($handle)"
Given a job handle (a scalar string) \fI\f(CI$handle\fI\fR, runs the job, then returns.
.ie n .SS """$client\->grab_and_work_on($handle)"""
.el .SS "\f(CW$client\->grab_and_work_on($handle)\fP"
.IX Subsection "$client->grab_and_work_on($handle)"
Similar to \f(CW$client\fR\->work_on($handle), except that the job will be grabbed
before being run. It guarantees that only one worker will work on it (at least
in the \f(CW\*(C`grab_for\*(C'\fR interval).
.PP
Returns false if the worker could not grab the job, and true if the worker worked
on it.
.ie n .SS """$client\->find_job_for_workers( [$abilities] )"""
.el .SS "\f(CW$client\->find_job_for_workers( [$abilities] )\fP"
.IX Subsection "$client->find_job_for_workers( [$abilities] )"
Returns a \f(CW\*(C`TheSchwartz::Job\*(C'\fR for a random job that the client can do. If
specified, the job returned matches one of the abilities in the arrayref
\&\f(CW$abilities\fR, rather than \f(CW$client\fR's abilities.
.ie n .SS """$client\->find_job_with_coalescing_value( $ability, $coval )"""
.el .SS "\f(CW$client\->find_job_with_coalescing_value( $ability, $coval )\fP"
.IX Subsection "$client->find_job_with_coalescing_value( $ability, $coval )"
Returns a \f(CW\*(C`TheSchwartz::Job\*(C'\fR for a random job for a worker capable of
\&\f(CW$ability\fR and with a coalescing value of \f(CW$coval\fR.
.ie n .SS """$client\->find_job_with_coalescing_prefix( $ability, $coval )"""
.el .SS "\f(CW$client\->find_job_with_coalescing_prefix( $ability, $coval )\fP"
.IX Subsection "$client->find_job_with_coalescing_prefix( $ability, $coval )"
Returns a \f(CW\*(C`TheSchwartz::Job\*(C'\fR for a random job for a worker capable of
\&\f(CW$ability\fR and with a coalescing value beginning with \f(CW$coval\fR.
.PP
Note the \f(CW\*(C`TheSchwartz\*(C'\fR implementation of this function uses a \f(CW\*(C`LIKE\*(C'\fR query to
find matching jobs, with all the attendant performance implications for your
job databases.
.ie n .SS """$client\->get_server_time( $driver )"""
.el .SS "\f(CW$client\->get_server_time( $driver )\fP"
.IX Subsection "$client->get_server_time( $driver )"
Given an open driver \fI\f(CI$driver\fI\fR to a database, gets the current server time from the database.
.SH "THE SCOREBOARD"
.IX Header "THE SCOREBOARD"
The scoreboards can be used to monitor what the TheSchwartz::Worker sub-classes are
currently working on.  Once the scoreboard has been enabled in the workers with
\&\f(CW\*(C`set_scoreboard\*(C'\fR method the \f(CW\*(C`thetop\*(C'\fR utility (shipped with TheSchwartz distribution
in the \f(CW\*(C`extras\*(C'\fR directory) can be used to list all current jobs being worked on.
.ie n .SS """$client\->set_scoreboard( $dir )"""
.el .SS "\f(CW$client\->set_scoreboard( $dir )\fP"
.IX Subsection "$client->set_scoreboard( $dir )"
Enables the scoreboard.  Setting this to \f(CW1\fR or \f(CW\*(C`on\*(C'\fR will cause TheSchwartz to create
a scoreboard file in a location it determines is optimal.
.PP
Passing in any other option sets the directory the TheSchwartz scoreboard directory should
be created in.  For example, if you set this to \f(CW\*(C`/tmp\*(C'\fR then this would create a directory
called \f(CW\*(C`/tmp/theschwartz\*(C'\fR and a scoreboard file \f(CW\*(C`/tmp/theschwartz/scoreboard.pid\*(C'\fR in it
(where pid is the current process pid.)
.ie n .SS """$client\->scoreboard()"""
.el .SS "\f(CW$client\->scoreboard()\fP"
.IX Subsection "$client->scoreboard()"
Returns the path to the current scoreboard file.
.ie n .SS """$client\->start_scoreboard()"""
.el .SS "\f(CW$client\->start_scoreboard()\fP"
.IX Subsection "$client->start_scoreboard()"
Writes the current job information to the scoreboard file (called by the worker
in work_safely before it actually starts working)
.ie n .SS """$client\->end_scoreboard()"""
.el .SS "\f(CW$client\->end_scoreboard()\fP"
.IX Subsection "$client->end_scoreboard()"
Appends the current job duration to the end of the scoreboard file (called by
the worker in work_safely once work has been completed)
.ie n .SS """$client\->clean_scoreboard()"""
.el .SS "\f(CW$client\->clean_scoreboard()\fP"
.IX Subsection "$client->clean_scoreboard()"
Removes the scoreboard file (but not the scoreboard directory.)  Automatically
called by TheSchwartz during object destruction (i.e. when the instance goes
out of scope)
.SH "PASSING IN AN EXISTING DRIVER"
.IX Header "PASSING IN AN EXISTING DRIVER"
You can pass in a existing \f(CW\*(C`Data::Object::Driver::DBI\*(C'\fR object which also allows you
to reuse exist Database handles like so:
.PP
.Vb 7
\&        my $dbh = DBI\->connect( $dsn, "root", "", {
\&                RaiseError => 1,
\&                PrintError => 0,
\&                AutoCommit => 1,
\&            } ) or die $DBI::errstr;
\&        my $driver = Data::ObjectDriver::Driver::DBI\->new( dbh => $dbh);
\&        return TheSchwartz\->new(databases => [{ driver => $driver }]);
.Ve
.PP
\&\fBNote\fR: it's important that the \f(CW\*(C`RaiseError\*(C'\fR and \f(CW\*(C`AutoCommit\*(C'\fR flags are 
set on the handle for various bits of functionality to work.
.SH "COPYRIGHT, LICENSE & WARRANTY"
.IX Header "COPYRIGHT, LICENSE & WARRANTY"
This software is Copyright 2007, Six Apart Ltd, cpan@sixapart.com. All
rights reserved.
.PP
TheSchwartz is free software; you may redistribute it and/or modify it
under the same terms as Perl itself.
.PP
TheSchwartz comes with no warranty of any kind.