NAME

    cPanel::TaskQueue::ChildProcessor - Processes an individual task from the cPanel::TaskQueue in a child process.

VERSION

    This document describes cPanel::TaskQueue::ChildProcessor version 0.503_04.

SYNOPSIS

    package NewTask;

    use base 'cPanel::TaskQueue::ChildProcessor';

    sub _do_child_task {
        my ($self, $task, $logger) = @_;
        
        # do something exciting.

        return;
    }

    sub is_valid_args {
        my ($self, $task) = @_;
        # all args must be numeric
        return !grep { /[^-\d]/ } @{$task->args()};
    }

    # 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) = @_;

        return 1800;
    }

DESCRIPTION

    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>.

    In addition, the class provides automatic timeout support for the child process.

PUBLIC METHODS

This interface of this class is defined by its base class cPanel::TaskQueue::Processor.

$proc->process_task( $task, $logger )

This method has been overridden from the base class to launch a child process and execute the _do_child_task method. If the _do_child_task method times out and the Task has retries remaining, the ChildProcessor will automatically reschedule the Task for later execution. The time delay is determined by the return value of the get_reschedule_delay method.

If you plan to override this method, you are better off deriving from cPanel::TaskQueue::Procesor and doing all of the work yourself.

$proc->retry_task( $task, $delay )

This method reschedules a task 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 delay parameter specifies how many seconds to delay before queuing the process again. It defaults to the value returned by get_child_timeout.

$proc->_do_child_task( $task, $logger )

This method is executed in a child process. It is provided a cPanel::TaskQueue::Task object and a logging object. See "#LOGGER OBJECT" in cPanel::TaskQueue for the interface of the $logger object.

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.

$proc->_do_timeout( $task )

Although you can perform any processing you want in _do_child_task 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 process_task method calls _do_timeout with the task description as an argument. You can then perform cleanup or possibly retry your task.

One word of warning, the processing in this method should be relatively fast.

$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 undef to use the default value specified by the cPanel::TaskQueue.

Subclasses may override this method to return a value different than the default.

$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 task 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.

Subclasses should override thius method to return a value different than the default.

DIAGNOSTICS

No child task defined.

Either this base class has been used directly as a processor for a command or the _do_child_task method was not overridden in a derived class.

In either case, the default behavior for _do_child_task is to throw an exception.

Failed to reschedule task.

Attempting to reschedule a task after timeout failed. This should never happen.

Unable to start a child process to handle the '%s' task

Unable to fork a child process to execute the task. Possibly too many processes are running?

CONFIGURATION AND ENVIRONMENT

cPanel::TaskQueue::ChildProcessor requires no configuration files or environment variables.

DEPENDENCIES

None

SEE ALSO

cPanel::TaskQueue, cPanel::TaskQueue::Processor, cPanel::TaskQueue::Task

INCOMPATIBILITIES

None reported.

BUGS AND LIMITATIONS

No bugs have been reported.

AUTHOR

G. Wade Johnson wade@cpanel.net

LICENCE AND COPYRIGHT

Copyright (c) 2011, cPanel, Inc. All rights reserved.

This module is free software; you can redistribute it and/or modify it under the same terms as Perl itself. See perlartistic.

DISCLAIMER OF WARRANTY

BECAUSE THIS SOFTWARE IS LICENSED FREE OF CHARGE, THERE IS NO WARRANTY FOR THE SOFTWARE, TO THE EXTENT PERMITTED BY APPLICABLE LAW. EXCEPT WHEN OTHERWISE STATED IN WRITING THE COPYRIGHT HOLDERS AND/OR OTHER PARTIES PROVIDE THE SOFTWARE "AS IS" WITHOUT WARRANTY OF ANY KIND, EITHER EXPRESSED OR IMPLIED, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE. THE ENTIRE RISK AS TO THE QUALITY AND PERFORMANCE OF THE SOFTWARE IS WITH YOU. SHOULD THE SOFTWARE PROVE DEFECTIVE, YOU ASSUME THE COST OF ALL NECESSARY SERVICING, REPAIR, OR CORRECTION.

IN NO EVENT UNLESS REQUIRED BY APPLICABLE LAW OR AGREED TO IN WRITING WILL ANY COPYRIGHT HOLDER, OR ANY OTHER PARTY WHO MAY MODIFY AND/OR REDISTRIBUTE THE SOFTWARE AS PERMITTED BY THE ABOVE LICENCE, BE LIABLE TO YOU FOR DAMAGES, INCLUDING ANY GENERAL, SPECIAL, INCIDENTAL, OR CONSEQUENTIAL DAMAGES ARISING OUT OF THE USE OR INABILITY TO USE THE SOFTWARE (INCLUDING BUT NOT LIMITED TO LOSS OF DATA OR DATA BEING RENDERED INACCURATE OR LOSSES SUSTAINED BY YOU OR THIRD PARTIES OR A FAILURE OF THE SOFTWARE TO OPERATE WITH ANY OTHER SOFTWARE), EVEN IF SUCH HOLDER OR OTHER PARTY HAS BEEN ADVISED OF THE POSSIBILITY OF SUCH DAMAGES.

cpanm cPanel::TaskQueue

perl -MCPAN -e shell
install cPanel::TaskQueue