cctools
|
Python Work Queue object. More...
Public Member Functions | |
def | __init__ |
Create a new work queue. More... | |
def | name |
Get the project name of the queue. More... | |
def | port |
Get the listening port of the queue. More... | |
def | stats |
Get queue statistics. More... | |
def | stats_hierarchy |
Get worker hierarchy statistics. More... | |
def | stats_category |
Get the task statistics for the given category. More... | |
def | specify_category_mode |
Turn on or off first-allocation labeling for a given category. More... | |
def | specify_category_autolabel_resource |
Turn on or off first-allocation labeling for a given category and resource. More... | |
def | task_state |
Get current task state. More... | |
def | enable_monitoring |
Enables resource monitoring of tasks in the queue, and writes a summary per task to the directory given. More... | |
def | enable_monitoring_full |
As enable_monitoring, but it also generates a time series and a debug file. More... | |
def | activate_fast_abort |
Turn on or off fast abort functionality for a given queue for tasks in the "default" category, and for task which category does not set an explicit multiplier. More... | |
def | activate_fast_abort_category |
Turn on or off fast abort functionality for a given queue. More... | |
def | empty |
Determine whether there are any known tasks queued, running, or waiting to be collected. More... | |
def | hungry |
Determine whether the queue can support more tasks. More... | |
def | specify_algorithm |
Set the worker selection algorithm for queue. More... | |
def | specify_task_order |
Set the order for dispatching submitted tasks in the queue. More... | |
def | specify_name |
Change the project name for the given queue. More... | |
def | specify_master_preferred_connection |
Set the preference for using hostname over IP address to connect. More... | |
def | specify_min_taskid |
Set the minimum taskid of future submitted tasks. More... | |
def | specify_priority |
Change the project priority for the given queue. More... | |
def | specify_num_tasks_left |
Specify the number of tasks not yet submitted to the queue. More... | |
def | specify_master_mode |
Specify the master mode for the given queue. More... | |
def | specify_catalog_server |
Specify the catalog server the master should report to. More... | |
def | specify_log |
Specify a log file that records the cummulative stats of connected workers and submitted tasks. More... | |
def | specify_transactions_log |
Specify a log file that records the states of tasks. More... | |
def | specify_password |
Add a mandatory password that each worker must present. More... | |
def | specify_password_file |
Add a mandatory password file that each worker must present. More... | |
def | specify_max_resources |
Specifies the maximum resources allowed for the default category. More... | |
def | specify_category_max_resources |
Specifies the maximum resources allowed for the given category. More... | |
def | specify_category_first_allocation_guess |
Specifies the first-allocation guess for the given category. More... | |
def | initialize_categories |
Initialize first value of categories. More... | |
def | cancel_by_taskid |
Cancel task identified by its taskid and remove from the given queue. More... | |
def | cancel_by_tasktag |
Cancel task identified by its tag and remove from the given queue. More... | |
def | shutdown_workers |
Shutdown workers connected to queue. More... | |
def | blacklist |
Blacklist workers running on host. More... | |
def | blacklist_with_timeout |
Blacklist workers running on host for the duration of the given timeout. More... | |
def | blacklist_clear |
Remove host from blacklist. More... | |
def | specify_keepalive_interval |
Change keepalive interval for a given queue. More... | |
def | specify_keepalive_timeout |
Change keepalive timeout for a given queue. More... | |
def | estimate_capacity |
Turn on master capacity measurements. More... | |
def | tune |
Tune advanced parameters for work queue. More... | |
def | submit |
Submit a task to the queue. More... | |
def | wait |
Wait for tasks to complete. More... | |
Python Work Queue object.
This class uses a dictionary to map between the task pointer objects and the work_queue.Task.
def work_queue.WorkQueue.__init__ | ( | self, | |
port = WORK_QUEUE_DEFAULT_PORT , |
|||
name = None , |
|||
catalog = False , |
|||
exclusive = True , |
|||
shutdown = False |
|||
) |
Create a new work queue.
self | Reference to the current work queue object. |
port | The port number to listen on. If zero is specified, then the default is chosen, and if -1 is specified, a random port is chosen. |
name | The project name to use. |
catalog | Whether or not to enable catalog mode. |
exclusive | Whether or not the workers should be exclusive. |
shutdown | Automatically shutdown workers when queue is finished. Disabled by default. |
References work_queue.WorkQueue.__free_queue(), work_queue.WorkQueue._shutdown, work_queue.WorkQueue._stats, work_queue.WorkQueue._stats_hierarchy, work_queue.WorkQueue._task_table, work_queue.WorkQueue._work_queue, work_queue.WorkQueue.shutdown_workers(), work_queue_create(), work_queue_delete(), work_queue_specify_master_mode(), and work_queue_specify_name().
def work_queue.WorkQueue.name | ( | self | ) |
Get the project name of the queue.
Note: This is defined using property decorator. So it must be called without parentheses (). For example:
References work_queue.WorkQueue._work_queue, and work_queue_name().
def work_queue.WorkQueue.port | ( | self | ) |
Get the listening port of the queue.
Note: This is defined using property decorator. So it must be called without parentheses (). For example:
References work_queue.WorkQueue._work_queue, and work_queue_port().
def work_queue.WorkQueue.stats | ( | self | ) |
Get queue statistics.
Note: This is defined using property decorator. So it must be called without parentheses (). For example:
The fields in stats can also be individually accessed through this call. For example:
References work_queue.WorkQueue._stats, work_queue.WorkQueue._work_queue, and work_queue_get_stats().
def work_queue.WorkQueue.stats_hierarchy | ( | self | ) |
Get worker hierarchy statistics.
Note: This is defined using property decorator. So it must be called without parentheses (). For example:
The fields in stats_hierarchy can also be individually accessed through this call. For example:
References work_queue.WorkQueue._stats_hierarchy, work_queue.WorkQueue._work_queue, and work_queue_get_stats_hierarchy().
def work_queue.WorkQueue.stats_category | ( | self, | |
category | |||
) |
Get the task statistics for the given category.
self | Reference to the current work queue object. |
category | A category name. For example: The fields in work_queue_stats can also be individually accessed through this call. For example: |
References work_queue.WorkQueue._work_queue, and work_queue_get_stats_category().
def work_queue.WorkQueue.specify_category_mode | ( | self, | |
category, | |||
mode | |||
) |
Turn on or off first-allocation labeling for a given category.
By default, only cores, memory, and disk are labeled. Turn on/off other specific resources with specify_category_autolabel_resource. NOTE: autolabeling is only meaningfull when task monitoring is enabled (enable_monitoring). When monitoring is enabled and a task exhausts resources in a worker, mode dictates how work queue handles the exhaustion:
self | Reference to the current work queue object. |
category | A category name. If None, sets the mode by default for newly created categories. |
mode | One of category_mode_t:
|
References work_queue.WorkQueue._work_queue, and work_queue_specify_category_mode().
def work_queue.WorkQueue.specify_category_autolabel_resource | ( | self, | |
category, | |||
resource, | |||
autolabel | |||
) |
Turn on or off first-allocation labeling for a given category and resource.
This function should be use to fine-tune the defaults from specify_category_mode.
q | A work queue object. |
category | A category name. |
resource | A resource name. |
autolabel | True/False for on/off. |
References work_queue.WorkQueue._work_queue, and work_queue_enable_category_resource().
def work_queue.WorkQueue.task_state | ( | self, | |
taskid | |||
) |
Get current task state.
See work_queue_task_state_t for possible values.
References work_queue.WorkQueue._work_queue, and work_queue_task_state().
def work_queue.WorkQueue.enable_monitoring | ( | self, | |
dirname = None , |
|||
watchdog = True |
|||
) |
Enables resource monitoring of tasks in the queue, and writes a summary per task to the directory given.
Additionally, all summaries are consolidate into the file all_summaries-PID.log
Returns 1 on success, 0 on failure (i.e., monitoring was not enabled).
self | Reference to the current work queue object. |
dirname | Directory name for the monitor output. |
watchdog | If True (default), kill tasks that exhaust their declared resources. |
References work_queue.WorkQueue._work_queue, and work_queue_enable_monitoring().
def work_queue.WorkQueue.enable_monitoring_full | ( | self, | |
dirname = None , |
|||
watchdog = True |
|||
) |
As enable_monitoring, but it also generates a time series and a debug file.
WARNING: Such files may reach gigabyte sizes for long running tasks.
Returns 1 on success, 0 on failure (i.e., monitoring was not enabled).
self | Reference to the current work queue object. |
dirname | Directory name for the monitor output. |
watchdog | If True (default), kill tasks that exhaust their declared resources. |
References work_queue.WorkQueue._work_queue, and work_queue_enable_monitoring_full().
def work_queue.WorkQueue.activate_fast_abort | ( | self, | |
multiplier | |||
) |
Turn on or off fast abort functionality for a given queue for tasks in the "default" category, and for task which category does not set an explicit multiplier.
self | Reference to the current work queue object. |
multiplier | The multiplier of the average task time at which point to abort; if negative (the default) fast_abort is deactivated. |
References work_queue.WorkQueue._work_queue, and work_queue_activate_fast_abort().
def work_queue.WorkQueue.activate_fast_abort_category | ( | self, | |
name, | |||
multiplier | |||
) |
Turn on or off fast abort functionality for a given queue.
self | Reference to the current work queue object. |
name | Name of the category. |
multiplier | The multiplier of the average task time at which point to abort; if zero, deacticate for the category, negative (the default), use the one for the "default" category (see fast_abort) |
References work_queue.WorkQueue._work_queue, and work_queue_activate_fast_abort_category().
def work_queue.WorkQueue.empty | ( | self | ) |
Determine whether there are any known tasks queued, running, or waiting to be collected.
Returns 0 if there are tasks remaining in the system, 1 if the system is "empty".
self | Reference to the current work queue object. |
References work_queue.WorkQueue._work_queue, and work_queue_empty().
def work_queue.WorkQueue.hungry | ( | self | ) |
Determine whether the queue can support more tasks.
Returns the number of additional tasks it can support if "hungry" and 0 if "sated".
self | Reference to the current work queue object. |
References work_queue.WorkQueue._work_queue, and work_queue_hungry().
def work_queue.WorkQueue.specify_algorithm | ( | self, | |
algorithm | |||
) |
Set the worker selection algorithm for queue.
self | Reference to the current work queue object. |
algorithm | One of the following algorithms to use in assigning a task to a worker. See work_queue_schedule_t for possible values. |
References work_queue.WorkQueue._work_queue, and work_queue_specify_algorithm().
def work_queue.WorkQueue.specify_task_order | ( | self, | |
order | |||
) |
Set the order for dispatching submitted tasks in the queue.
self | Reference to the current work queue object. |
order | One of the following algorithms to use in dispatching submitted tasks to workers: |
References work_queue.WorkQueue._work_queue, and work_queue_specify_task_order().
def work_queue.WorkQueue.specify_name | ( | self, | |
name | |||
) |
Change the project name for the given queue.
self | Reference to the current work queue object. |
name | The new project name. |
References work_queue.WorkQueue._work_queue, and work_queue_specify_name().
def work_queue.WorkQueue.specify_master_preferred_connection | ( | self, | |
mode | |||
) |
Set the preference for using hostname over IP address to connect.
'by_ip' uses IP address (standard behavior), or 'by_hostname' to use the hostname at the master.
self | Reference to the current work queue object. |
preferred_connection | An string to indicate using 'by_ip' or a 'by_hostname'. |
References work_queue.WorkQueue._work_queue, and work_queue_master_preferred_connection().
def work_queue.WorkQueue.specify_min_taskid | ( | self, | |
minid | |||
) |
Set the minimum taskid of future submitted tasks.
Further submitted tasks are guaranteed to have a taskid larger or equal to minid. This function is useful to make taskids consistent in a workflow that consists of sequential masters. (Note: This function is rarely used). If the minimum id provided is smaller than the last taskid computed, the minimum id provided is ignored.
self | Reference to the current work queue object. |
minid | Minimum desired taskid |
References work_queue.WorkQueue._work_queue, and work_queue_specify_min_taskid().
def work_queue.WorkQueue.specify_priority | ( | self, | |
priority | |||
) |
Change the project priority for the given queue.
self | Reference to the current work queue object. |
priority | An integer that presents the priorty of this work queue master. The higher the value, the higher the priority. |
References work_queue.WorkQueue._work_queue, and work_queue_specify_priority().
def work_queue.WorkQueue.specify_num_tasks_left | ( | self, | |
ntasks | |||
) |
Specify the number of tasks not yet submitted to the queue.
It is used by work_queue_factory to determine the number of workers to launch. If not specified, it defaults to 0. work_queue_factory considers the number of tasks as: num tasks left + num tasks running + num tasks read.
q | A work queue object. |
ntasks | Number of tasks yet to be submitted. |
References work_queue.WorkQueue._work_queue, and work_queue_specify_num_tasks_left().
def work_queue.WorkQueue.specify_master_mode | ( | self, | |
mode | |||
) |
Specify the master mode for the given queue.
self | Reference to the current work queue object. |
mode | This may be one of the following values: WORK_QUEUE_MASTER_MODE_STANDALONE or WORK_QUEUE_MASTER_MODE_CATALOG. |
References work_queue.WorkQueue._work_queue, and work_queue_specify_master_mode().
def work_queue.WorkQueue.specify_catalog_server | ( | self, | |
hostname, | |||
port | |||
) |
Specify the catalog server the master should report to.
self | Reference to the current work queue object. |
hostname | The hostname of the catalog server. |
port | The port the catalog server is listening on. |
References work_queue.WorkQueue._work_queue, and work_queue_specify_catalog_server().
def work_queue.WorkQueue.specify_log | ( | self, | |
logfile | |||
) |
Specify a log file that records the cummulative stats of connected workers and submitted tasks.
self | Reference to the current work queue object. |
logfile | Filename. |
References work_queue.WorkQueue._work_queue, and work_queue_specify_log().
def work_queue.WorkQueue.specify_transactions_log | ( | self, | |
logfile | |||
) |
Specify a log file that records the states of tasks.
self | Reference to the current work queue object. |
logfile | Filename. |
References work_queue.WorkQueue._work_queue, and work_queue_specify_transactions_log().
def work_queue.WorkQueue.specify_password | ( | self, | |
password | |||
) |
Add a mandatory password that each worker must present.
self | Reference to the current work queue object. |
password | The password. |
References work_queue.WorkQueue._work_queue, and work_queue_specify_password().
def work_queue.WorkQueue.specify_password_file | ( | self, | |
file | |||
) |
Add a mandatory password file that each worker must present.
self | Reference to the current work queue object. |
file | Name of the file containing the password. |
References work_queue.WorkQueue._work_queue, and work_queue_specify_password_file().
def work_queue.WorkQueue.specify_max_resources | ( | self, | |
rmd | |||
) |
Specifies the maximum resources allowed for the default category.
self | Reference to the current work queue object. |
rm | Dictionary indicating maximum values. See for possible fields. For example: |
References work_queue.WorkQueue._work_queue, and work_queue_specify_max_resources().
def work_queue.WorkQueue.specify_category_max_resources | ( | self, | |
category, | |||
rmd | |||
) |
Specifies the maximum resources allowed for the given category.
self | Reference to the current work queue object. |
category | Name of the category. |
rm | Dictionary indicating maximum values. See for possible fields. For example: |
References work_queue.WorkQueue._work_queue, and work_queue_specify_category_max_resources().
def work_queue.WorkQueue.specify_category_first_allocation_guess | ( | self, | |
category, | |||
rmd | |||
) |
Specifies the first-allocation guess for the given category.
self | Reference to the current work queue object. |
category | Name of the category. |
rm | Dictionary indicating maximum values. See for possible fields. For example: |
References work_queue.WorkQueue._work_queue, and work_queue_specify_category_first_allocation_guess().
def work_queue.WorkQueue.initialize_categories | ( | filename, | |
rm | |||
) |
Initialize first value of categories.
self | Reference to the current work queue object. |
rm | Dictionary indicating maximum values. See for possible fields. |
filename | JSON file with resource summaries. |
References work_queue.WorkQueue._work_queue, and work_queue_initialize_categories().
def work_queue.WorkQueue.cancel_by_taskid | ( | self, | |
id | |||
) |
Cancel task identified by its taskid and remove from the given queue.
self | Reference to the current work queue object. |
id | The taskid returned from submit. |
References work_queue.WorkQueue._work_queue, and work_queue_cancel_by_taskid().
def work_queue.WorkQueue.cancel_by_tasktag | ( | self, | |
tag | |||
) |
Cancel task identified by its tag and remove from the given queue.
self | Reference to the current work queue object. |
tag | The tag assigned to task using work_queue_task_specify_tag. |
References work_queue.WorkQueue._work_queue, and work_queue_cancel_by_tasktag().
def work_queue.WorkQueue.shutdown_workers | ( | self, | |
n | |||
) |
Shutdown workers connected to queue.
Gives a best effort and then returns the number of workers given the shutdown order.
self | Reference to the current work queue object. |
n | The number to shutdown. To shut down all workers, specify "0". |
References work_queue.WorkQueue._work_queue, and work_queue_shut_down_workers().
Referenced by work_queue.WorkQueue.__init__().
def work_queue.WorkQueue.blacklist | ( | self, | |
host | |||
) |
Blacklist workers running on host.
self | Reference to the current work queue object. |
host | The hostname the host running the workers. |
References work_queue.WorkQueue._work_queue, and work_queue_blacklist_add().
def work_queue.WorkQueue.blacklist_with_timeout | ( | self, | |
host, | |||
timeout | |||
) |
Blacklist workers running on host for the duration of the given timeout.
self | Reference to the current work queue object. |
host | The hostname the host running the workers. |
timeout | How long this blacklist entry lasts (in seconds). If less than 1, blacklist indefinitely. |
References work_queue.WorkQueue._work_queue, and work_queue_blacklist_add_with_timeout().
def work_queue.WorkQueue.blacklist_clear | ( | self, | |
host = None |
|||
) |
Remove host from blacklist.
Clear all blacklist if host not provided.
self | Reference to the current work queue object. |
host | The of the hostname the host. |
References work_queue.WorkQueue._work_queue, work_queue_blacklist_clear(), and work_queue_blacklist_remove().
def work_queue.WorkQueue.specify_keepalive_interval | ( | self, | |
interval | |||
) |
Change keepalive interval for a given queue.
self | Reference to the current work queue object. |
interval | Minimum number of seconds to wait before sending new keepalive checks to workers. |
References work_queue.WorkQueue._work_queue, and work_queue_specify_keepalive_interval().
def work_queue.WorkQueue.specify_keepalive_timeout | ( | self, | |
timeout | |||
) |
Change keepalive timeout for a given queue.
self | Reference to the current work queue object. |
timeout | Minimum number of seconds to wait for a keepalive response from worker before marking it as dead. |
References work_queue.WorkQueue._work_queue, and work_queue_specify_keepalive_timeout().
def work_queue.WorkQueue.estimate_capacity | ( | self | ) |
Turn on master capacity measurements.
self | Reference to the current work queue object. |
References work_queue.WorkQueue._work_queue, and work_queue_specify_estimate_capacity_on().
def work_queue.WorkQueue.tune | ( | self, | |
name, | |||
value | |||
) |
Tune advanced parameters for work queue.
self | Reference to the current work queue object. |
name | The name fo the parameter to tune. Can be one of following:
|
value | The value to set the parameter to. |
References work_queue.WorkQueue._work_queue, and work_queue_tune().
def work_queue.WorkQueue.submit | ( | self, | |
task | |||
) |
Submit a task to the queue.
It is safe to re-submit a task returned by wait.
self | Reference to the current work queue object. |
task | A task description created from work_queue.Task. |
References work_queue.WorkQueue._task_table, work_queue.WorkQueue._work_queue, and work_queue_submit().
def work_queue.WorkQueue.wait | ( | self, | |
timeout = WORK_QUEUE_WAITFORTASK |
|||
) |
Wait for tasks to complete.
This call will block until the timeout has elapsed
self | Reference to the current work queue object. |
timeout | The number of seconds to wait for a completed task before returning. Use an integer to set the timeout or the constant WORK_QUEUE_WAITFORTASK to block until a task has completed. |
References work_queue.WorkQueue._task_table, work_queue.WorkQueue._work_queue, rmsummary.snapshots_count, and work_queue_wait().