/ 
cPanel-TaskQueue-0.850
River stage zero No dependents
/ cPanel::TaskQueue::Scheduler

NAME

cPanel::TaskQueue::Scheduler - Priority queue of Tasks to Queue at some time in the future.

SYNOPSIS

use cPanel::TaskQueue;
use cPanel::TaskQueue::Scheduler;

my $queue = cPanel::TaskQueue->new( { name => 'tasks', state_dir => '/home/$user/.cpanel/state' } );
my $sched = cPanel::TaskQueue::Scheduler->new( { name => 'tasks', state_dir => '/home/$user/.cpanel/state' } );

$sched->schedule_task( 'init_quota', {delay_seconds=>10} );
$sched->schedule_task( 'edit_quota fred 0', {delay_seconds=>60} );

# ... some time later ...
# This processing loop is a it more complicated than the one for just
# the TaskQueue.
while (1) {
    eval {
        $sched->process_ready_tasks( $queue );
        if ( $queue->has_work_to_do() ) {
            $queue->process_next_task();
        }
        else {
            my $wait = $sched->seconds_until_next_task();
            next if defined $wait and 0 == $wait;

            $wait = $default_wait if !$wait || $wait > $default_wait;
            sleep $wait;
        }
    };
    Carp::carp "Exception detected: $@" if $@;
}

DESCRIPTION

This module provides the ability to schedule tasks for later insertion into a cPanel::TaskQueue.

PUBLIC METHODS

cPanel::TaskQueue::Scheduler->new( $hashref )

Creates a new TaskQueue::Scheduler object based on the parameters from the supplied hashref.

state_dir

This required parameter specifies a directory where the state should be written. This directory is created if it does not exist.

name

This required parameter specifies the name of the scheduler. This name is used to construct the name of the state file used to store the scheduler information.

state_timeout

This optional parameter specifies the timeout to use for flocking the state file. The value is in seconds and defaults to the cPanel::StateFile default value.

cache_timeout

Deprecated. Replaced by the state_timeout.

token

If a valid token parameter is supplied, recreate the Scheduler described by the token. This allows recreating access to a Scheduler that was instantiated in another process. It also helps support serializing information about a Scheduler as part of a defined task.

If a token is supplied, the name and state_dir parameters are ignored because the token encodes that information.

$s->get_name()

Returns the name of the Scheduler object.

$s->schedule_task( $command, $hashref )

Schedule the supplied command to be queued as described by the parameters in the supplied hashref. The hashref has three optional parameters that specify the scheduling time:

at_time

This parameter specifies a specific time in epoch seconds after which the command will be queued.

delay_seconds

This parameter specifies a number of seconds to wait before scheduling the supplied command. If both at_time and delay_seconds are specified, at_time is used.

attempts

Specifies retry count for the task to be rescheduled if the task times out.

$s->unschedule_task( $uuid )

Remove the task associated with the supplied uuid from the schedule, if it has not been processed yet. Returns true on success.

$s->get_token()

Returns an opaque string containing the information needed to construct a new copy of this scheduler. Normally used when requesting a new scheduling at a later point in time.

$s->throw( $msg )

Log the supplied message and die.

$s->warn( $msg )

Log the supplied message as a warning.

$s->info( $msg )

Log the supplied message as an informational message.

QUEUE INFORMATION

$s->peek_next_task()

Get a copy of the next Task to be scheduled or undef if the scheduler is empty.

Because of the nature of a task scheduler, there is no guarantee that this task will remain unscheduled after the method call. That is one reason that a copy is returned.

$s->is_task_scheduled( $uuid )

Does the specified uuid reference a task to be scheduled?

Because of the nature of a task scheduler, the particular uuid tested may be scheduled for processing immediately after the test. Therefore, a true answer is not as useful as it might seem. A false answer does tell us that the item is no longer waiting.

$s->when_is_task_scheduled( $uuid )

Returns the time (in epoch seconds) when the Task referenced by uuid is scheduled to be run or undef if uuid does not reference a valid task.

Because of the nature of a task scheduler, the particular uuid tested may be scheduled for processing immediately after the test.

$s->how_many_scheduled()

Gives a count at this particular point in time of the number of items currently in the scheduler. Since an item may be removed and processed any time the process_ready_tasks() method is called, this count may not be correct immediately after the method returns.

Most useful for the general case of telling if the queue is really full, or mostly empty.

$s->seconds_until_next_task()

Returns the number of seconds until the next task is ready to be processed, or undef if there are no tasks to process.

$s->snapshot_task_schedule()

Returns an array reference containing a series of hashes containing the time a task is scheduled to run and a copy of the task to run at that time. The first item in the array is guaranteed to be the next task to run. The order of the rest of the list is not guaranteed.

This lack of guarantee allows the internal code to be implemented as either a sorted array or a heap without requiring this method to fix up the array.

SCHEDULING

$s->process_ready_tasks( $queue )

This method takes all of the Tasks that have reached (or passed) their schedule time and passes them to the queue_task method of the supplied queue object. No object is removed from the scheduler unless queue_task runs without an exception.

In addition, the process of moving a Task from the scheduler to the queue replaces it's uuid, so don't expect the uuid from the scheduler to have any relation to the uuid of the same task in the TaskQueue.

Returns the number of tasks processed, 0 if there were no tasks to process.

$s->flush_all_tasks( $queue )

This method takes all Tasks, whether or not they have reached their schedule time and passes the to the queue_task method of the supplied queue object. No object is removed from the scheduler unless queue_task runs without an exception.

Returns a list of the uuids of all tasks that are scheduled.

Warning: This is almost certainly a bad idea. But, there are a few cases where the scheduling may need to be overridden.

$s->delete_all_tasks( $queue )

This method removes all Tasks from the scheduler without any processing.

Returns a count of the number of tasks that were removed.

Warning: This is almost certainly a bad idea. But, there are a few cases where the scheduled tasks may need to be discarded.

CACHE SUPPORT

These methods should not be used directly, they exist to support the cPanel::StateFile interface that persists the scheduler information to disk.

$q->load_from_cache( $fh )

This method loads the scheduler information from the disk state. It is called by the cPanel::StateFile object owned by this object.

The user of this class should never need to call this method.

$q->save_to_cache( $fh )

This method saves the scheduler information to the disk state. It is called by the cPanel::StateFile object owned by this object.

The user of this class should never need to call this method.

LOGGER OBJECT

By default, the Scheduler uses die and warn for all messages during runtime. However, it supports a mechanism that allows you to insert a logging/reporting system in place by providing an object to do the logging for us.

To provide a different method of logging/reporting, supply an object to do the logging as follows when useing the module.

use cPanel::TaskQueue::Scheduler ( '-logger' => $logger );

The supplied object should supply (at least) 3 methods: throw, warn, and info. When needed these methods will be called with the messages to be logged.

The throw method is expected to use die to exit the method. The others are expected to continue. For example, an appropriate class for Log::Log4perl might do something like the following:

package Policy::Log4perl;
use strict;
use warnings;
use Log::Log4perl;

sub new {
    my ($class) = shift;
    my $self = {
        logger => Log::Log4perl->get_logger( @_ )
    };
    return bless, $class;
}

sub throw {
    my $self = shift;
    $self->{logger}->error( @_ );
    die @_;
}

sub warn {
    my $self = shift;
    $self->{logger}->warn( @_ );
}

sub info {
    my $self = shift;
    $self->{logger}->info( @_ );
}

This would call the Log4perl code as errors or other messages result in messages.

This only works once for a given program, so you can't reset the policy in multiple modules and expect it to work.

In addition to setting a global logger, a new logger object can be supplied when creating a specific Scheduler object.

DIAGNOSTICS

The following messages can be reported by this module:

Invalid token.

The token parameter supplied to new is not of the correct form to be a cPanel::TaskQueue::Scheduler token.

No caching directory supplied.

The required state_dir parameter was missing when constructing the TaskQueue::Scheduler object. The object was not created.

No queue name supplied.

The required name parameter was missing when constructing the TaskQueue::Scheduler object. The object was not created.

Not a recognized TaskQueue Scheduler state file.
Invalid version of TaskQueue Scheduler state file.

Either the state file is invalid or it is not a cPanel::TaskQueue::Scheduler state file.

Cannot queue an empty command.

The command string supplied to schedule_task_* was either undef or empty.

Task with 0 retries not scheduled.

The Task supplied to one of the schedule_task* methods has a remaining retry count of 0. The task has been discarded. This is an informational message only.

No Task uuid argument passed to %s.

The specified method requires a uuid to specify which task to operate on. None was supplied.

No valid queue supplied.

The process_ready_tasks methods requires a TaskQueue as a parameter. (Or, at least, an object with a queue_task method.)

Not an even number of arguments to the cPanel::TaskQueue::Scheduler module

The parameters passed to the import method should be name/value pairs.

Policies already set elsewhere

Some other file has already set the policies.

Unrecognized policy '%s'

The only policy supported by cPanel::TaskQueue::Scheduler is -logger.

DEPENDENCIES

YAML::Syck

cPanel::TaskQueue, cPanel::TaskQueue::Task, cPanel::StateFile

INCOMPATIBILITIES

None reported.

BUGS AND LIMITATIONS

none reported.

SEE ALSO

cPanel::TaskQueue::Processor, cPanel::TaskQueue::Task, and cPanel::StateFile

LICENCE AND COPYRIGHT

Copyright (c) 2014, 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.