=head1  NAME

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

=head1 VERSION

This document describes Cpanel::TaskQueue::Task version 0.307.

=head1 SYNOPSIS

    use Cpanel::TaskQueue;

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

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

=head1  DESCRIPTION

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

=head1 PUBLIC METHODS

=over 4

=item Cpanel::TaskQueue::Task->new( $args_ref )

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

=over 4

=item I<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.

=item I<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.

=item I<id>

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

=item I<timeout>

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

=item I<retries>

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

=item I<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 I<userdata> structure.

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

=back

=item $q->clone()

Create a deep copy of the C<Cpanel::TaskQueue::Task> object.

=item $q->mutate( $hashref )

Clone the C<Cpanel::TaskQueue::Task> object and modify some of its properites.

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

=over 4

=item I<timeout>

=item I<retries>

=item I<userdata>

=back

These parameters act in much the same way as their counterparts in the C<new>
method above. The one difference is the I<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.

=back

=head2 ACCESSORS

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

=over 4

=item $t->command()

Returns the name of the task, without arguments

=item $t->full_command()

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

=item $t->argstring()

Returns the unparsed argument string.

=item $t->args()

Returns the list of parsed arguments.

=item $t->get_arg( $index )

Returns the argument at the supplied I<index>, C<undef> if there is no argument
at that index.

=item $t->timestamp()

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

=item $t->uuid()

Return the unique ID of this queue item.

=item $t->child_timeout()

Return timeout for a child process in seconds

=item $t->started()

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

=item $t->pid()

Return pid of the child process executing this command

=item $t->retries_remaining()

Return the current value of the remaining retries counter.

=item $t->get_userdata( $key )

Return the userdata associated with the supplied I<key> if any exists, otherwise return C<undef>.

=back

=head2 MUTATORS

These method modify the data in the C<Task>.

=over 4

=item $t->set_pid( $pid )

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

=item $t->begin()

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

=item $t->decrement_retries()

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

=back

=head2 CLASS METHODS

=over

=item Cpanel::TaskQueue::Task::is_valid_taskid( $taskid )

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

=back

=head1 DIAGNOSTICS

The following messages can be reported by this module:

=over 4

=item C<< Missing arguments. >>

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

=item C<< Args parameter must be a hash ref. >>

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

=item C<< Missing command string. >>

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

=item C<< Invalid Namespace UUID. >>

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

=item C<< Invalid id. >>

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

=item C<< Invalid child timeout. >>

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

=item C<< Invalid value for retries. >>

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

=item C<< Expected a hash reference for userdata value. >>

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

=item C<< Reference values not allowed as userdata. Keys containing references: %s. >>

The hash passed as the I<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.

=item C<< No userdata key specified. >>

No key name was passed to the C<get_userdata> method.

=back

=head1 DEPENDENCIES

None

=head1 INCOMPATIBILITIES

None reported.

=head1 BUGS AND LIMITATIONS

none reported.

=head1 SEE ALSO

Cpanel::TaskProcessor

=head1 LICENCE AND COPYRIGHT

Copyright (c) 2009, CPanel. All rights reserved.

This module is free software; you can redistribute it and/or
modify it under the same terms as Perl itself. See L<perlartistic>.

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