.\" 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::Task 3"
.TH Cpanel::TaskQueue::Task 3 "2011-01-04" "perl v5.8.8" "User Contributed Perl Documentation"
.SH "NAME"
Cpanel::TaskQueue::Task \- Objects representing the task concept.
.SH "VERSION"
.IX Header "VERSION"
This document describes Cpanel::TaskQueue::Task 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
.SH "DESCRIPTION"
.IX Header "DESCRIPTION"
This module provides an abstraction for the tasks we insert into the
\&\f(CW\*(C`Cpanel::TaskQueue\*(C'\fR.  They should not be instantiated directly, the TaskQueue
object will handle that.
.SH "PUBLIC METHODS"
.IX Header "PUBLIC METHODS"
.ie n .IP "Cpanel::TaskQueue::Task\->new( $args_ref )" 4
.el .IP "Cpanel::TaskQueue::Task\->new( \f(CW$args_ref\fR )" 4
.IX Item "Cpanel::TaskQueue::Task->new( $args_ref )"
Creates a new Task object based on the parameters supplied in the hashref.
.RS 4
.IP "\fIcmd\fR" 4
.IX Item "cmd"
The command string that we will turn into a task. The string consists of a command
name and an optional whitespace-separated set of arguments. If an argument must
contain spaces, surround it with quotes.
.IP "\fInsid\fR" 4
.IX Item "nsid"
A namespace string used to generate a unique identifer for the Task. Must be a
non-empty string containing no ':' characters. Defaults to an internal \s-1UUID\s0.
.IP "\fIid\fR" 4
.IX Item "id"
A sequence number combined with the \fInsid\fR to create a unique Task \s-1ID\s0.
.IP "\fItimeout\fR" 4
.IX Item "timeout"
This is a number of seconds after which a child task should be timed out.
.IP "\fIretries\fR" 4
.IX Item "retries"
The initial value for the retry counter. Must be a positive integer.
.IP "\fIuserdata\fR" 4
.IX Item "userdata"
The value of this parameter is a hash containing data that the Task will maintain
on behalf of the user. This may be used to pass data from the scheduling process
to the running process that is inconvenient to store in the Processor. For
example, the data used to drive the retry code uses the \fIuserdata\fR structure.
.Sp
None of the values in the \fIuserdata\fR hash may be references (or objects). This
limitation reduces the possibility of Tasks that cannot be restored correctly
from disk.
.RE
.RS 4
.RE
.IP "$q\->\fIclone()\fR" 4
.IX Item "$q->clone()"
Create a deep copy of the \f(CW\*(C`Cpanel::TaskQueue::Task\*(C'\fR object.
.ie n .IP "$q\->mutate( $hashref )" 4
.el .IP "$q\->mutate( \f(CW$hashref\fR )" 4
.IX Item "$q->mutate( $hashref )"
Clone the \f(CW\*(C`Cpanel::TaskQueue::Task\*(C'\fR object and modify some of its properites.
.Sp
The \f(CW\*(C`mutate\*(C'\fR method supports hashref argument that contains small number of
named parameters for changing the assocatiated properties.
.RS 4
.IP "\fItimeout\fR" 4
.IX Item "timeout"
.PD 0
.IP "\fIretries\fR" 4
.IX Item "retries"
.IP "\fIuserdata\fR" 4
.IX Item "userdata"
.RE
.RS 4
.PD
.Sp
These parameters act in much the same way as their counterparts in the \f(CW\*(C`new\*(C'\fR
method above. The one difference is the \fIuserdata\fR parameter. This parameter
does not replace the user data from the original Task. Instead, the old user
data is merged with the data supplied by this parameter. Any data without a key
in the new hash is kept as it was, otherwise it is replaced by the new value.
.RE
.Sh "\s-1ACCESSORS\s0"
.IX Subsection "ACCESSORS"
There are accessors for each of the properties of the Task object.
.IP "$t\->\fIcommand()\fR" 4
.IX Item "$t->command()"
Returns the name of the task, without arguments
.IP "$t\->\fIfull_command()\fR" 4
.IX Item "$t->full_command()"
Returns the \f(CW\*(C`command\*(C'\fR and \f(CW\*(C`argstring\*(C'\fR values joined by a single space.
.IP "$t\->\fIargstring()\fR" 4
.IX Item "$t->argstring()"
Returns the unparsed argument string.
.IP "$t\->\fIargs()\fR" 4
.IX Item "$t->args()"
Returns the list of parsed arguments.
.ie n .IP "$t\->get_arg( $index )" 4
.el .IP "$t\->get_arg( \f(CW$index\fR )" 4
.IX Item "$t->get_arg( $index )"
Returns the argument at the supplied \fIindex\fR, \f(CW\*(C`undef\*(C'\fR if there is no argument
at that index.
.IP "$t\->\fItimestamp()\fR" 4
.IX Item "$t->timestamp()"
Return the time the item was added to the queue in epoch seconds.
.IP "$t\->\fIuuid()\fR" 4
.IX Item "$t->uuid()"
Return the unique \s-1ID\s0 of this queue item.
.IP "$t\->\fIchild_timeout()\fR" 4
.IX Item "$t->child_timeout()"
Return timeout for a child process in seconds
.IP "$t\->\fIstarted()\fR" 4
.IX Item "$t->started()"
Return the timestamp of the point in time the task started in epoch seconds.
.IP "$t\->\fIpid()\fR" 4
.IX Item "$t->pid()"
Return pid of the child process executing this command
.IP "$t\->\fIretries_remaining()\fR" 4
.IX Item "$t->retries_remaining()"
Return the current value of the remaining retries counter.
.ie n .IP "$t\->get_userdata( $key )" 4
.el .IP "$t\->get_userdata( \f(CW$key\fR )" 4
.IX Item "$t->get_userdata( $key )"
Return the userdata associated with the supplied \fIkey\fR if any exists, otherwise return \f(CW\*(C`undef\*(C'\fR.
.Sh "\s-1MUTATORS\s0"
.IX Subsection "MUTATORS"
These method modify the data in the \f(CW\*(C`Task\*(C'\fR.
.ie n .IP "$t\->set_pid( $pid )" 4
.el .IP "$t\->set_pid( \f(CW$pid\fR )" 4
.IX Item "$t->set_pid( $pid )"
Set the pid of the Task to the child process executing the Task.
.IP "$t\->\fIbegin()\fR" 4
.IX Item "$t->begin()"
Set the \fIstarted\fR time of the process to the current time in epoch seconds.
.IP "$t\->\fIdecrement_retries()\fR" 4
.IX Item "$t->decrement_retries()"
If the retry count is greater than 0, decrement it by one.
.Sh "\s-1CLASS\s0 \s-1METHODS\s0"
.IX Subsection "CLASS METHODS"
.ie n .IP "Cpanel::TaskQueue::Task::is_valid_taskid( $taskid )" 4
.el .IP "Cpanel::TaskQueue::Task::is_valid_taskid( \f(CW$taskid\fR )" 4
.IX Item "Cpanel::TaskQueue::Task::is_valid_taskid( $taskid )"
Returns true if the supplied \f(CW$taskid\fR is of the right form to be a Task id.
.SH "DIAGNOSTICS"
.IX Header "DIAGNOSTICS"
The following messages can be reported by this module:
.ie n .IP """Missing arguments.""" 4
.el .IP "\f(CWMissing arguments.\fR" 4
.IX Item "Missing arguments."
The \f(CW\*(C`new\*(C'\fR method was called with no hash ref to initialize the object state.
.ie n .IP """Args parameter must be a hash ref.""" 4
.el .IP "\f(CWArgs parameter must be a hash ref.\fR" 4
.IX Item "Args parameter must be a hash ref."
Incorrect parameter type for \f(CW\*(C`new\*(C'\fR method. Probably called the method with either positional arguments
or with named arguments outside an anonynmous hash.
.ie n .IP """Missing command string.""" 4
.el .IP "\f(CWMissing command string.\fR" 4
.IX Item "Missing command string."
The \fInew\fR method was called without a \fIcmd\fR parameter that lists the command to execute.
.ie n .IP """Invalid Namespace UUID.""" 4
.el .IP "\f(CWInvalid Namespace UUID.\fR" 4
.IX Item "Invalid Namespace UUID."
The method was called with something other than a 16\-byte binary \s-1UUID\s0 as the \fInsid\fR parameter.
.ie n .IP """Invalid id.""" 4
.el .IP "\f(CWInvalid id.\fR" 4
.IX Item "Invalid id."
The method was called with something other than a positive integer as the \fIid\fR parameter.
.ie n .IP """Invalid child timeout.""" 4
.el .IP "\f(CWInvalid child timeout.\fR" 4
.IX Item "Invalid child timeout."
The method was called with something other than a positive integer as the \fItimeout\fR parameter.
.ie n .IP """Invalid value for retries.""" 4
.el .IP "\f(CWInvalid value for retries.\fR" 4
.IX Item "Invalid value for retries."
The method was called with something other than a positive integer as the \fIretries\fR parameter.
.ie n .IP """Expected a hash reference for userdata value.""" 4
.el .IP "\f(CWExpected a hash reference for userdata value.\fR" 4
.IX Item "Expected a hash reference for userdata value."
The method was called with something other than a hash as the value of the \fIuserdata\fR parameter.
.ie n .IP """Reference values not allowed as userdata. Keys containing references: %s.""" 4
.el .IP "\f(CWReference values not allowed as userdata. Keys containing references: %s.\fR" 4
.IX Item "Reference values not allowed as userdata. Keys containing references: %s."
The hash passed as the \fIuserdata\fR value contained values that are references. This is currently not allowed.
The keys with the inappropriate data are listed at the end of the message.
.ie n .IP """No userdata key specified.""" 4
.el .IP "\f(CWNo userdata key specified.\fR" 4
.IX Item "No userdata key specified."
No key name was passed to the \f(CW\*(C`get_userdata\*(C'\fR method.
.SH "DEPENDENCIES"
.IX Header "DEPENDENCIES"
None
.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::TaskProcessor
.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.