.\" 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::ChildProcessor 3"
.TH Cpanel::TaskQueue::ChildProcessor 3 "2011-01-04" "perl v5.8.8" "User Contributed Perl Documentation"
.SH "NAME"
.Vb 1
\&    Cpanel::TaskQueue::ChildProcessor - Processes an individual task from the Cpanel::TaskQueue in a child process.
.Ve
.SH "VERSION"
.IX Header "VERSION"
.Vb 1
\&    This document describes Cpanel::TaskQueue::ChildProcessor version 0.307.
.Ve
.SH "SYNOPSIS"
.IX Header "SYNOPSIS"
.Vb 1
\&    package NewTask;
.Ve
.PP
.Vb 1
\&    use base 'Cpanel::TaskQueue::ChildProcessor';
.Ve
.PP
.Vb 2
\&    sub _do_child_task {
\&        my ($self, $task, $logger) = @_;
.Ve
.PP
.Vb 1
\&        # do something exciting.
.Ve
.PP
.Vb 2
\&        return;
\&    }
.Ve
.PP
.Vb 5
\&    sub is_valid_args {
\&        my ($self, $task) = @_;
\&        # all args must be numeric
\&        return !grep { /[^-\ed]/ } @{$task->args()};
\&    }
.Ve
.PP
.Vb 4
\&    # This task should take between 15-20 minutes to run, if it takes half an
\&    #   hour we need to fail
\&    sub get_child_timeout {
\&        my ($self) = @_;
.Ve
.PP
.Vb 2
\&        return 1800;
\&    }
.Ve
.SH "DESCRIPTION"
.IX Header "DESCRIPTION"
.Vb 4
\&    This module provides an abstraction for commands to be executed by a child
\&    process launched from the TaskQueue. It overrides the C<process_task> method
\&    to fork a child process and return the appropriate information back to
\&    C<Cpanel::TaskQueue>.
.Ve
.PP
.Vb 1
\&    In addition, the class provides automatic timeout support for the child process.
.Ve
.SH "PUBLIC METHODS"
.IX Header "PUBLIC METHODS"
This interface of this class is defined by its base class Cpanel::TaskQueue::Processor.
.ie n .IP "$proc\->process_task( $task\fR, \f(CW$logger )" 4
.el .IP "$proc\->process_task( \f(CW$task\fR, \f(CW$logger\fR )" 4
.IX Item "$proc->process_task( $task, $logger )"
This method has been overridden from the base class to launch a child process and
execute the \f(CW\*(C`_do_child_task\*(C'\fR method. If the \f(CW\*(C`_do_child_task\*(C'\fR method times out and
the Task has retries remaining, the \f(CW\*(C`ChildProcessor\*(C'\fR will automatically reschedule
the Task for later execution. The time delay is determined by the return value of the
\&\f(CW\*(C`get_reschedule_delay\*(C'\fR method.
.Sp
If you plan to override this method, you are better off deriving from
\&\f(CW\*(C`Cpanel::TaskQueue::Procesor\*(C'\fR and doing all of the work yourself.
.ie n .IP "$proc\->retry_task( $task\fR, \f(CW$delay )" 4
.el .IP "$proc\->retry_task( \f(CW$task\fR, \f(CW$delay\fR )" 4
.IX Item "$proc->retry_task( $task, $delay )"
This method reschedules a \fItask\fR to try again. It is called automatically when
a child process times out. However, the child process may determine that it has
failed and decide that rescheduling is necessary. This method provides a way for
the child process to easily reschedule itself. The optional \fIdelay\fR parameter
specifies how many seconds to delay before queuing the process again. It defaults
to the value returned by \f(CW\*(C`get_child_timeout\*(C'\fR.
.ie n .IP "$proc\->_do_child_task( $task\fR, \f(CW$logger )" 4
.el .IP "$proc\->_do_child_task( \f(CW$task\fR, \f(CW$logger\fR )" 4
.IX Item "$proc->_do_child_task( $task, $logger )"
This method is executed in a child process. It is provided a \f(CW\*(C`Cpanel::TaskQueue::Task\*(C'\fR
object and a logging object. See \*(L"#LOGGER \s-1OBJECT\s0\*(R" in Cpanel::TaskQueue
for the interface of the \f(CW$logger\fR object.
.Sp
A subclass must override this method to provide the needed behavior. This method
is called after the child process has already been forked, so this subroutine
will run in the child process.
.ie n .IP "$proc\->_do_timeout( $task )" 4
.el .IP "$proc\->_do_timeout( \f(CW$task\fR )" 4
.IX Item "$proc->_do_timeout( $task )"
Although you can perform any processing you want in \f(CW\*(C`_do_child_task\*(C'\fR if your
task is successful or if you determine it has failed. This method supplies an
entry point for handling the timeout case. If your process times out, the
\&\f(CW\*(C`process_task\*(C'\fR method calls \f(CW\*(C`_do_timeout\*(C'\fR with the task description as an
argument. You can then perform cleanup or possibly retry your task.
.Sp
One word of warning, the processing in this method should be relatively fast.
.IP "$proc\->\fIget_child_timeout()\fR" 4
.IX Item "$proc->get_child_timeout()"
This method should return a timeout value (in seconds) for the maximum time we
will wait for the child process to complete. Return 0 or \f(CW\*(C`undef\*(C'\fR to use the
default value specified by the \f(CW\*(C`Cpanel::TaskQueue\*(C'\fR.
.Sp
Subclasses may override this method to return a value different than the default.
.ie n .IP "$proc\->get_reschedule_delay( $task )" 4
.el .IP "$proc\->get_reschedule_delay( \f(CW$task\fR )" 4
.IX Item "$proc->get_reschedule_delay( $task )"
This method should return a number of seconds in the future to schedule the next
retry. The default value is 900 (15 minutes). The \fItask\fR parameter is supplied
in case it is needed to determine the delay. This could be useful in case you
want to schedule each succeeding retry farther in the future.
.Sp
Subclasses should override thius method to return a value different than the
default.
.SH "DIAGNOSTICS"
.IX Header "DIAGNOSTICS"
.ie n .IP """No child task defined.""" 4
.el .IP "\f(CWNo child task defined.\fR" 4
.IX Item "No child task defined."
Either this base class has been used directly as a processor for a command or
the \f(CW\*(C`_do_child_task\*(C'\fR method was not overridden in a derived class.
.Sp
In either case, the default behavior for \f(CW\*(C`_do_child_task\*(C'\fR is to throw an exception.
.ie n .IP """Failed to reschedule task.""" 4
.el .IP "\f(CWFailed to reschedule task.\fR" 4
.IX Item "Failed to reschedule task."
Attempting to reschedule a task after timeout failed. This should never happen.
.ie n .IP """Unable to start a child process to handle the '%s' task""" 4
.el .IP "\f(CWUnable to start a child process to handle the '%s' task\fR" 4
.IX Item "Unable to start a child process to handle the '%s' task"
Unable to \f(CW\*(C`fork\*(C'\fR a child process to execute the task. Possibly too many processes
are running?
.SH "CONFIGURATION AND ENVIRONMENT"
.IX Header "CONFIGURATION AND ENVIRONMENT"
Cpanel::TaskQueue::ChildProcessor requires no configuration files or environment variables.
.SH "DEPENDENCIES"
.IX Header "DEPENDENCIES"
None
.SH "SEE ALSO"
.IX Header "SEE ALSO"
Cpanel::TaskQueue, Cpanel::TaskQueue::Processor, Cpanel::TaskQueue::Task
.SH "INCOMPATIBILITIES"
.IX Header "INCOMPATIBILITIES"
None reported.
.SH "BUGS AND LIMITATIONS"
.IX Header "BUGS AND LIMITATIONS"
No bugs have been reported.
.SH "AUTHOR"
.IX Header "AUTHOR"
G. Wade Johnson  \f(CW\*(C`wade@cpanel.net\*(C'\fR
.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.