/ 
cPanel-TaskQueue-0.606
River stage zero No dependents
/ cPanel::TaskQueue::Task

NAME

cPanel::TaskQueue::Task - Objects representing the task concept.

VERSION

This document describes cPanel::TaskQueue::Task version 0.606.

SYNOPSIS

use cPanel::TaskQueue;

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

$queue->queue_task( "init_quota" );
$queue->queue_task( "edit_quota fred 0" );

DESCRIPTION

This module provides an abstraction for the tasks we insert into the cPanel::TaskQueue. They should not be instantiated directly, the TaskQueue object will handle that.

PUBLIC METHODS

cPanel::TaskQueue::Task->new( $args_ref )

Creates a new Task object based on the parameters supplied in the hashref.

cmd

The command string that we will turn into a task. The string consists of a command name and an optional whitespace-separated set of arguments. If an argument must contain spaces, surround it with quotes.

nsid

A namespace string used to generate a unique identifer for the Task. Must be a non-empty string containing no ':' characters. Defaults to an internal UUID.

id

A sequence number combined with the nsid to create a unique Task ID.

timeout

This is a number of seconds after which a child task should be timed out.

retries

The initial value for the retry counter. Must be a positive integer.

userdata

The value of this parameter is a hash containing data that the Task will maintain on behalf of the user. This may be used to pass data from the scheduling process to the running process that is inconvenient to store in the Processor. For example, the data used to drive the retry code uses the userdata structure.

None of the values in the userdata hash may be references (or objects). This limitation reduces the possibility of Tasks that cannot be restored correctly from disk.

cPanel::TaskQueue::Task->reconstitute( $task_hash )

Given a hash that represents the core of a Cpanel::TaskQueue::Task object, rebuild a task object to match this state. This class method supports rebuilding the Task objects after a serialize/deserialize round-trip that strips the type from the objects.

The method dies if any parameter is the wrong type or or if any parameters are missing. Extra parameters are discarded. The data is cloned to remove the chance that someone will mess with the object through the original hash.

$q->clone()

Create a deep copy of the cPanel::TaskQueue::Task object.

$q->mutate( $hashref )

Clone the cPanel::TaskQueue::Task object and modify some of its properites.

The mutate method supports hashref argument that contains small number of named parameters for changing the assocatiated properties.

timeout
retries
userdata

These parameters act in much the same way as their counterparts in the new method above. The one difference is the userdata parameter. This parameter does not replace the user data from the original Task. Instead, the old user data is merged with the data supplied by this parameter. Any data without a key in the new hash is kept as it was, otherwise it is replaced by the new value.

ACCESSORS

There are accessors for each of the properties of the Task object.

$t->command()

Returns the name of the task, without arguments

$t->full_command()

Returns the command and argstring values joined by a single space.

$t->argstring()

Returns the unparsed argument string.

$t->args()

Returns the list of parsed arguments.

$t->get_arg( $index )

Returns the argument at the supplied index, undef if there is no argument at that index.

$t->timestamp()

Return the time the item was added to the queue in epoch seconds.

$t->uuid()

Return the unique ID of this queue item.

$t->child_timeout()

Return timeout for a child process in seconds

$t->started()

Return the timestamp of the point in time the task started in epoch seconds.

$t->pid()

Return pid of the child process executing this command

$t->retries_remaining()

Return the current value of the remaining retries counter.

$t->get_userdata( $key )

Return the userdata associated with the supplied key if any exists, otherwise return undef.

MUTATORS

These method modify the data in the Task.

$t->set_pid( $pid )

Set the pid of the Task to the child process executing the Task.

$t->begin()

Set the started time of the process to the current time in epoch seconds.

$t->decrement_retries()

If the retry count is greater than 0, decrement it by one.

CLASS METHODS

cPanel::TaskQueue::Task::is_valid_taskid( $taskid )

Returns true if the supplied $taskid is of the right form to be a Task id.

DIAGNOSTICS

The following messages can be reported by this module:

Missing arguments.

The new method was called with no hash ref to initialize the object state.

Args parameter must be a hash ref.

Incorrect parameter type for new method. Probably called the method with either positional arguments or with named arguments outside an anonynmous hash.

Missing command string.

The new method was called without a cmd parameter that lists the command to execute.

Invalid Namespace UUID.

The method was called with something other than a 16-byte binary UUID as the nsid parameter.

Invalid id.

The method was called with something other than a positive integer as the id parameter.

Invalid child timeout.

The method was called with something other than a positive integer as the timeout parameter.

Invalid value for retries.

The method was called with something other than a positive integer as the retries parameter.

Expected a hash reference for userdata value.

The method was called with something other than a hash as the value of the userdata parameter.

Reference values not allowed as userdata. Keys containing references: %s.

The hash passed as the userdata value contained values that are references. This is currently not allowed. The keys with the inappropriate data are listed at the end of the message.

No userdata key specified.

No key name was passed to the get_userdata method.

DEPENDENCIES

None

INCOMPATIBILITIES

None reported.

BUGS AND LIMITATIONS

none reported.

SEE ALSO

cPanel::TaskProcessor

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.