/ 
cPanel-TaskQueue-0.603
River stage zero No dependents
/ cPanel::TaskQueue::Ctrl

NAME

cPanel::TaskQueue::Ctrl - A text-based interface for controlling a TaskQueue

VERSION

This document describes cPanel::TaskQueue::Ctrl version 0.603

SYNOPSIS

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;
};

DESCRIPTION

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.

INTERFACE

cPanel::TaskQueue::Ctrl->new( $args )

Constructs a cPanel::TaskQueue::Ctrl object. The supplied hashref determines the queue to manipulate.

The following parameters are supported in the hash.

qdir

This required parameter specifies the directory in which to find the queue file.

qname

This required parameter is the name used when creating the queue.

sdir

This optional parameter specifies the directory in which to find the scheduler file. If not supplied, it defaults to the value of qdir.

sname

This optional parameter is the name used when creating the scheduler. If not supplied, no scheduler is controlled.

logger

This optional parameter specifies a logger object used by the TaskQueue and TaskQueue::Scheduler whenever they need to write output to the user.

out

Specify an output filehandle for printing. If not supplied, use the STDOUT handle instead.

serial

Specify which serializer to use. Valid values are storable and yaml. If no serializer type is specified, the default (storable) will be used.

$ctrl->run( $cmd, @args )

Run the specified command with the given arguments.

$ctrl->synopsis

Display a short help message describing the commands supported by this object.

$ctrl->help

Display a longer help message describing the commands supported by this object.

queue_tasks( $fh, $queue, $sched, @commands )

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.

unqueue_tasks( $ctrl, $fh, $queue, $sched, @task_ids )

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.

list_tasks( $ctrl, $fh, $queue, $sched, @options )

Print information about the tasks. The list of options modifies which tasks are printed and in how much detail. The supported options are:

verbose

Print more information about the tasks. Without this option, only minimal information is printed.

active

Print the tasks that are currently being processed.

waiting

Print the tasks that are waiting to be processed.

scheduled

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.

find_task( $ctrl, $fh, $queue, $sched, $subcmd, $match )

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.

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.

list_plugins( $ctrl, $fh, $queue, $sched, $option )

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.

list_commands( $ctrl, $fh, $queue, $sched )

Print the names of the commands supported by the loaded plugins.

schedule_tasks( $ctrl, $fh, $queue, $sched, [ $subcmd, $value, ] @cmds )

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:

at {time}

Schedule the commands at the epoch time supplied as the $value.

after {seconds}

Schedule the commands after the $value number of seconds.

If neither of these values applies, the commands will be scheduled right now.

unschedule_tasks( $ctrl, $fh, $queue, $sched, @ids )

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.

queue_status( $ctrl, $fh, $queue, $sched )

Display a summary of information about the $queue and $sched.

convert_state_files( $ctrl, $fh, $queue, $sched, $fmt )

Convert the state files for the $queue and $sched to the format described by $fmt and exit the program. Modify the $ctrl object to use the new serialization method on subsequent attempts to create the queue and scheduler.

display_queue_info( $ctrl, $fh, $queue, $sched )

Write general infomration about the TaskQueue and Scheduler to the supplied filehandle. The information includes the serialization type, and the full names of the state files for $queue and $sched objects.

process_one_step( $ctrl, $fh, $queue, $sched, @args )

Perform One step's worth of processing on the queue, the scheduler, or both. How much processing is performed depends on the supplied arguments. The supported arguments are:

verbose

If this argument is supplied, the subroutine writes more output to the supplied file handle to tell the user what is happening.

scheduled

If this argument is supplied, any scheduled items that have reached their activation time will be queued.

waiting

If this argument is supplied, one waiting task is started if we have space in the active queue.

If neither scheduled or waiting are supplied, the routine acts as if both were supplied.

DIAGNOSTICS

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.

CONFIGURATION AND ENVIRONMENT

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

DEPENDENCIES

cPanel::TaskQueue and Text::Wrap

INCOMPATIBILITIES

None reported.

BUGS AND LIMITATIONS

No bugs have been reported.

AUTHOR

G. Wade Johnson wade@cpanel.net

LICENSE AND COPYRIGHT

Copyright (c) 2012, cPanel, Inc. All rights reserved. This code is subject to the cPanel license. Unauthorized copying is prohibited