cPanel::TaskQueue::Ctrl - A text-based interface for controlling a TaskQueue
This document describes cPanel::TaskQueue::Ctrl version 0.503_03
use cPanel::TaskQueue::Ctrl; my $ctrl = cPanel::TaskQueue::Ctrl->new( { qdir=> $queue_dir, qname=> $qname, sname => $qname } ); eval { $ctrl->run( @ARGV ); 1; } or do { print "$@\nSupported commands:\n\n"; print join( "\n", $ctrl->synopsis() ), "\n\n"; exit 1; };
The cPanel::TaskQueue system stores its queuing information in files on disk. Manipulating these files by hand is error-prone and can potentially corrupt the queue making further execution of tasks impossible. This module provides the tools needed to allow safe manipulation of a queue and associated scheduler.
As a general rule, most users will find the taskqueuectrl script much more useful than using this module directly. However, the module is provided to allow new tools to be built more easily.
taskqueuectrl
Constructs a cPanel::TaskQueue::Ctrl object. The supplied hashref determines the queue to manipulate.
cPanel::TaskQueue::Ctrl
The following parameters are supported in the hash.
This required parameter specifies the directory in which to find the queue file.
This required parameter is the name used when creating the queue.
This optional parameter specifies the directory in which to find the scheduler file. If not supplied, it defaults to the value of qdir.
This optional parameter is the name used when creating the scheduler. If not supplied, no scheduler is controlled.
This optional parameter specifies a logger object used by the TaskQueue and TaskQueue::Scheduler whenever they need to write output to the user.
TaskQueue
TaskQueue::Scheduler
Specify an output filehandle for printing. If not supplied, use the STDOUT handle instead.
Run the specified command with the given arguments.
Display a short help message describing the commands supported by this object.
Display a longer help message describing the commands supported by this object.
Take a series of command strings as @commands, use $queue to queue each of commands as a task. Print the Id on success or an error message on failure.
@commands
$queue
Given a list of Task ID strings, attempt to unqueue those tasks. Print a count of the number of tasks that were unqueued. This count could be less that the requested number of tasks if some of the tasks are being processed or have been completed in the time the function is running.
Print error messages for any unqueue attempt that fails.
Print information about the tasks. The list of options modifies which tasks are printed and in how much detail. The supported options are:
Print more information about the tasks. Without this option, only minimal information is printed.
Print the tasks that are currently being processed.
Print the tasks that are waiting to be processed.
Print the tasks that are scheduled to be queued at a later time.
If none of active, waiting, and scheduled are supplied, all three sets are printed.
active
waiting
scheduled
Find one or more tasks that match the supplied parameters. Print all of the tasks that were found.
If the $subcmd has a value of task, the $match value is treated as a task id. Since task ids are unique, this approach can only print at most one task.
$subcmd
task
$match
If the $subcmd has a value of command, the $match value is treated as a command name (without the arguments). This subcommand will print zero or more tasks.
command
Print the names of the plugins to the screen. If the option parameter is the string 'verbose' print the commands for each plugin as well as the plugin name.
'verbose'
Print the names of the commands supported by the loaded plugins.
Schedule each of the commands in the @cmds list as a separate task based at a time determined by the $subcmd and $value. There are two potential values for $subcmd:
@cmds
$value
Schedule the commands at the epoch time supplied as the $value.
Schedule the commands after the $value number of seconds.
If neither of these values applies, the commands will be scheduled right now.
Unschedule each of the tasks specified by the list @id. It's possible for a valid task to not be able to be unscheduled, if it has moved to the waiting queue.
@id
Display a summary of information about the $queue and $sched.
$sched
Argument to new is not a hashref.
Missing required '%s' argument.
Value of '%s' parameter (%s) is not valid.
No command suppled to run.
Unrecognized command '%s' to run.
No command to queue.
No task ids to unqueue.
cPanel::TaskQueue::Ctrl requires no configuration files or environment variables.
cPanel::TaskQueue and Text::Wrap
None reported.
No bugs have been reported.
G. Wade Johnson wade@cpanel.net
wade@cpanel.net
Copyright (c) 2011, cPanel, Inc. All rights reserved. This code is subject to the cPanel license. Unauthorized copying is prohibited
To install cPanel::TaskQueue, copy and paste the appropriate command in to your terminal.
cpanm
cpanm cPanel::TaskQueue
CPAN shell
perl -MCPAN -e shell install cPanel::TaskQueue
For more information on module installation, please visit the detailed CPAN module installation guide.