File: //usr/local/ssl/local/share/man/man3/Cpanel::TaskQueue.3
.\" Automatically generated by Pod::Man v1.37, Pod::Parser v1.32
.\"
.\" Standard preamble:
.\" ========================================================================
.de Sh \" Subsection heading
.br
.if t .Sp
.ne 5
.PP
\fB\\$1\fR
.PP
..
.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. | will give a
.\" real vertical bar. \*(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-|\(bv\*(Tr
.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" ''
'br\}
.\"
.\" If the F register is turned on, we'll generate index entries on stderr for
.\" titles (.TH), headers (.SH), subsections (.Sh), items (.Ip), and index
.\" entries marked with X<> in POD. Of course, you'll have to process the
.\" output yourself in some meaningful fashion.
.if \nF \{\
. de IX
. tm Index:\\$1\t\\n%\t"\\$2"
..
. nr % 0
. rr F
.\}
.\"
.\" For nroff, turn off justification. Always turn off hyphenation; it makes
.\" way too many mistakes in technical documents.
.hy 0
.if n .na
.\"
.\" 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 "Cpanel::TaskQueue 3"
.TH Cpanel::TaskQueue 3 "2011-09-16" "perl v5.8.8" "User Contributed Perl Documentation"
.SH "NAME"
Cpanel::TaskQueue \- FIFO queue of tasks to perform
.SH "VERSION"
.IX Header "VERSION"
This document describes Cpanel::TaskQueue version 0.307
.SH "SYNOPSIS"
.IX Header "SYNOPSIS"
.Vb 1
\& use Cpanel::TaskQueue ();
.Ve
.PP
.Vb 1
\& my $queue = Cpanel::TaskQueue->new( { name => 'tasks', cache_dir => "/home/$user/.cpanel/cache" } );
.Ve
.PP
.Vb 2
\& $queue->queue_task( "init_quota" );
\& $queue->queue_task( "edit_quota fred 0" );
.Ve
.PP
.Vb 14
\& # Processing loop
\& while (1) {
\& # if work, process, else sleep
\& if ( $queue-has_work_to_do() ) {
\& eval { $queue->process_next_task() };
\& if ( $@ ) {
\& Carp::carp( $@ );
\& }
\& }
\& else {
\& # wait for work.
\& sleep 300;
\& }
\& }
.Ve
.SH "DESCRIPTION"
.IX Header "DESCRIPTION"
This module provides an abstraction for a \s-1FIFO\s0 queue of tasks that may be
executed asynchronously. Each command determines whether it runs in the
current process or forks a child to do the work in the background.
.PP
The TaskQueue has support for limiting the number of background tasks running
at one time and for preventing duplicate tasks from being scheduled.
.SH "PUBLIC METHODS"
.IX Header "PUBLIC METHODS"
.ie n .IP "Cpanel::TaskQueue\->new( $hashref )" 4
.el .IP "Cpanel::TaskQueue\->new( \f(CW$hashref\fR )" 4
.IX Item "Cpanel::TaskQueue->new( $hashref )"
Creates a new TaskQueue object based on the parameters from the supplied hashref.
.RS 4
.IP "\fIcache_dir\fR" 4
.IX Item "cache_dir"
This required parameter specifies a directory where the cache should be written.
This directory is created if it does not exist.
.IP "\fIname\fR" 4
.IX Item "name"
This required parameter specifies the name of the queue. This name is used to
construct the name of the cache file used to store the queue information.
.IP "\fIcache_timeout\fR" 4
.IX Item "cache_timeout"
This optional parameter specifies the timeout to use for flocking the cache file.
The value is in seconds and defaults to the Cpanel::CacheFile default value.
.IP "\fIdefault_timeout\fR" 4
.IX Item "default_timeout"
This optional parameter specifies the default amount of time (in seconds) to wait
for an in-process task to run. The default value is 60 seconds.
.Sp
This timeout may be overridden for a particular command by the
\&\f(CW\*(C`Cpanel::TaskQueue::Processor\*(C'\fR object.
.IP "\fImax_timeout\fR" 4
.IX Item "max_timeout"
This optional parameter specifies the maximum amount of time (in seconds) to wait
for an in-process task to run. The default value is 300 seconds (5 minutes).
.Sp
This value prevents a given \f(CW\*(C`Cpanel::TaskQueue::Processor\*(C'\fR object from setting the timeout
too high.
.IP "\fImax_running\fR" 4
.IX Item "max_running"
This optional parameter specifies the maximum number of child processes that the
queue will allow to be running at one time. If this number is reached, all queue
processing blocks until one or more child processes exit. The default value is 2.
.IP "\fIdefault_child_timeout\fR" 4
.IX Item "default_child_timeout"
This optional parameter specifies the default amount of time (in seconds) to wait
for a child task to run. The default value is 3600 seconds (1 hour).
.Sp
This timeout may be overridden for a particular command by the
\&\f(CW\*(C`Cpanel::TaskQueue::Processor\*(C'\fR object.
.RE
.RS 4
.Sp
If these parameters are not specified, but a \f(CW\*(C`TaskQueue\*(C'\fR with this \fIname\fR and
\&\fIcache_dir\fR has already been created, the new \f(CW\*(C`TaskQueue\*(C'\fR will use the parameters
that were stored in the file. This causes all instances of this \f(CW\*(C`TaskQueue\*(C'\fR
to act the same. Providing these parameters also updates all other instances of
this \f(CW\*(C`TaskQueue\*(C'\fR the next time they need to \f(CW\*(C`synch\*(C'\fR.
.RE
.ie n .IP "$q\->queue_task( $command )" 4
.el .IP "$q\->queue_task( \f(CW$command\fR )" 4
.IX Item "$q->queue_task( $command )"
Create a new task from the command and put it at the end of the queue if it meets
certain minimum criteria.
.RS 4
.IP "Command must be legal." 4
.IX Item "Command must be legal."
The command type must have been registered with the TaskQueue module.
.IP "Command must not duplicate a command already in the queue." 4
.IX Item "Command must not duplicate a command already in the queue."
Each command type can have it's own definition of duplicate. It can depend on
one or more of the arguments or not.
.RE
.RS 4
.Sp
If the task is successfully queued, a non-empty \fIuuid\fR is returned. This id can
be used to remove the task from the queue at a later time.
.Sp
If the task was not queued, a false value is returned.
.Sp
The \f(CW\*(C`queue_task\*(C'\fR method can also be called with a \f(CW\*(C`Cpanel::TaskQueue::Task\*(C'\fR
object which will be tested and inserted as usual.
.RE
.ie n .IP "$q\->unqueue_task( $uuid )" 4
.el .IP "$q\->unqueue_task( \f(CW$uuid\fR )" 4
.IX Item "$q->unqueue_task( $uuid )"
Remove the task associated with the supplied \fIuuid\fR from the queue, if it
has not been processed yet. Returns true on success.
.Sh "\s-1QUEUE\s0 \s-1PROCESSING\s0"
.IX Subsection "QUEUE PROCESSING"
.IP "$q\->\fIhas_work_to_do()\fR" 4
.IX Item "$q->has_work_to_do()"
Returns a true value if there are any tasks in the queue and we can process them.
This method does not block on child processes that are currently running if we
cannot launch a new task.
.IP "$q\->\fIprocess_next_task()\fR" 4
.IX Item "$q->process_next_task()"
This method is called to process another task from the wait queue.
.Sp
If there are any tasks remaining and we have not reached the limit of tasks we
can process at once, the next is removed from the queue. The task is checked to
make certain we know how to process it, if not it is discarded. Then it is added
to the processing list and the \f(CW\*(C`Cpanel::TaskQueue::Processor\*(C'\fR object for that
command is asked to process it. If we have reached our processing limit, block
until a task can be executed.
.Sp
If the command is completed by the \f(CW\*(C`Cpanel::TaskQueue::Processor\*(C'\fR, the task is
removed from the processing list. If the \f(CW\*(C`Cpanel::TaskQueue::Processor\*(C'\fR launched
a child process, the task is left in the processing list.
.Sp
The method returns true if the task was completed or otherwise removed from the
system. If the task was launched as a child process, the method returns false. The
method will also return true if there is nothing to process.
.IP "$q\->\fIfinish_all_processing()\fR" 4
.IX Item "$q->finish_all_processing()"
This method does not return until all tasks currently being processed in the
background are completed. It is most useful to call as part of shutdown of the
program that processes the queue. While waiting for processing to complete,
this method does not start any new tasks out of the queue.
.Sh "\s-1QUEUE\s0 \s-1INFORMATION\s0"
.IX Subsection "QUEUE INFORMATION"
.IP "$q\->get_default_child_timeout" 4
.IX Item "$q->get_default_child_timeout"
Returns the default timeout value for a child process.
.IP "$q\->get_default_timeout" 4
.IX Item "$q->get_default_timeout"
Returns the default timeout value for a task.
.IP "$q\->get_max_running" 4
.IX Item "$q->get_max_running"
Returns the maximum number of child processes that can be running at once.
.IP "$q\->get_max_timeout" 4
.IX Item "$q->get_max_timeout"
Returns the maximum timeout value for a task.
.IP "$q\->get_name" 4
.IX Item "$q->get_name"
Returns the TaskQueue's name.
.IP "$q\->\fIpeek_next_task()\fR" 4
.IX Item "$q->peek_next_task()"
Get a copy of the first task descriptor in the queue or \f(CW\*(C`undef\*(C'\fR if the queue is
empty.
.Sp
Because of the nature of a task queue, there is no guarantee that this task will
remain unscheduled after the method call. That is one reason that a copy is
returned.
.ie n .IP "$q\->is_task_queued( $uuid )" 4
.el .IP "$q\->is_task_queued( \f(CW$uuid\fR )" 4
.IX Item "$q->is_task_queued( $uuid )"
Does the specified \fIuuid\fR reference a task in the queue?
.Sp
Because of the nature of a task queue, the particular \fIuuid\fR tested may be scheduled
for processsing immediately after the test. Therefore, a true answer is not as useful as
it might seem. A false answer does tell us that the item is no longer waiting.
.ie n .IP "$q\->find_task( $uuid )" 4
.el .IP "$q\->find_task( \f(CW$uuid\fR )" 4
.IX Item "$q->find_task( $uuid )"
Returns a copy of the task in the queue with the supplied \fIuuid\fR. Returns
\&\f(CW\*(C`undef\*(C'\fR if no task with that \fIuuid\fR is found. Because of the nature of the
task queue, the task that is returned may not be in the queue shortly after
return from this method. Another process may have handled it and removed it from
the queue.
.Sp
However, the returned copy is a faithful representation of the task at the point
in time that it was found.
.ie n .IP "$q\->find_command( $command )" 4
.el .IP "$q\->find_command( \f(CW$command\fR )" 4
.IX Item "$q->find_command( $command )"
Returns a copy of the first command with the supplied \fIcommand\fR (sans
arguments). Returns \f(CW\*(C`undef\*(C'\fR if no task with that command name is found.
Because of the nature of the task queue, the task that is returned may not be
in the queue shortly after return from this method. Another process may have
handled it and removed it from the queue.
.Sp
Remember that \f(CW$command\fR is just the name of the command, not the whole
command string with arguments.
.IP "$q\->\fIhow_many_queued()\fR" 4
.IX Item "$q->how_many_queued()"
Gives a count at this particular point in time of the number of items currently
in the queue. Since an item may be removed and processed any time the
\&\f(CW\*(C`process_next_task()\*(C'\fR method is called, this count may not be correct immediately
after the method returns.
.Sp
Most useful for the general case of telling if the queue is really full, or mostly
empty.
.ie n .IP "$q\->is_task_processing( $uuid )" 4
.el .IP "$q\->is_task_processing( \f(CW$uuid\fR )" 4
.IX Item "$q->is_task_processing( $uuid )"
Does the specified \fIuuid\fR reference a task currently being processed?
.Sp
Because of the nature of a task queue, the particular \fIuuid\fR tested may be scheduled
for processsing or finish processing immediately after the test. I'm not sure if this
test is actually useful for anything.
.IP "$q\->\fIhow_many_in_process()\fR" 4
.IX Item "$q->how_many_in_process()"
Returns a count of the number of items currently being processed. Since a task
can complete at any time, the exact value returned by this method is not
guaranteed for any length of time after the method returns. May be useful to get
a statistical measure of how busy the \f(CW\*(C`Cpanel::TaskQueue\*(C'\fR system is.
.IP "$q\->\fIsnapshot_task_lists()\fR" 4
.IX Item "$q->snapshot_task_lists()"
Returns a reference to a hash containing copies of the current queues. The value
of \fIwaiting\fR is an array reference containing copies of all of the \f(CW\*(C`Task\*(C'\fRs
waiting to execute. The value of \fIprocessing\fR is an array reference containing
copies of all of the \f(CW\*(C`Tasks\*(C'\fR currently being processed.
.Sp
Since a task can complete at any time and whatever process handles the queue can
start processing a task at any time, the output of this method may be out of
date as soon as it returns. This method is only really useful for a general idea
of the state of the queue.
.Sh "\s-1CACHE\s0 \s-1SUPPORT\s0"
.IX Subsection "CACHE SUPPORT"
These methods should not be used directly, they exist to support the \f(CW\*(C`Cpanel::CacheFile\*(C'\fR
interface that persists the queue information to disk.
.ie n .IP "$q\->load_from_cache( $fh )" 4
.el .IP "$q\->load_from_cache( \f(CW$fh\fR )" 4
.IX Item "$q->load_from_cache( $fh )"
This method loads the queue information from the disk cache. It is called by the
\&\f(CW\*(C`Cpanel::CacheFile\*(C'\fR object owned by this object.
.Sp
The user of this class should never need to call this method.
.ie n .IP "$q\->save_to_cache( $fh )" 4
.el .IP "$q\->save_to_cache( \f(CW$fh\fR )" 4
.IX Item "$q->save_to_cache( $fh )"
This method saves the queue information to the disk cache. It is called by the
\&\f(CW\*(C`Cpanel::CacheFile\*(C'\fR object owned by this object.
.Sp
The user of this class should never need to call this method.
.ie n .IP "$q\->throw( $msg )" 4
.el .IP "$q\->throw( \f(CW$msg\fR )" 4
.IX Item "$q->throw( $msg )"
Log the supplied message and \f(CW\*(C`die\*(C'\fR.
.ie n .IP "$q\->warn( $msg )" 4
.el .IP "$q\->warn( \f(CW$msg\fR )" 4
.IX Item "$q->warn( $msg )"
Log the supplied message as a warning.
.ie n .IP "$q\->info( $msg )" 4
.el .IP "$q\->info( \f(CW$msg\fR )" 4
.IX Item "$q->info( $msg )"
Log the supplied message as an informational message.
.SH "CLASS METHODS"
.IX Header "CLASS METHODS"
The class also supports a few methods that apply to the Task Queuing system as a whole.
These methods manage the registering of task processing objects.
.ie n .IP "Cpanel::TaskQueue\->register_task_processor( $cmdname\fR, \f(CW$processor )" 4
.el .IP "Cpanel::TaskQueue\->register_task_processor( \f(CW$cmdname\fR, \f(CW$processor\fR )" 4
.IX Item "Cpanel::TaskQueue->register_task_processor( $cmdname, $processor )"
Add a task processing object for the command name given as the first argument.
The second argument must either be a \f(CW\*(C`Cpanel::TaskQueue::Processor\*(C'\fR\-derived object
or a code reference that will be wrapped in a \f(CW\*(C`Cpanel::TaskQueue::Processor::CodeRef\*(C'\fR
object.
.ie n .IP "Cpanel::TaskQueue\->unregister_task_processor( $cmdname )" 4
.el .IP "Cpanel::TaskQueue\->unregister_task_processor( \f(CW$cmdname\fR )" 4
.IX Item "Cpanel::TaskQueue->unregister_task_processor( $cmdname )"
Removes the task processing object for the command given as the only argument.
.Sp
After a call to this method, that particular command can not be queued any more
and any already queued objects will be discarded when the \f(CW\*(C`Cpanel::TaskQueue\*(C'\fR
tries to process them.
.SH "LOGGER OBJECT"
.IX Header "LOGGER OBJECT"
By default, the \f(CW\*(C`TaskQueue\*(C'\fR uses \f(CW\*(C`die\*(C'\fR and \f(CW\*(C`warn\*(C'\fR for all messages during
runtime. However, it supports a mechanism that allows you to insert a
logging/reporting system in place by providing an object to do the logging for
us.
.PP
To provide a different method of logging/reporting, supply an object to do the
logging as follows when \f(CW\*(C`use\*(C'\fRing the module.
.PP
.Vb 1
\& use Cpanel::TaskQueue ( '-logger' => $logger );
.Ve
.PP
The supplied object should supply (at least) 3 methods: \f(CW\*(C`throw\*(C'\fR, \f(CW\*(C`warn\*(C'\fR, and
\&\f(CW\*(C`info\*(C'\fR. When needed these methods will be called with the messages to be logged.
.PP
The \f(CW\*(C`throw\*(C'\fR method is expected to use \f(CW\*(C`die\*(C'\fR to exit the method. The others
are expected to continue. For example, an appropriate class for \f(CW\*(C`Log::Log4perl\*(C'\fR
might do something like the following:
.PP
.Vb 4
\& package Policy::Log4perl;
\& use strict;
\& use warnings;
\& use Log::Log4perl;
.Ve
.PP
.Vb 7
\& sub new {
\& my ($class) = shift;
\& my $self = {
\& logger => Log::Log4perl->get_logger( @_ )
\& };
\& return bless, $class;
\& }
.Ve
.PP
.Vb 5
\& sub throw {
\& my $self = shift;
\& $self->{logger}->error( @_ );
\& die @_;
\& }
.Ve
.PP
.Vb 4
\& sub warn {
\& my $self = shift;
\& $self->{logger}->warn( @_ );
\& }
.Ve
.PP
.Vb 4
\& sub info {
\& my $self = shift;
\& $self->{logger}->info( @_ );
\& }
.Ve
.PP
This would call the \f(CW\*(C`Log4perl\*(C'\fR code as errors or other messages result in
messages.
.PP
This only works once for a given program, so you can't reset the policy in
multiple modules and expect it to work.
.PP
In addition to setting a global logger, a new logger object can be supplied
when creating a specific \f(CW\*(C`TaskQueue\*(C'\fR object.
.SH "DIAGNOSTICS"
.IX Header "DIAGNOSTICS"
The following messages can be reported by this module:
.ie n .IP """Missing command in register_task_processor.""" 4
.el .IP "\f(CWMissing command in register_task_processor.\fR" 4
.IX Item "Missing command in register_task_processor."
No command name was given when calling the \f(CW\*(C`register_task_processor\*(C'\fR class
method to register a processing object to handle a command.
.ie n .IP """Missing task processor in register_task_processor.""" 4
.el .IP "\f(CWMissing task processor in register_task_processor.\fR" 4
.IX Item "Missing task processor in register_task_processor."
No command processor object was supplied when calling the \f(CW\*(C`register_task_processor\*(C'\fR
class method to register an action to attach to a command.
.ie n .IP """Command '%s' already has a TaskQueue::Processor registered.""" 4
.el .IP "\f(CWCommand '%s' already has a TaskQueue::Processor registered.\fR" 4
.IX Item "Command '%s' already has a TaskQueue::Processor registered."
The supplied command name already has a registered processing object. If you want
to change it, you must first remove the other processor using
\&\f(CW\*(C`unregister_task_processor\*(C'\fR.
.ie n .IP """Unrecognized task processor object.""" 4
.el .IP "\f(CWUnrecognized task processor object.\fR" 4
.IX Item "Unrecognized task processor object."
The second parameter to \f(CW\*(C`register_task_processor\*(C'\fR was not recognized as a
\&\f(CW\*(C`TaskQueue::Processor\*(C'\fR\-derived object or as a \f(CW\*(C`coderef\*(C'\fR.
.ie n .IP """Missing command in unregister_task_processor.""" 4
.el .IP "\f(CWMissing command in unregister_task_processor.\fR" 4
.IX Item "Missing command in unregister_task_processor."
No command name string was supplied when calling this method.
.ie n .IP """Command '%s' not registered, ignoring.""" 4
.el .IP "\f(CWCommand '%s' not registered, ignoring.\fR" 4
.IX Item "Command '%s' not registered, ignoring."
The supplied argument to \f(CW\*(C`unregister_task_processor\*(C'\fR was not a registered
command name.
.ie n .IP """No caching directory supplied.""" 4
.el .IP "\f(CWNo caching directory supplied.\fR" 4
.IX Item "No caching directory supplied."
The required \fIcache_dir\fR parameter was missing when constructing the \f(CW\*(C`TaskQueue\*(C'\fR
object. The object was not created.
.ie n .IP """No queue name supplied.""" 4
.el .IP "\f(CWNo queue name supplied.\fR" 4
.IX Item "No queue name supplied."
The required \fIname\fR parameter was missing when constructing the \f(CW\*(C`TaskQueue\*(C'\fR
object. The object was not created.
.ie n .IP """Not a recognized TaskQueue cache.""" 4
.el .IP "\f(CWNot a recognized TaskQueue cache.\fR" 4
.IX Item "Not a recognized TaskQueue cache."
.PD 0
.ie n .IP """Invalid version of TaskQueue cache.""" 4
.el .IP "\f(CWInvalid version of TaskQueue cache.\fR" 4
.IX Item "Invalid version of TaskQueue cache."
.PD
Either the cache file is invalid or it is not a TaskQueue cache file.
.ie n .IP """Cannot queue an empty command.""" 4
.el .IP "\f(CWCannot queue an empty command.\fR" 4
.IX Item "Cannot queue an empty command."
The command string supplied to \f(CW\*(C`queue_task\*(C'\fR was either \f(CW\*(C`undef\*(C'\fR or empty.
.ie n .IP """Task with 0 retries not queued.""" 4
.el .IP "\f(CWTask with 0 retries not queued.\fR" 4
.IX Item "Task with 0 retries not queued."
The \f(CW\*(C`Task\*(C'\fR supplied to \f(CW\*(C`queue_task\*(C'\fR has a remaining retry count of 0. The task
has been discarded. This is a warning message only.
.ie n .IP """No known processor for '%s'.""" 4
.el .IP "\f(CWNo known processor for '%s'.\fR" 4
.IX Item "No known processor for '%s'."
The specified command has no defined processor. The command has been discarded.
.ie n .IP """Requested command [%s] has invalid arguments.""" 4
.el .IP "\f(CWRequested command [%s] has invalid arguments.\fR" 4
.IX Item "Requested command [%s] has invalid arguments."
The supplied full command has arguments that are not valid as defined by the
command processor.
.ie n .IP """No Task uuid argument passed to %s.""" 4
.el .IP "\f(CWNo Task uuid argument passed to %s.\fR" 4
.IX Item "No Task uuid argument passed to %s."
The specified method requires a \fIuuid\fR to specify which task to operate
on. None was supplied.
.ie n .IP """No processor found for '%s'.""" 4
.el .IP "\f(CWNo processor found for '%s'.\fR" 4
.IX Item "No processor found for '%s'."
Either the program inserting tasks into the queue has a different list of commands
than the program processing the queue, or a TaskQueue::Processor was unregistered
after this command was queued.
.ie n .IP """Task '%s' timed out during processing.""" 4
.el .IP "\f(CWTask '%s' timed out during processing.\fR" 4
.IX Item "Task '%s' timed out during processing."
The supplied command timed out while being executed in\-process.
.ie n .IP """Undefined tasks found in the queue, removing...""" 4
.el .IP "\f(CWUndefined tasks found in the queue, removing...\fR" 4
.IX Item "Undefined tasks found in the queue, removing..."
Somehow a task item of \f(CW\*(C`undef\*(C'\fR has appeared in the queue. This should never
happen, so if it does, we remove them.
.SH "DEPENDENCIES"
.IX Header "DEPENDENCIES"
YAML::Syck, \s-1POSIX\s0
.PP
Cpanel::TaskQueue::Processor, Cpanel::TaskQueue::Task, Cpanel::CacheFile
.SH "INCOMPATIBILITIES"
.IX Header "INCOMPATIBILITIES"
None reported.
.SH "BUGS AND LIMITATIONS"
.IX Header "BUGS AND LIMITATIONS"
none reported.
.SH "SEE ALSO"
.IX Header "SEE ALSO"
Cpanel::TaskQueue::Processor, Cpanel::TaskQueue::Task, and Cpanel::CacheFile
.SH "LICENCE AND COPYRIGHT"
.IX Header "LICENCE AND COPYRIGHT"
Copyright (c) 2009, CPanel. All rights reserved.
.PP
This module is free software; you can redistribute it and/or
modify it under the same terms as Perl itself. See perlartistic.
.SH "DISCLAIMER OF WARRANTY"
.IX Header "DISCLAIMER OF WARRANTY"
\&\s-1BECAUSE\s0 \s-1THIS\s0 \s-1SOFTWARE\s0 \s-1IS\s0 \s-1LICENSED\s0 \s-1FREE\s0 \s-1OF\s0 \s-1CHARGE\s0, \s-1THERE\s0 \s-1IS\s0 \s-1NO\s0 \s-1WARRANTY\s0
\&\s-1FOR\s0 \s-1THE\s0 \s-1SOFTWARE\s0, \s-1TO\s0 \s-1THE\s0 \s-1EXTENT\s0 \s-1PERMITTED\s0 \s-1BY\s0 \s-1APPLICABLE\s0 \s-1LAW\s0. \s-1EXCEPT\s0 \s-1WHEN\s0
\&\s-1OTHERWISE\s0 \s-1STATED\s0 \s-1IN\s0 \s-1WRITING\s0 \s-1THE\s0 \s-1COPYRIGHT\s0 \s-1HOLDERS\s0 \s-1AND/OR\s0 \s-1OTHER\s0 \s-1PARTIES\s0
\&\s-1PROVIDE\s0 \s-1THE\s0 \s-1SOFTWARE\s0 \*(L"\s-1AS\s0 \s-1IS\s0\*(R" \s-1WITHOUT\s0 \s-1WARRANTY\s0 \s-1OF\s0 \s-1ANY\s0 \s-1KIND\s0, \s-1EITHER\s0
\&\s-1EXPRESSED\s0 \s-1OR\s0 \s-1IMPLIED\s0, \s-1INCLUDING\s0, \s-1BUT\s0 \s-1NOT\s0 \s-1LIMITED\s0 \s-1TO\s0, \s-1THE\s0 \s-1IMPLIED\s0
\&\s-1WARRANTIES\s0 \s-1OF\s0 \s-1MERCHANTABILITY\s0 \s-1AND\s0 \s-1FITNESS\s0 \s-1FOR\s0 A \s-1PARTICULAR\s0 \s-1PURPOSE\s0. \s-1THE\s0
\&\s-1ENTIRE\s0 \s-1RISK\s0 \s-1AS\s0 \s-1TO\s0 \s-1THE\s0 \s-1QUALITY\s0 \s-1AND\s0 \s-1PERFORMANCE\s0 \s-1OF\s0 \s-1THE\s0 \s-1SOFTWARE\s0 \s-1IS\s0 \s-1WITH\s0
\&\s-1YOU\s0. \s-1SHOULD\s0 \s-1THE\s0 \s-1SOFTWARE\s0 \s-1PROVE\s0 \s-1DEFECTIVE\s0, \s-1YOU\s0 \s-1ASSUME\s0 \s-1THE\s0 \s-1COST\s0 \s-1OF\s0 \s-1ALL\s0
\&\s-1NECESSARY\s0 \s-1SERVICING\s0, \s-1REPAIR\s0, \s-1OR\s0 \s-1CORRECTION\s0.
.PP
\&\s-1IN\s0 \s-1NO\s0 \s-1EVENT\s0 \s-1UNLESS\s0 \s-1REQUIRED\s0 \s-1BY\s0 \s-1APPLICABLE\s0 \s-1LAW\s0 \s-1OR\s0 \s-1AGREED\s0 \s-1TO\s0 \s-1IN\s0 \s-1WRITING\s0
\&\s-1WILL\s0 \s-1ANY\s0 \s-1COPYRIGHT\s0 \s-1HOLDER\s0, \s-1OR\s0 \s-1ANY\s0 \s-1OTHER\s0 \s-1PARTY\s0 \s-1WHO\s0 \s-1MAY\s0 \s-1MODIFY\s0 \s-1AND/OR\s0
\&\s-1REDISTRIBUTE\s0 \s-1THE\s0 \s-1SOFTWARE\s0 \s-1AS\s0 \s-1PERMITTED\s0 \s-1BY\s0 \s-1THE\s0 \s-1ABOVE\s0 \s-1LICENCE\s0, \s-1BE\s0
\&\s-1LIABLE\s0 \s-1TO\s0 \s-1YOU\s0 \s-1FOR\s0 \s-1DAMAGES\s0, \s-1INCLUDING\s0 \s-1ANY\s0 \s-1GENERAL\s0, \s-1SPECIAL\s0, \s-1INCIDENTAL\s0,
\&\s-1OR\s0 \s-1CONSEQUENTIAL\s0 \s-1DAMAGES\s0 \s-1ARISING\s0 \s-1OUT\s0 \s-1OF\s0 \s-1THE\s0 \s-1USE\s0 \s-1OR\s0 \s-1INABILITY\s0 \s-1TO\s0 \s-1USE\s0
\&\s-1THE\s0 \s-1SOFTWARE\s0 (\s-1INCLUDING\s0 \s-1BUT\s0 \s-1NOT\s0 \s-1LIMITED\s0 \s-1TO\s0 \s-1LOSS\s0 \s-1OF\s0 \s-1DATA\s0 \s-1OR\s0 \s-1DATA\s0 \s-1BEING\s0
\&\s-1RENDERED\s0 \s-1INACCURATE\s0 \s-1OR\s0 \s-1LOSSES\s0 \s-1SUSTAINED\s0 \s-1BY\s0 \s-1YOU\s0 \s-1OR\s0 \s-1THIRD\s0 \s-1PARTIES\s0 \s-1OR\s0 A
\&\s-1FAILURE\s0 \s-1OF\s0 \s-1THE\s0 \s-1SOFTWARE\s0 \s-1TO\s0 \s-1OPERATE\s0 \s-1WITH\s0 \s-1ANY\s0 \s-1OTHER\s0 \s-1SOFTWARE\s0), \s-1EVEN\s0 \s-1IF\s0
\&\s-1SUCH\s0 \s-1HOLDER\s0 \s-1OR\s0 \s-1OTHER\s0 \s-1PARTY\s0 \s-1HAS\s0 \s-1BEEN\s0 \s-1ADVISED\s0 \s-1OF\s0 \s-1THE\s0 \s-1POSSIBILITY\s0 \s-1OF\s0
\&\s-1SUCH\s0 \s-1DAMAGES\s0.