
=head1 NAME

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


=head1 VERSION

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


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


=head1 DESCRIPTION

The L<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 C<taskqueuectrl> script much more
useful than using this module directly. However, the module is provided to
allow new tools to be built more easily.

=head1 INTERFACE 

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

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

The following parameters are supported in the hash.

=over 4

=item qdir

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

=item qname

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

=item sdir

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

=item sname

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

=item logger

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

=item out

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

=item serial

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

=back

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

Run the specified command with the given arguments.

=head2 $ctrl->synopsis

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

=head2 $ctrl->help

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

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

Take a series of command strings as C<@commands>, use C<$queue> to queue each
of commands as a task. Print the Id on success or an error message on failure.

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

=head2 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:

=over 4

=item verbose

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

=item active

Print the tasks that are currently being processed.

=item waiting

Print the tasks that are waiting to be processed.

=item scheduled

Print the tasks that are scheduled to be queued at a later time.

=back

If none of C<active>, C<waiting>, and C<scheduled> are supplied, all three sets
are printed.

=head2 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 C<$subcmd> has a value of C<task>, the C<$match> value is treated as a
task id. Since task ids are unique, this approach can only print at most one
task.

If the C<$subcmd> has a value of C<command>, the C<$match> value is treated as
a command name (without the arguments). This subcommand will print zero or more
tasks.

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

Print the names of the plugins to the screen. If the option parameter is the
string C<'verbose'> print the commands for each plugin as well as the plugin
name.

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

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

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

Schedule each of the commands in the C<@cmds> list as a separate task based at
a time determined by the C<$subcmd> and C<$value>. There are two potential
values for C<$subcmd>:

=over 4

=item at {time}

Schedule the commands at the epoch time supplied as the C<$value>.

=item after {seconds}

Schedule the commands after the C<$value> number of seconds.

=back

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

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

Unschedule each of the tasks specified by the list C<@id>. It's possible for
a valid task to not be able to be unscheduled, if it has moved to the waiting
queue.

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

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

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

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

=head2 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 C<$queue> and C<$sched> objects.

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

Perform I<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:

=over 4

=item verbose

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

=item scheduled

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

=item waiting

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

=back

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

=head1 DIAGNOSTICS

=over

=item C<< Argument to new is not a hashref. >>

=item C<< Missing required '%s' argument. >>

=item C<< Value of '%s' parameter (%s) is not valid. >>

=item C<< No command suppled to run. >>

=item C<< Unrecognized command '%s' to run. >>

=item C<< No command to queue. >>

=item C<< No task ids to unqueue. >>

=back


=head1 CONFIGURATION AND ENVIRONMENT

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

=head1 DEPENDENCIES

L<cPanel::TaskQueue> and L<Text::Wrap>

=head1 INCOMPATIBILITIES

None reported.

=head1 BUGS AND LIMITATIONS

No bugs have been reported.

=head1 AUTHOR

G. Wade Johnson  C<< wade@cpanel.net >>

=head1 LICENSE AND COPYRIGHT

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

