NAME

Work_Queue::Task - Perl Work Queue Task bindings.


SYNOPSIS

The objects and methods provided by this package correspond to the native C API in work_queue.h for task creation and manipulation. This module is automatically loaded with Work_Queue.

                use Work_Queue;
                my $t = Work_Queue::Task->new($command);
                $t->specify_input_file(local_name => 'some_name', remote_name => 'some_other_name');
                $t->specify_output_file('some_name');
                $q->submit($t);
                $t = $q->wait(5);
                if($t) {
                                my $resources = $t->resources_measured;
                                print $resources->{resident_memory}, '\n';
                }


METHODS

Work_Queue::Task

Work_Queue::Task->new('/some/command < input > output');

Create a new task specification.

command

The shell command line to be exected by the task.

specify_tag

Attach a user defined logical name to the task.

tag

The tag to be executed.

clone

Return a copy of this task.

specify_command

Set the command to be executed by the task.

command

The command to be executed.

specify_algorithm

Set the worker selection algorithm for task.

algorithm

One of the following algorithms to use in assigning a task to a worker:

WORK_QUEUE_SCHEDULE_FCFS
WORK_QUEUE_SCHEDULE_FILES
WORK_QUEUE_SCHEDULE_TIME
WORK_QUEUE_SCHEDULE_RAND

specify_preferred_host

Indicate that the task would be optimally run on a given host.

hostname

The hostname to which this task would optimally be sent.

specify_file

Add a file to the task.

local_name

The name of the file on local disk or shared filesystem.

remote_name

The name of the file at the execution site.

type

Must be one of the following values: $Work_Queue::WORK_QUEUE_INPUT or $Work_Queue::WORK_QUEUE_OUTPUT

flags

May be zero to indicate no special handling, or any of the following or'd together:

$Work_Queue::WORK_QUEUE_NOCACHE
$Work_Queue::WORK_QUEUE_CACHE
$Work_Queue::WORK_QUEUE_WATCH
cache

Legacy parameter for setting file caching attribute. By default this is enabled.

                $t->specify_file(local_name => ...);
                $t->specify_file(local_name => ..., remote_name => ..., );

specify_file_piece

Add a file piece to the task.

local_name

The name of the file on local disk or shared filesystem.

remote_name

The name of the file at the execution site.

start_byte

The starting byte offset of the file piece to be transferred.

end_byte

The ending byte offset of the file piece to be transferred.

type

Must be one of the following values: $Work_Queue::WORK_QUEUE_INPUT or $Work_Queue::WORK_QUEUE_OUTPUT.

flags

May be zero to indicate no special handling, or any of the following or'd together. See Work_Queue::Task->specify_file

cache

Legacy parameter for setting file caching attribute. By default this is enabled.

                $t->specify_file_piece(local_name => ..., start_byte => ..., ...);
                $t->specify_file_piece(local_name => ..., remote_name => ..., ...);

specify_input_file

Add a input file to the task.

This is just a wrapper for Work_Queue::Task->specify_file with type set to $Work_Queue::WORK_QUEUE_INPUT. If only one argument is given, it defaults to both local_name and remote_name.

specify_output_file

Add a output file to the task.

This is just a wrapper for Work_Queue::Task->specify_file with type set to $Work_Queue::WORK_QUEUE_OUTPUT. If only one argument is given, then it defaults to both local_name and remote_name.

specify_directory

Add a directory to the task.

local_name

The name of the directory on local disk or shared filesystem. Optional if the directory is empty.

remote_name

The name of the directory at the remote execution site.

type

Must be one of $Work_Queue::WORK_QUEUE_INPUT or $Work_Queue::WORK_QUEUE_OUTPUT.

flags May be zero to indicate no special handling. See Work_Queue::Task->specify_file.
recursive

Indicates whether just the directory (0) or the directory and all of its contents (1) should be included.

cache

Legacy parameter for setting file caching attribute. By default this is enabled.

Returns 1 if the task directory is successfully specified, 0 if either of @a local_name, or @a remote_name is null or @a remote_name is an absolute path.

specify_buffer

Add an input bufer to the task.

buffer

The contents of the buffer to pass as input.

remote_name

The name of the remote file to create.

flags

May take the same values as Work_Queue::Task->specify_file.

cache

Legacy parameter for setting file caching attribute. By default this is enabled.

specify_cores

Specify the number of cores the task requires.

n

Number of cores.

specify_memory

Specify the size of the memory the task requires.

n

Memory size, in megabytes.

specify_disk

Specify the size of disk the task requires.

n

Disk size, in megabytes.

specify_gpus

Specify the number of gpus the task requires.

n

Number of gpus.

specify_end_time

Indicate the maximum end time (in seconds from the Epoch) of this task.

seconds

Number of seconds.

specify_priority

Indicate the the priority of this task (larger means better priority, default is 0).

n

Integer priority.

tag

Get the tag value of the task.

priority

Get the priority value of the task.

command

Get the command line of the task.

algorithm

Get the algorithm specified for this task to be dispatched.

output

Get the standard output of the task. Must be called only after the task completes execution.

id

Get the task id number.

return_status

Get the exit code of the command executed by the task. Must be called only after the task completes execution.

result

Get the result of the task (successful, failed return_status, missing input file, missing output file).

Must be called only after the task completes execution.

total_submissions

Get the number of times the task has been resubmitted internally.

Must be called only after the task completes execution.

host

Get the address and port of the host on which the task ran. Must be called only after the task completes execution.

hostname

Get the name of the host on which the task ran. Must be called only after the task completes execution.

commit_time

Get the time at which this task was committed to a worker. Must be called only after the task completes execution.

submit_time

Get the time at which this task was submitted.

Must be called only after the task completes execution.

finish_time

Get the time at which this task was finished.

Must be called only after the task completes execution.

time_app_delay

Get the time spent in upper-level application (outside of work_queue_wait).

Must be called only after the task completes execution.

send_input_start

Get the time at which the task started to transfer input files.

Must be called only after the task completes execution.

send_input_finish

Get the time at which the task finished transferring input files.

Must be called only after the task completes execution.

execute_cmd_start

The time at which the task began.

Must be called only after the task completes execution.

execute_cmd_finish

Get the time at which the task finished (discovered by the master).

Must be called only after the task completes execution.

receive_output_start

Get the time at which the task started to transfer output files.

Must be called only after the task completes execution.

receive_output_finish

Get the time at which the task finished transferring output files.

Must be called only after the task completes execution.

total_bytes_received

Get the number of bytes received since task started receiving input data.

Must be called only after the task completes execution.

total_bytes_sent

Get the number of bytes sent since task started sending input data.

Must be called only after the task completes execution.

total_bytes_transferred

Get the number of bytes transferred since task started transferring input data.

Must be called only after the task completes execution.

total_transfer_time

Get the time comsumed in microseconds for transferring total_bytes_transferred.

Must be called only after the task completes execution.

cmd_execution_time

Get the time spent in microseconds for executing the command on the worker.

Must be called only after the task completes execution.

total_cmd_execution_time

        Get the time spent in microseconds for executing the command on any worker.
        Must be called only after the task completes execution.

resources_measured

        Get the resources measured when monitoring is enabled.
        Must be called only after the task completes execution.
                $t->resources_measured{bytes_read};
                $t->resources_measured{bytes_written};
                $t->resources_measured{cores};
                $t->resources_measured{cpu_time};
                $t->resources_measured{gpus};
                $t->resources_measured{max_concurrent_processes};
                $t->resources_measured{resident_memory};
                $t->resources_measured{resident_memory};
                $t->resources_measured{resident_memory};
                $t->resources_measured{swap_memory};
                $t->resources_measured{task_id};
                $t->resources_measured{total_processes};
                $t->resources_measured{virtual_memory};
                $t->resources_measured{wall_time};
                $t->resources_measured{workdir_footprint};
                $t->resources_measured{workdir_num_files};