Product documentation
Develop for XenServer
8 Citrix Hypervisor 8.2 CU1
View PDF

Class: task

June 19, 2024
Contributed by: 
X X

A long-running asynchronous task

Fields for class: task

Field Type Qualifier Description
allowed_operations task_allowed_operations set RO/runtime list of the operations allowed in this state. This list is advisory only and the server state may have changed by the time this field is read by a client.
backtrace string RO/runtime Function call trace for debugging.
created datetime RO/runtime Time task was created
current_operations (string -> task_allowed_operations) map RO/runtime links each of the running tasks using this object (by reference) to a current_operation enum which describes the nature of the task.
error_info string set RO/runtime if the task has failed, this field contains the set of associated error strings. Undefined otherwise.
finished datetime RO/runtime Time task finished (i.e. succeeded or failed). If task-status is pending, then the value of this field has no meaning
name_description string RO/runtime a notes field containing human-readable description
name_label string RO/runtime a human-readable name
other_config (string -> string) map RW additional configuration
progress float RO/runtime This field contains the estimated fraction of the task which is complete. This field should not be used to determine whether the task is complete - for this the status field of the task should be used.
resident_on host ref RO/runtime the host on which the task is running
result string RO/runtime if the task has completed successfully, this field contains the result value (either Void or an object reference). Undefined otherwise.
status task_status_type RO/runtime current status of the task
subtask_of task ref RO/runtime Ref pointing to the task this is a substask of.
subtasks task ref set RO/runtime List pointing to all the substasks.
type string RO/runtime if the task has completed successfully, this field contains the type of the encoded result (i.e. name of the class whose reference is in the result field). Undefined otherwise.
uuid string RO/runtime Unique identifier/object reference

RPCs associated with class: task

RPC name: add_to_other_config

Overview:

Add the given key-value pair to the other_config field of the given task.

Signature:

void add_to_other_config (session ref session_ref, task ref self, string key, string value)
<!--NeedCopy-->

Arguments:

Type Name Description
session ref session_ref Reference to a valid session
task ref self reference to the object
string key Key to add
string value Value to add

Minimum Role: pool-operator

Return Type: void

RPC name: cancel

Overview:

Request that a task be cancelled. Note that a task may fail to be cancelled and may complete or fail normally and note that, even when a task does cancel, it might take an arbitrary amount of time.

Signature:

void cancel (session ref session_ref, task ref task)
<!--NeedCopy-->

Arguments:

Type Name Description
session ref session_ref Reference to a valid session
task ref task The task

Minimum Role: read-only

Return Type: void

Possible Error Codes: OPERATION_NOT_ALLOWED

RPC name: create

Overview:

Create a new task object which must be manually destroyed.

Signature:

task ref create (session ref session_ref, string label, string description)
<!--NeedCopy-->

Arguments:

Type Name Description
session ref session_ref Reference to a valid session
string label short label for the new task
string description longer description for the new task

Minimum Role: read-only

Return Type: task ref

The reference of the created task object

RPC name: destroy

Overview:

Destroy the task object

Signature:

void destroy (session ref session_ref, task ref self)
<!--NeedCopy-->

Arguments:

Type Name Description
session ref session_ref Reference to a valid session
task ref self Reference to the task object

Minimum Role: read-only

Return Type: void

RPC name: get_all

Overview:

Return a list of all the tasks known to the system.

Signature:

task ref set get_all (session ref session_ref)
<!--NeedCopy-->

Arguments:

Type Name Description
session ref session_ref Reference to a valid session

Minimum Role: read-only

Return Type: task ref set

references to all objects

RPC name: get_all_records

Overview:

Return a map of task references to task records for all tasks known to the system.

Signature:

(task ref -> task record) map get_all_records (session ref session_ref)
<!--NeedCopy-->

Arguments:

Type Name Description
session ref session_ref Reference to a valid session

Minimum Role: read-only

Return Type: (task ref -> task record) map

records of all objects

RPC name: get_allowed_operations

Overview:

Get the allowed_operations field of the given task.

Signature:

task_allowed_operations set get_allowed_operations (session ref session_ref, task ref self)
<!--NeedCopy-->

Arguments:

Type Name Description
session ref session_ref Reference to a valid session
task ref self reference to the object

Minimum Role: read-only

Return Type: task_allowed_operations set

value of the field

RPC name: get_backtrace

Overview:

Get the backtrace field of the given task.

Signature:

string get_backtrace (session ref session_ref, task ref self)
<!--NeedCopy-->

Arguments:

Type Name Description
session ref session_ref Reference to a valid session
task ref self reference to the object

Minimum Role: read-only

Return Type: string

value of the field

RPC name: get_by_name_label

Overview:

Get all the task instances with the given label.

Signature:

task ref set get_by_name_label (session ref session_ref, string label)
<!--NeedCopy-->

Arguments:

Type Name Description
session ref session_ref Reference to a valid session
string label label of object to return

Minimum Role: read-only

Return Type: task ref set

references to objects with matching names

RPC name: get_by_uuid

Overview:

Get a reference to the task instance with the specified UUID.

Signature:

task ref get_by_uuid (session ref session_ref, string uuid)
<!--NeedCopy-->

Arguments:

Type Name Description
session ref session_ref Reference to a valid session
string uuid UUID of object to return

Minimum Role: read-only

Return Type: task ref

reference to the object

RPC name: get_created

Overview:

Get the created field of the given task.

Signature:

datetime get_created (session ref session_ref, task ref self)
<!--NeedCopy-->

Arguments:

Type Name Description
session ref session_ref Reference to a valid session
task ref self reference to the object

Minimum Role: read-only

Return Type: datetime

value of the field

RPC name: get_current_operations

Overview:

Get the current_operations field of the given task.

Signature:

(string -> task_allowed_operations) map get_current_operations (session ref session_ref, task ref self)
<!--NeedCopy-->

Arguments:

Type Name Description
session ref session_ref Reference to a valid session
task ref self reference to the object

Minimum Role: read-only

Return Type: (string -> task_allowed_operations) map

value of the field

RPC name: get_error_info

Overview:

Get the error_info field of the given task.

Signature:

string set get_error_info (session ref session_ref, task ref self)
<!--NeedCopy-->

Arguments:

Type Name Description
session ref session_ref Reference to a valid session
task ref self reference to the object

Minimum Role: read-only

Return Type: string set

value of the field

RPC name: get_finished

Overview:

Get the finished field of the given task.

Signature:

datetime get_finished (session ref session_ref, task ref self)
<!--NeedCopy-->

Arguments:

Type Name Description
session ref session_ref Reference to a valid session
task ref self reference to the object

Minimum Role: read-only

Return Type: datetime

value of the field

RPC name: get_name_description

Overview:

Get the name/description field of the given task.

Signature:

string get_name_description (session ref session_ref, task ref self)
<!--NeedCopy-->

Arguments:

Type Name Description
session ref session_ref Reference to a valid session
task ref self reference to the object

Minimum Role: read-only

Return Type: string

value of the field

RPC name: get_name_label

Overview:

Get the name/label field of the given task.

Signature:

string get_name_label (session ref session_ref, task ref self)
<!--NeedCopy-->

Arguments:

Type Name Description
session ref session_ref Reference to a valid session
task ref self reference to the object

Minimum Role: read-only

Return Type: string

value of the field

RPC name: get_other_config

Overview:

Get the other_config field of the given task.

Signature:

(string -> string) map get_other_config (session ref session_ref, task ref self)
<!--NeedCopy-->

Arguments:

Type Name Description
session ref session_ref Reference to a valid session
task ref self reference to the object

Minimum Role: read-only

Return Type: (string -> string) map

value of the field

RPC name: get_progress

Overview:

Get the progress field of the given task.

Signature:

float get_progress (session ref session_ref, task ref self)
<!--NeedCopy-->

Arguments:

Type Name Description
session ref session_ref Reference to a valid session
task ref self reference to the object

Minimum Role: read-only

Return Type: float

value of the field

RPC name: get_record

Overview:

Get a record containing the current state of the given task.

Signature:

task record get_record (session ref session_ref, task ref self)
<!--NeedCopy-->

Arguments:

Type Name Description
session ref session_ref Reference to a valid session
task ref self reference to the object

Minimum Role: read-only

Return Type: task record

all fields from the object

RPC name: get_resident_on

Overview:

Get the resident_on field of the given task.

Signature:

host ref get_resident_on (session ref session_ref, task ref self)
<!--NeedCopy-->

Arguments:

Type Name Description
session ref session_ref Reference to a valid session
task ref self reference to the object

Minimum Role: read-only

Return Type: host ref

value of the field

RPC name: get_result

Overview:

Get the result field of the given task.

Signature:

string get_result (session ref session_ref, task ref self)
<!--NeedCopy-->

Arguments:

Type Name Description
session ref session_ref Reference to a valid session
task ref self reference to the object

Minimum Role: read-only

Return Type: string

value of the field

RPC name: get_status

Overview:

Get the status field of the given task.

Signature:

task_status_type get_status (session ref session_ref, task ref self)
<!--NeedCopy-->

Arguments:

Type Name Description
session ref session_ref Reference to a valid session
task ref self reference to the object

Minimum Role: read-only

Return Type: task_status_type

value of the field

RPC name: get_subtask_of

Overview:

Get the subtask_of field of the given task.

Signature:

task ref get_subtask_of (session ref session_ref, task ref self)
<!--NeedCopy-->

Arguments:

Type Name Description
session ref session_ref Reference to a valid session
task ref self reference to the object

Minimum Role: read-only

Return Type: task ref

value of the field

RPC name: get_subtasks

Overview:

Get the subtasks field of the given task.

Signature:

task ref set get_subtasks (session ref session_ref, task ref self)
<!--NeedCopy-->

Arguments:

Type Name Description
session ref session_ref Reference to a valid session
task ref self reference to the object

Minimum Role: read-only

Return Type: task ref set

value of the field

RPC name: get_type

Overview:

Get the type field of the given task.

Signature:

string get_type (session ref session_ref, task ref self)
<!--NeedCopy-->

Arguments:

Type Name Description
session ref session_ref Reference to a valid session
task ref self reference to the object

Minimum Role: read-only

Return Type: string

value of the field

RPC name: get_uuid

Overview:

Get the uuid field of the given task.

Signature:

string get_uuid (session ref session_ref, task ref self)
<!--NeedCopy-->

Arguments:

Type Name Description
session ref session_ref Reference to a valid session
task ref self reference to the object

Minimum Role: read-only

Return Type: string

value of the field

RPC name: remove_from_other_config

Overview:

Remove the given key and its corresponding value from the other_config field of the given task. If the key is not in that Map, then do nothing.

Signature:

void remove_from_other_config (session ref session_ref, task ref self, string key)
<!--NeedCopy-->

Arguments:

Type Name Description
session ref session_ref Reference to a valid session
task ref self reference to the object
string key Key to remove

Minimum Role: pool-operator

Return Type: void

RPC name: set_error_info

Overview:

Set the task error info

Signature:

void set_error_info (session ref session_ref, task ref self, string set value)
<!--NeedCopy-->

Arguments:

Type Name Description
session ref session_ref Reference to a valid session
task ref self Reference to the task object
string set value Task error info to be set

Minimum Role: read-only

Return Type: void

RPC name: set_other_config

Overview:

Set the other_config field of the given task.

Signature:

void set_other_config (session ref session_ref, task ref self, (string -> string) map value)
<!--NeedCopy-->

Arguments:

Type Name Description
session ref session_ref Reference to a valid session
task ref self reference to the object
(string -> string) map value New value to set

Minimum Role: pool-operator

Return Type: void

RPC name: set_progress

Overview:

Set the task progress

Signature:

void set_progress (session ref session_ref, task ref self, float value)
<!--NeedCopy-->

Arguments:

Type Name Description
session ref session_ref Reference to a valid session
task ref self Reference to the task object
float value Task progress value to be set

Minimum Role: read-only

Return Type: void

RPC name: set_result

Overview:

Set the task result

Signature:

void set_result (session ref session_ref, task ref self, string value)
<!--NeedCopy-->

Arguments:

Type Name Description
session ref session_ref Reference to a valid session
task ref self Reference to the task object
string value Task result to be set

Minimum Role: read-only

Return Type: void

RPC name: set_status

Overview:

Set the task status

Signature:

void set_status (session ref session_ref, task ref self, task_status_type value)
<!--NeedCopy-->

Arguments:

Type Name Description
session ref session_ref Reference to a valid session
task ref self Reference to the task object
task_status_type value task status value to be set

Minimum Role: read-only

Return Type: void

Class: task
June 19, 2024
Contributed by: 
X X
June 19, 2024
Contributed by: 
X X

In this article

Site feedback | Your privacy choices footer linkYour Privacy Choices | Privacy and legal terms | Consent settings | docs.cloud.com
© 1999- Cloud Software Group, Inc. All rights reserved.