cctools
taskvine.h File Reference
#include <sys/types.h>
#include "timestamp.h"
#include "category.h"
#include "rmsummary.h"

Go to the source code of this file.

Data Structures

struct  vine_stats
 Statistics describing a manager. More...
 

Macros

#define VINE_DEFAULT_PORT   9123
 Default taskvine port number. More...
 
#define VINE_RANDOM_PORT   0
 Indicates that any port may be chosen. More...
 
#define VINE_WAIT_FOREVER   -1
 Timeout value to wait for a task to complete before returning. More...
 

Enumerations

enum  vine_mount_flags_t {
  VINE_TRANSFER_ALWAYS = 0,
  VINE_FIXED_LOCATION = 1,
  VINE_WATCH = 2,
  VINE_FAILURE_ONLY = 4,
  VINE_SUCCESS_ONLY = 8,
  VINE_RETRACT_ON_RESET = 16,
  VINE_MOUNT_SYMLINK = 32,
  VINE_MOUNT_MKDIR = 64
}
 Select optional handling for input and output files: caching, unpacking, watching, etc. More...
 
enum  vine_cache_level_t {
  VINE_CACHE_LEVEL_TASK =0,
  VINE_CACHE_LEVEL_WORKFLOW =1,
  VINE_CACHE_LEVEL_WORKER =2,
  VINE_CACHE_LEVEL_FOREVER =3
}
 Control caching and sharing behavior of file objects. More...
 
enum  vine_file_flags_t {
  VINE_PEER_NOSHARE = 1,
  VINE_UNLINK_WHEN_DONE = 2
}
 Control sharing and garbage collection behavior of file objects. More...
 
enum  vine_schedule_t {
  VINE_SCHEDULE_UNSET = 0,
  VINE_SCHEDULE_FCFS,
  VINE_SCHEDULE_FILES,
  VINE_SCHEDULE_TIME,
  VINE_SCHEDULE_RAND,
  VINE_SCHEDULE_WORST
}
 Select overall scheduling algorithm for matching tasks to workers. More...
 
enum  vine_result_t {
  VINE_RESULT_SUCCESS = 0,
  VINE_RESULT_INPUT_MISSING = 1,
  VINE_RESULT_OUTPUT_MISSING = 2,
  VINE_RESULT_STDOUT_MISSING = 4,
  VINE_RESULT_SIGNAL = 1 << 3,
  VINE_RESULT_RESOURCE_EXHAUSTION = 2 << 3,
  VINE_RESULT_MAX_END_TIME = 3 << 3,
  VINE_RESULT_UNKNOWN = 4 << 3,
  VINE_RESULT_FORSAKEN = 5 << 3,
  VINE_RESULT_MAX_RETRIES = 6 << 3,
  VINE_RESULT_MAX_WALL_TIME = 7 << 3,
  VINE_RESULT_RMONITOR_ERROR = 8 << 3,
  VINE_RESULT_OUTPUT_TRANSFER_ERROR = 9 << 3,
  VINE_RESULT_FIXED_LOCATION_MISSING = 10 << 3,
  VINE_RESULT_CANCELLED = 11<<3,
  VINE_RESULT_LIBRARY_EXIT = 12 << 3
}
 Possible outcomes for a task, returned by vine_task_get_result. More...
 
enum  vine_category_mode_t {
  VINE_ALLOCATION_MODE_FIXED = CATEGORY_ALLOCATION_MODE_FIXED,
  VINE_ALLOCATION_MODE_MAX = CATEGORY_ALLOCATION_MODE_MAX,
  VINE_ALLOCATION_MODE_MIN_WASTE = CATEGORY_ALLOCATION_MODE_MIN_WASTE,
  VINE_ALLOCATION_MODE_MAX_THROUGHPUT = CATEGORY_ALLOCATION_MODE_MAX_THROUGHPUT
}
 Select how to allocate resources for similar tasks with vine_set_category_mode. More...
 

Functions

Functions - Tasks
struct vine_task * vine_task_create (const char *full_command)
 Create a new task object. More...
 
void vine_task_delete (struct vine_task *t)
 Delete a task. More...
 
void vine_task_set_command (struct vine_task *t, const char *cmd)
 Indicate the command to be executed. More...
 
void vine_task_needs_library (struct vine_task *t, const char *name)
 Set the library name required by this task. More...
 
void vine_task_provides_library (struct vine_task *t, const char *name)
 Set the library name provided by this task. More...
 
void vine_task_set_function_slots (struct vine_task *t, int nslots)
 Set the number of concurrent functions a library can run. More...
 
int vine_task_add_input (struct vine_task *t, struct vine_file *f, const char *remote_name, vine_mount_flags_t flags)
 Add a general file object as a input to a task. More...
 
int vine_task_add_output (struct vine_task *t, struct vine_file *f, const char *remote_name, vine_mount_flags_t flags)
 Add a general file object as a output of a task. More...
 
void vine_task_set_retries (struct vine_task *t, int64_t max_retries)
 Specify the number of times this task is retried on worker errors. More...
 
void vine_task_set_max_forsaken (struct vine_task *t, int64_t max_forsaken)
 Specify the total number of times this task can be return to the manager without being executed. More...
 
void vine_task_set_memory (struct vine_task *t, int64_t memory)
 Specify the amount of disk space required by a task. More...
 
void vine_task_set_disk (struct vine_task *t, int64_t disk)
 Specify the amount of disk space required by a task. More...
 
void vine_task_set_cores (struct vine_task *t, int cores)
 Specify the number of cores required by a task. More...
 
void vine_task_set_gpus (struct vine_task *t, int gpus)
 Specify the number of gpus required by a task. More...
 
void vine_task_set_time_end (struct vine_task *t, int64_t useconds)
 Specify the maximum end time allowed for the task (in microseconds since the Epoch). More...
 
void vine_task_set_time_start (struct vine_task *t, int64_t useconds)
 Specify the minimum start time allowed for the task (in microseconds since the Epoch). More...
 
void vine_task_set_time_max (struct vine_task *t, int64_t seconds)
 Specify the maximum time (in seconds) the task is allowed to run in a worker. More...
 
void vine_task_set_time_min (struct vine_task *t, int64_t seconds)
 Specify the minimum time (in seconds) the task is expected to run in a worker. More...
 
void vine_task_set_tag (struct vine_task *t, const char *tag)
 Attach a user defined string tag to the task. More...
 
void vine_task_set_category (struct vine_task *t, const char *category)
 Label the task with the given category. More...
 
void vine_task_add_feature (struct vine_task *t, const char *name)
 Label the task with a user-defined feature. More...
 
void vine_task_set_priority (struct vine_task *t, double priority)
 Specify the priority of this task relative to others in the manager. More...
 
void vine_task_set_env_var (struct vine_task *t, const char *name, const char *value)
 Specify an environment variable to be added to the task. More...
 
void vine_task_set_scheduler (struct vine_task *t, vine_schedule_t algorithm)
 Select the scheduling algorithm for a single task. More...
 
int vine_task_set_monitor_output (struct vine_task *t, const char *monitor_output)
 Specify a custom name for the monitoring summary. More...
 
const char * vine_task_get_command (struct vine_task *t)
 Get the command line of the task. More...
 
const char * vine_task_get_tag (struct vine_task *t)
 Get the tag associated with the task. More...
 
const char * vine_task_get_category (struct vine_task *t)
 Get the category associated with the task. More...
 
int vine_task_get_id (struct vine_task *t)
 Get the unique ID of the task. More...
 
vine_result_t vine_task_get_result (struct vine_task *t)
 Get the end result of the task. More...
 
const char * vine_result_string (vine_result_t result)
 Explain result codes from tasks. More...
 
int vine_task_get_exit_code (struct vine_task *t)
 Get the Unix exit code of the task. More...
 
const char * vine_task_get_stdout (struct vine_task *t)
 Get the standard output of the task. More...
 
const char * vine_task_get_addrport (struct vine_task *t)
 Get the address and port of the worker on which the task ran. More...
 
const char * vine_task_get_hostname (struct vine_task *t)
 Get the hostname of the worker on which the task ran. More...
 
int64_t vine_task_get_metric (struct vine_task *t, const char *name)
 Get a performance metric of a completed task. More...
 
void vine_task_set_resources (struct vine_task *t, const struct rmsummary *rm)
 Set the expected resource consumption of a task before execution. More...
 
const struct rmsummaryvine_task_get_resources (struct vine_task *t, const char *name)
 Get resource information (e.g., cores, memory, and disk) of a completed task. More...
 
int vine_task_set_snapshot_file (struct vine_task *t, struct vine_file *monitor_snapshot_file)
 When monitoring, indicates a json-encoded file that instructs the monitor to take a snapshot of the task resources. More...
 
int vine_task_add_starch_package (struct vine_task *t, struct vine_file *f)
 Add a Starch package as an execution context. More...
 
int vine_task_add_poncho_package (struct vine_task *t, struct vine_file *f)
 Add a Poncho package as an execution context. More...
 
int vine_task_add_execution_context (struct vine_task *t, struct vine_file *f)
 Adds an execution context to the task. More...
 
int vine_task_add_environment (struct vine_task *t, struct vine_file *f)
 
Functions - Files
const char * vine_file_contents (struct vine_file *f)
 Get the contents of a vine file. More...
 
size_t vine_file_size (struct vine_file *f)
 Get the length of a vine file. More...
 
struct vine_file * vine_declare_file (struct vine_manager *m, const char *source, vine_cache_level_t cache, vine_file_flags_t flags)
 Declare a file object from a local file. More...
 
struct vine_file * vine_declare_url (struct vine_manager *m, const char *url, vine_cache_level_t cache, vine_file_flags_t flags)
 Declare a file object from a remote URL. More...
 
struct vine_file * vine_declare_xrootd (struct vine_manager *m, const char *source, struct vine_file *proxy, struct vine_file *env, vine_cache_level_t cache, vine_file_flags_t flags)
 Create a file object of a remote file accessible from an xrootd server. More...
 
struct vine_file * vine_declare_chirp (struct vine_manager *m, const char *server, const char *source, struct vine_file *ticket, struct vine_file *env, vine_cache_level_t cache, vine_file_flags_t flags)
 Create a file object of a remote file accessible from a chirp server. More...
 
struct vine_file * vine_declare_temp (struct vine_manager *m)
 Create a scratch file object. More...
 
struct vine_file * vine_declare_buffer (struct vine_manager *m, const char *buffer, size_t size, vine_cache_level_t cache, vine_file_flags_t flags)
 Create a file object from a data buffer. More...
 
struct vine_file * vine_declare_mini_task (struct vine_manager *m, struct vine_task *mini_task, const char *name, vine_cache_level_t cache, vine_file_flags_t flags)
 Create a file object produced from a mini-task Attaches a task definition to produce an input file by running a Unix command. More...
 
struct vine_file * vine_declare_untar (struct vine_manager *m, struct vine_file *f, vine_cache_level_t cache, vine_file_flags_t flags)
 Create a file object by unpacking a tar archive. More...
 
struct vine_file * vine_declare_poncho (struct vine_manager *m, struct vine_file *f, vine_cache_level_t cache, vine_file_flags_t flags)
 Create a file object by unpacking a poncho package. More...
 
struct vine_file * vine_declare_starch (struct vine_manager *m, struct vine_file *f, vine_cache_level_t cache, vine_file_flags_t flags)
 Create a file object by unpacking a starch package. More...
 
const char * vine_fetch_file (struct vine_manager *m, struct vine_file *f)
 Fetch the contents of a file. More...
 
void vine_undeclare_file (struct vine_manager *m, struct vine_file *f)
 Un-declare a file that was created by vine_declare_file or similar functions. More...
 
Functions - Managers
struct vine_manager * vine_create (int port)
 Create a new manager. More...
 
struct vine_manager * vine_ssl_create (int port, const char *key, const char *cert)
 Create a new manager using SSL. More...
 
void vine_delete (struct vine_manager *m)
 Delete a manager. More...
 
int vine_submit (struct vine_manager *m, struct vine_task *t)
 Submit a task to a manager. More...
 
void vine_manager_install_library (struct vine_manager *m, struct vine_task *t, const char *name)
 Indicate the library to be installed on all workers connected to the manager. More...
 
void vine_manager_remove_library (struct vine_manager *m, const char *name)
 Indicate the library to be removed from all connected workers. More...
 
struct vine_task * vine_wait (struct vine_manager *m, int timeout)
 Wait for a task to complete. More...
 
struct vine_task * vine_wait_for_tag (struct vine_manager *m, const char *tag, int timeout)
 Wait for a task with a given task to complete. More...
 
struct vine_task * vine_wait_for_task_id (struct vine_manager *m, int task_id, int timeout)
 Wait for a task with a given task_id to complete. More...
 
int vine_hungry (struct vine_manager *m)
 Determine whether the manager is 'hungry' for more tasks. More...
 
int vine_empty (struct vine_manager *m)
 Determine whether the manager is empty. More...
 
int vine_port (struct vine_manager *m)
 Get the listening port of the manager. More...
 
void vine_set_name (struct vine_manager *m, const char *name)
 Change the project name for a given manager. More...
 
const char * vine_get_name (struct vine_manager *m)
 Get the project name of the manager. More...
 
int vine_enable_monitoring (struct vine_manager *m, int watchdog, int time_series)
 Enables resource monitoring for tasks. More...
 
int vine_enable_peer_transfers (struct vine_manager *m)
 Enable taskvine peer transfers to be scheduled by the manager. More...
 
int vine_disable_peer_transfers (struct vine_manager *m)
 Disable taskvine peer transfers to be scheduled by the manager. More...
 
int vine_set_task_id_min (struct vine_manager *m, int minid)
 Set the minimum task_id of future submitted tasks. More...
 
void vine_block_host (struct vine_manager *m, const char *hostname)
 Block workers in hostname from working for manager q. More...
 
void vine_block_host_with_timeout (struct vine_manager *m, const char *hostname, time_t seconds)
 Block workers in hostname from a manager, but remove block after timeout seconds. More...
 
void vine_unblock_host (struct vine_manager *m, const char *hostname)
 Unblock host from a manager. More...
 
void vine_unblock_all (struct vine_manager *m)
 Unblock all host. More...
 
void vine_get_stats (struct vine_manager *m, struct vine_stats *s)
 Get manager statistics (only from manager) More...
 
void vine_get_stats_category (struct vine_manager *m, const char *c, struct vine_stats *s)
 Get the task statistics for the given category. More...
 
char * vine_get_status (struct vine_manager *m, const char *request)
 Get manager information as json. More...
 
struct rmsummary ** vine_summarize_workers (struct vine_manager *m)
 Summary data for all workers in buffer. More...
 
void vine_set_bandwidth_limit (struct vine_manager *m, const char *bandwidth)
 Limit the manager bandwidth when transferring files to and from workers. More...
 
double vine_get_effective_bandwidth (struct vine_manager *m)
 Get current manager bandwidth. More...
 
int vine_enable_disconnect_slow_workers (struct vine_manager *m, double multiplier)
 Enable disconnect slow workers functionality for a given manager for tasks without an explicit category. More...
 
int vine_enable_disconnect_slow_workers_category (struct vine_manager *m, const char *category, double multiplier)
 Enable disconnect slow workers functionality for a given category. More...
 
int vine_set_draining_by_hostname (struct vine_manager *m, const char *hostname, int drain_flag)
 Set the draining mode per worker hostname. More...
 
int vine_set_category_mode (struct vine_manager *m, const char *category, vine_category_mode_t mode)
 Turn on or off first-allocation labeling for a given category. More...
 
int vine_enable_category_resource (struct vine_manager *m, const char *category, const char *resource, int autolabel)
 Turn on or off first-allocation labeling for a given category and resource. More...
 
void vine_set_scheduler (struct vine_manager *m, vine_schedule_t algorithm)
 Change the worker selection algorithm. More...
 
void vine_set_priority (struct vine_manager *m, int priority)
 Change the priority for a given manager. More...
 
void vine_set_tasks_left_count (struct vine_manager *m, int ntasks)
 Specify the number of tasks not yet submitted to the manager. More...
 
void vine_set_catalog_servers (struct vine_manager *m, const char *hosts)
 Specify the catalog server(s) the manager should report to. More...
 
void vine_set_property (struct vine_manager *m, const char *name, const char *value)
 Add a global property to the manager which will be included in periodic reports to the catalog server and other telemetry destinations. More...
 
int vine_cancel_by_task_id (struct vine_manager *m, int id)
 Cancel a submitted task using its task id. More...
 
int vine_cancel_by_task_tag (struct vine_manager *m, const char *tag)
 Cancel a submitted task using its tag and remove it from manager. More...
 
int vine_cancel_all (struct vine_manager *m)
 Cancel all submitted tasks and remove them from the manager. More...
 
int vine_enable_debug_log (const char *logfile)
 Turn on the debugging log output and send to the named file. More...
 
int vine_enable_perf_log (struct vine_manager *m, const char *logfile)
 Add a performance log file that records cummulative statistics of the connected workers and submitted tasks. More...
 
int vine_enable_transactions_log (struct vine_manager *m, const char *logfile)
 Add a log file that records the states of the connected workers and tasks. More...
 
int vine_enable_taskgraph_log (struct vine_manager *m, const char *logfile)
 Add an output log that produces the taskgraph in Grapvhiz Dot format. More...
 
int vine_workers_shutdown (struct vine_manager *m, int n)
 Shut down workers connected to the manager. More...
 
void vine_set_password (struct vine_manager *m, const char *password)
 Add a mandatory password that each worker must present. More...
 
int vine_set_password_file (struct vine_manager *m, const char *file)
 Add a mandatory password file that each worker must present. More...
 
void vine_set_keepalive_interval (struct vine_manager *m, int interval)
 Change the keepalive interval for a given manager. More...
 
void vine_set_keepalive_timeout (struct vine_manager *m, int timeout)
 Change the keepalive timeout for identifying dead workers for a given manager. More...
 
void vine_set_manager_preferred_connection (struct vine_manager *m, const char *preferred_connection)
 Set the preference for using hostname over IP address to connect. More...
 
int vine_tune (struct vine_manager *m, const char *name, double value)
 Tune advanced parameters for manager. More...
 
void vine_set_resources_max (struct vine_manager *m, const struct rmsummary *rm)
 Sets the maximum resources a task without an explicit category ("default" category). More...
 
void vine_set_resources_min (struct vine_manager *m, const struct rmsummary *rm)
 Sets the minimum resources a task without an explicit category ("default" category). More...
 
void vine_set_category_resources_max (struct vine_manager *m, const char *category, const struct rmsummary *rm)
 Sets the maximum resources a task in the category may use. More...
 
void vine_set_category_resources_min (struct vine_manager *m, const char *category, const struct rmsummary *rm)
 Sets the minimum resources a task in the category may use. More...
 
void vine_set_category_first_allocation_guess (struct vine_manager *m, const char *category, const struct rmsummary *rm)
 Set the initial guess for resource autolabeling for the given category. More...
 
void vine_initialize_categories (struct vine_manager *m, struct rmsummary *max, const char *summaries_file)
 Initialize first value of categories. More...
 
void vine_set_runtime_info_path (const char *path)
 Sets the path where runtime info directories (logs and staging) are created. More...
 
void vine_log_debug_app (struct vine_manager *q, const char *entry)
 Adds a custom APPLICATION entry to the debug log. More...
 
void vine_log_txn_app (struct vine_manager *q, const char *entry)
 Adds a custom APPLICATION entry to the transactions log. More...
 

Detailed Description

The public API for the taskvine distributed application framework. A taskvine application consists of a manager process and a larger number of worker processes, typically running in a high performance computing cluster, or a cloud facility. Both the manager and worker processes run with ordinary user privileges and require no special capabilities.

From the application perspective, the programmer creates a manager with vine_create, defines a number of tasks with vine_task_create, submits the tasks to the manager with vine_submit, and then monitors completion with vine_wait. Tasks are further described by attaching data objects via vine_task_add_input, vine_task_add_output and related functions.

The taskvine framework provides a large number of fault tolerance, resource management, and performance monitoring features that enable the construction of applications that run reliably on tens of thousands of nodes in the presence of failures and other expected events.

Macro Definition Documentation

◆ VINE_DEFAULT_PORT

#define VINE_DEFAULT_PORT   9123

Default taskvine port number.

◆ VINE_RANDOM_PORT

#define VINE_RANDOM_PORT   0

Indicates that any port may be chosen.

◆ VINE_WAIT_FOREVER

#define VINE_WAIT_FOREVER   -1

Timeout value to wait for a task to complete before returning.

Enumeration Type Documentation

◆ vine_mount_flags_t

Select optional handling for input and output files: caching, unpacking, watching, etc.

Enumerator
VINE_TRANSFER_ALWAYS 

Always transfer this file when needed.

VINE_FIXED_LOCATION 

Never transfer input files with this flag to a worker for execution.

Task won't be dispatched to a worker unless file is already cached there.

VINE_WATCH 

Watch the output file and send back changes as the task runs.

VINE_FAILURE_ONLY 

Only return this output file if the task failed.

(Useful for returning large log files.)

VINE_SUCCESS_ONLY 

Only return this output file if the task succeeded.

VINE_RETRACT_ON_RESET 

Remove this file from the mount lists if the task is reset.

(TaskVine internal use only.)

VINE_MOUNT_SYMLINK 

Permit this directory to be mounted via symlink instead of hardlink.

VINE_MOUNT_MKDIR 

Create this empty output directory in the task sandbox prior to execution.

◆ vine_cache_level_t

Control caching and sharing behavior of file objects.

Enumerator
VINE_CACHE_LEVEL_TASK 

Do not cache file at worker.

(default)

VINE_CACHE_LEVEL_WORKFLOW 

File remains in cache of worker until workflow ends.

VINE_CACHE_LEVEL_WORKER 

File remains in cache of worker until worker terminates.

VINE_CACHE_LEVEL_FOREVER 

File remains at execution site when worker terminates.

(use with caution)

◆ vine_file_flags_t

Control sharing and garbage collection behavior of file objects.

Enumerator
VINE_PEER_NOSHARE 

Schedule this file to be shared between peers where available.

See vine_enable_peer_transfers

VINE_UNLINK_WHEN_DONE 

Whether to delete the file when its reference count is 0.

(Warning: Only use on files produced by the application, and never on irreplaceable input files.)

◆ vine_schedule_t

Select overall scheduling algorithm for matching tasks to workers.

Enumerator
VINE_SCHEDULE_UNSET 

Internal use only.

VINE_SCHEDULE_FCFS 

Select worker on a first-come-first-serve basis.

VINE_SCHEDULE_FILES 

Select worker that has the most data required by the task.

(default)

VINE_SCHEDULE_TIME 

Select worker that has the fastest execution time on previous tasks.

VINE_SCHEDULE_RAND 

Select a random worker.

VINE_SCHEDULE_WORST 

Select the worst fit worker (the worker with more unused resources).

◆ vine_result_t

Possible outcomes for a task, returned by vine_task_get_result.

These results can be converted to a string with vine_result_string.

Enumerator
VINE_RESULT_SUCCESS 

The task ran successfully, and its Unix exit code is given by vine_task_get_exit_code.

VINE_RESULT_INPUT_MISSING 

The task cannot be run due to a missing input file.

VINE_RESULT_OUTPUT_MISSING 

The task ran but failed to generate a specified output file.

VINE_RESULT_STDOUT_MISSING 

The task ran but its stdout has been truncated.

VINE_RESULT_SIGNAL 

The task was terminated with a signal.

VINE_RESULT_RESOURCE_EXHAUSTION 

The task used more resources than requested.

VINE_RESULT_MAX_END_TIME 

The task ran after the specified (absolute since epoch) end time.

VINE_RESULT_UNKNOWN 

The result could not be classified.

VINE_RESULT_FORSAKEN 

The task failed, but it was not a task error.

VINE_RESULT_MAX_RETRIES 

Currently unused.

VINE_RESULT_MAX_WALL_TIME 

The task ran for more than the specified time (relative since running in a worker).

VINE_RESULT_RMONITOR_ERROR 

The task failed because the monitor did not produce a summary report.

VINE_RESULT_OUTPUT_TRANSFER_ERROR 

The task failed because an output could be transfered to the manager (not enough disk space, incorrect write permissions.

VINE_RESULT_FIXED_LOCATION_MISSING 

The task failed because no worker could satisfy the fixed location input file requirements.

VINE_RESULT_CANCELLED 

The task was cancelled by the caller.

VINE_RESULT_LIBRARY_EXIT 

Task is a library that has terminated.

◆ vine_category_mode_t

Select how to allocate resources for similar tasks with vine_set_category_mode.

Enumerator
VINE_ALLOCATION_MODE_FIXED 

When monitoring is disabled, all tasks run as VINE_ALLOCATION_MODE_FIXED.

If monitoring is enabled and resource exhaustion occurs for specified resources values, then the task permanently fails.

VINE_ALLOCATION_MODE_MAX 

When monitoring is enabled, tasks are tried with maximum specified values of cores, memory, disk or gpus until enough statistics are collected.

Then, further tasks are first tried using the maximum values observed, and in case of resource exhaustion, they are retried using the maximum specified values. The task permanently fails when there is an exhaustion using the maximum values. If no maximum values are specified, the task will wait until a larger worker connects.

VINE_ALLOCATION_MODE_MIN_WASTE 

As above, but tasks are first tried with an automatically computed allocation to minimize resource waste.

VINE_ALLOCATION_MODE_MAX_THROUGHPUT 

As above, but maximizing throughput.

Function Documentation

◆ vine_task_create()

struct vine_task* vine_task_create ( const char *  full_command)

Create a new task object.

Once created and elaborated with functions such as vine_task_add_input and vine_task_add_output, the task should be passed to vine_submit.

Parameters
full_commandThe shell command line or coprocess functions to be executed by the task. If null, the command will be given later by vine_task_set_command
Returns
A new task object, or null if it could not be created.

◆ vine_task_delete()

void vine_task_delete ( struct vine_task *  t)

Delete a task.

This may be called on tasks after they are returned from vine_wait.

Parameters
tThe task to delete.

◆ vine_task_set_command()

void vine_task_set_command ( struct vine_task *  t,
const char *  cmd 
)

Indicate the command to be executed.

Parameters
tA task object.
cmdThe command to be executed. This string will be duplicated by this call, so the argument may be freed or re-used afterward.

◆ vine_task_needs_library()

void vine_task_needs_library ( struct vine_task *  t,
const char *  name 
)

Set the library name required by this task.

Parameters
tA task object.
nameThe name of the library coprocess name that will be used by this task.

◆ vine_task_provides_library()

void vine_task_provides_library ( struct vine_task *  t,
const char *  name 
)

Set the library name provided by this task.

Parameters
tA task object.
nameThe name of the library coprocess that this task implements.

◆ vine_task_set_function_slots()

void vine_task_set_function_slots ( struct vine_task *  t,
int  nslots 
)

Set the number of concurrent functions a library can run.

Parameters
tA task object.
nslotsThe maximum number of concurrent functions this library can run.

◆ vine_task_add_input()

int vine_task_add_input ( struct vine_task *  t,
struct vine_file *  f,
const char *  remote_name,
vine_mount_flags_t  flags 
)

Add a general file object as a input to a task.

Parameters
tA task object.
fA file object, created by vine_declare_file, vine_declare_url, vine_declare_buffer, vine_declare_mini_task.
remote_nameThe name of the file as it should appear in the task's sandbox.
flagsMay be zero or more vine_mount_flags_t or'd together. See vine_task_add_input.
Returns
True on success, false on failure.

◆ vine_task_add_output()

int vine_task_add_output ( struct vine_task *  t,
struct vine_file *  f,
const char *  remote_name,
vine_mount_flags_t  flags 
)

Add a general file object as a output of a task.

Parameters
tA task object.
fA file object, created by vine_declare_file or vine_declare_buffer.
remote_nameThe name of the file as it will appear in the task's sandbox.
flagsMay be zero or more vine_mount_flags_t or'd together. See vine_task_add_input.
Returns
True on success, false on failure.

◆ vine_task_set_retries()

void vine_task_set_retries ( struct vine_task *  t,
int64_t  max_retries 
)

Specify the number of times this task is retried on worker errors.

If less than one, the task is retried indefinitely (this the default). A task that did not succeed after the given number of retries is returned with the result of its last attempt.

Parameters
tA task object.
max_retriesThe number of retries.

◆ vine_task_set_max_forsaken()

void vine_task_set_max_forsaken ( struct vine_task *  t,
int64_t  max_forsaken 
)

Specify the total number of times this task can be return to the manager without being executed.

If less than zero, the task is tried indefinitely (this the default). A task that did not succeed after the given number is returned with the result VINE_RESULT_FORSAKEN.

Parameters
tA task object.
max_retriesThe number of retries.

◆ vine_task_set_memory()

void vine_task_set_memory ( struct vine_task *  t,
int64_t  memory 
)

Specify the amount of disk space required by a task.

Parameters
tA task object.
memoryThe amount of disk space required by the task, in megabytes.

◆ vine_task_set_disk()

void vine_task_set_disk ( struct vine_task *  t,
int64_t  disk 
)

Specify the amount of disk space required by a task.

Parameters
tA task object.
diskThe amount of disk space required by the task, in megabytes.

◆ vine_task_set_cores()

void vine_task_set_cores ( struct vine_task *  t,
int  cores 
)

Specify the number of cores required by a task.

Parameters
tA task object.
coresThe number of cores required by the task.

◆ vine_task_set_gpus()

void vine_task_set_gpus ( struct vine_task *  t,
int  gpus 
)

Specify the number of gpus required by a task.

Parameters
tA task object.
gpusThe number of gpus required by the task.

◆ vine_task_set_time_end()

void vine_task_set_time_end ( struct vine_task *  t,
int64_t  useconds 
)

Specify the maximum end time allowed for the task (in microseconds since the Epoch).

If less than 1, then no end time is specified (this is the default). This is useful, for example, when the task uses certificates that expire.

Parameters
tA task object.
usecondsNumber of useconds since the Epoch.

◆ vine_task_set_time_start()

void vine_task_set_time_start ( struct vine_task *  t,
int64_t  useconds 
)

Specify the minimum start time allowed for the task (in microseconds since the Epoch).

The task will only be submitted to workers after the specified time. If less than 1, then no minimum start time is specified (this is the default).

Parameters
tA task object.
usecondsNumber of useconds since the Epoch.

◆ vine_task_set_time_max()

void vine_task_set_time_max ( struct vine_task *  t,
int64_t  seconds 
)

Specify the maximum time (in seconds) the task is allowed to run in a worker.

This time is accounted since the the moment the task starts to run in a worker. If less than 1, then no maximum time is specified (this is the default).

Parameters
tA task object.
secondsMaximum number of seconds the task may run in a worker.

◆ vine_task_set_time_min()

void vine_task_set_time_min ( struct vine_task *  t,
int64_t  seconds 
)

Specify the minimum time (in seconds) the task is expected to run in a worker.

This time is accounted since the moment the task starts to run in a worker. If less than 1, then no minimum time is specified (this is the default).

Parameters
tA task object.
secondsMinimum number of seconds the task may run in a worker.

◆ vine_task_set_tag()

void vine_task_set_tag ( struct vine_task *  t,
const char *  tag 
)

Attach a user defined string tag to the task.

This field is not interpreted by the manager, but is provided for the user's convenience in identifying tasks when they complete.

Parameters
tA task object.
tagThe tag to attach to task t.

◆ vine_task_set_category()

void vine_task_set_category ( struct vine_task *  t,
const char *  category 
)

Label the task with the given category.

It is expected that tasks with the same category have similar resources requirements (e.g. to disconnect slow workers).

Parameters
tA task object.
categoryThe name of the category to use.

◆ vine_task_add_feature()

void vine_task_add_feature ( struct vine_task *  t,
const char *  name 
)

Label the task with a user-defined feature.

The task will only run on a worker that provides (–feature option) such feature.

Parameters
tA task object.
nameThe name of the feature.

◆ vine_task_set_priority()

void vine_task_set_priority ( struct vine_task *  t,
double  priority 
)

Specify the priority of this task relative to others in the manager.

Tasks with a higher priority value run first. If no priority is given, a task is placed at the end of the ready list, regardless of the priority.

Parameters
tA task object.
priorityThe priority of the task.

◆ vine_task_set_env_var()

void vine_task_set_env_var ( struct vine_task *  t,
const char *  name,
const char *  value 
)

Specify an environment variable to be added to the task.

Parameters
tA task object
nameName of the variable.
valueValue of the variable.

◆ vine_task_set_scheduler()

void vine_task_set_scheduler ( struct vine_task *  t,
vine_schedule_t  algorithm 
)

Select the scheduling algorithm for a single task.

To change the scheduling algorithm for all tasks, use vine_set_scheduler instead.

Parameters
tA task object.
algorithmThe algorithm to use in assigning this task to a worker. For possible values, see vine_schedule_t.

◆ vine_task_set_monitor_output()

int vine_task_set_monitor_output ( struct vine_task *  t,
const char *  monitor_output 
)

Specify a custom name for the monitoring summary.

If vine_enable_monitoring is also enabled, the summary is also written to that directory.

Parameters
tA task object.
monitor_outputResource summary file.
Returns
True on success, false on failure.

◆ vine_task_get_command()

const char* vine_task_get_command ( struct vine_task *  t)

Get the command line of the task.

Parameters
tA task object.
Returns
The command line set by vine_task_create.

◆ vine_task_get_tag()

const char* vine_task_get_tag ( struct vine_task *  t)

Get the tag associated with the task.

Parameters
tA task object.
Returns
The tag string set by vine_task_set_tag.

◆ vine_task_get_category()

const char* vine_task_get_category ( struct vine_task *  t)

Get the category associated with the task.

Parameters
tA task object.
Returns
The category string set by vine_task_set_category.

◆ vine_task_get_id()

int vine_task_get_id ( struct vine_task *  t)

Get the unique ID of the task.

Parameters
tA task object.
Returns
The integer task ID assigned at creation time.

◆ vine_task_get_result()

vine_result_t vine_task_get_result ( struct vine_task *  t)

Get the end result of the task.

If the result is VINE_RESULT_SUCCESS, then the task ran to completion and the exit code of the process can be obtained from vine_task_get_exit_code. For any other result, the task could not be run to completion. Use vine_result_string to convert the result code into a readable string.

Parameters
tA task object.
Returns
The result of the task as a vine_result_t.

◆ vine_result_string()

const char* vine_result_string ( vine_result_t  result)

Explain result codes from tasks.

Parameters
resultResult from a task returned by vine_wait.
Returns
String representation of task result code.

◆ vine_task_get_exit_code()

int vine_task_get_exit_code ( struct vine_task *  t)

Get the Unix exit code of the task.

Parameters
tA task object.
Returns
If the task ran to completion and the result is VINE_RESULT_SUCCESS, then this function returns the Unix exit code of the process, which by custom is zero to indicate success, and non-zero to indicate failure.

◆ vine_task_get_stdout()

const char* vine_task_get_stdout ( struct vine_task *  t)

Get the standard output of the task.

Parameters
tA task object.
Returns
A null-terminated string containing the standard output of the task. If the task did not run to completion, then this function returns null.

◆ vine_task_get_addrport()

const char* vine_task_get_addrport ( struct vine_task *  t)

Get the address and port of the worker on which the task ran.

Parameters
tA task object.
Returns
A null-terminated string containing the address and port of the relevant worker. If the task did not run on a worker, then this function returns null.

◆ vine_task_get_hostname()

const char* vine_task_get_hostname ( struct vine_task *  t)

Get the hostname of the worker on which the task ran.

Parameters
tA task object.
Returns
A null-terminated string containing the hostname of the relevant worker. If the task did not run on a worker, then this function returns null.

◆ vine_task_get_metric()

int64_t vine_task_get_metric ( struct vine_task *  t,
const char *  name 
)

Get a performance metric of a completed task.

Parameters
tA task object.
nameThe name of an integer performance metric:
  • "time_when_submitted"
  • "time_when_done"
  • "time_when_commit_start"
  • "time_when_commit_end"
  • "time_when_retrieval"
  • "time_workers_execute_last"
  • "time_workers_execute_all"
  • "time_workers_execute_exhaustion"
  • "time_workers_execute_failure"
  • "bytes_received"
  • "bytes_sent"
  • "bytes_transferred"
Returns
The metric value, or zero if an invalid name is given.

◆ vine_task_set_resources()

void vine_task_set_resources ( struct vine_task *  t,
const struct rmsummary rm 
)

Set the expected resource consumption of a task before execution.

Parameters
tA task object.
rmA resource summary object.

◆ vine_task_get_resources()

const struct rmsummary* vine_task_get_resources ( struct vine_task *  t,
const char *  name 
)

Get resource information (e.g., cores, memory, and disk) of a completed task.

Parameters
tA task object.
nameOne of: "allocated", "requested", or "measured". For measured resources see vine_enable_monitoring.
Returns
The metric value, or zero if an invalid name is given.

◆ vine_task_set_snapshot_file()

int vine_task_set_snapshot_file ( struct vine_task *  t,
struct vine_file *  monitor_snapshot_file 
)

When monitoring, indicates a json-encoded file that instructs the monitor to take a snapshot of the task resources.

Snapshots appear in the JSON summary file of the task, under the key "snapshots". Snapshots are taken on events on files described in the monitor_snapshot_file. The monitor_snapshot_file is a json encoded file with the following format:

{
    "FILENAME": {
        "from-start":boolean,
        "from-start-if-truncated":boolean,
        "delete-if-found":boolean,
        "events": [
            {
                "label":"EVENT_NAME",
                "on-create":boolean,
                "on-truncate":boolean,
                "pattern":"REGEXP",
                "count":integer
            },
            {
                "label":"EVENT_NAME",
                ...
            }
        ]
    },
    "FILENAME": {
        ...
}

All fields but label are optional.

        from-start:boolean         If FILENAME exits when task starts running, process from line 1. Default: false, as the task may be appending to an already existing file.
        from-start-if-truncated    If FILENAME is truncated, process from line 1. Default: true, to account for log rotations.
        delete-if-found            Delete FILENAME when found. Default: false

        events:
        label        Name that identifies the snapshot. Only alphanumeric, -,
                     and _ characters are allowed.
        on-create    Take a snapshot every time the file is created. Default: false
        on-truncate  Take a snapshot when the file is truncated.    Default: false
        pattern      Take a snapshot when a line matches the regexp pattern.    Default: none
        count        Maximum number of snapshots for this label. Default: -1 (no limit)

For more information, consult the manual of the resource_monitor.

Parameters
tA vine_task object.
monitor_snapshot_fileA filename.

◆ vine_task_add_starch_package()

int vine_task_add_starch_package ( struct vine_task *  t,
struct vine_file *  f 
)

Add a Starch package as an execution context.

The file given must refer to a (unpacked) package containing libraries captured by the starch command. The task will execute using this package as its environment.

Parameters
tA task object.
fA file containing an unpacked Starch package.

◆ vine_task_add_poncho_package()

int vine_task_add_poncho_package ( struct vine_task *  t,
struct vine_file *  f 
)

Add a Poncho package as an execution context.

The file given must refer to a (unpacked) PONCHO package, containing a set of Python modules needed by the task. The task will execute using this package as its Python environment.

Parameters
tA task object.
fA file containing an unpacked Poncho package.

◆ vine_task_add_execution_context()

int vine_task_add_execution_context ( struct vine_task *  t,
struct vine_file *  f 
)

Adds an execution context to the task.

The context file given must expand to a directory containing (at a minimum) a file named bin/run_in_env that will perform any desired setup (e.g. setting PATH, LD_LIBRARY_PATH, PYTHONPATH), execute the given command, and then perform any desired cleanup. The context directory may also include any support files or libraries needed by the task. If specified multiple times, execution contexts are nested in the order given (i.e. first added is the first applied).

See also
vine_task_add_starch_package
vine_task_add_poncho_package
Parameters
tA task object.
fThe execution context file.

◆ vine_file_contents()

const char* vine_file_contents ( struct vine_file *  f)

Get the contents of a vine file.

Typically used to examine an output buffer returned from a file. Note that the vfile contents may not be available unless vine_fetch_file has previously been called on this object.

Parameters
mA manager object
fA file object created by vine_declare_buffer.
Returns
A constant pointer to the buffer contents, or null if not available.

◆ vine_file_size()

size_t vine_file_size ( struct vine_file *  f)

Get the length of a vine file.

Parameters
fA file object.
Returns
The length of the file, or zero if unknown.

◆ vine_declare_file()

struct vine_file* vine_declare_file ( struct vine_manager *  m,
const char *  source,
vine_cache_level_t  cache,
vine_file_flags_t  flags 
)

Declare a file object from a local file.

Parameters
mA manager object
sourceThe path of the file on the local filesystem
cacheMethod for caching file at the workers: never, the default (VINE_CACHE_LEVEL_TASK), to cache only for the current manager (VINE_CACHE_LEVEL_WORKFLOW), to cache for the lifetime of the worker (VINE_CACHE_LEVEL_WORKER), or to cache at execution site even when worker terminates (VINE_CACHE_LEVEL_FOREVER).
flagsFlags that can be or'ed (|) to indicate whether a file should not be transferred among workers (VINE_PEER_NOSHARE) when peer transfers are enabled (vine_enable_peer_transfers), or whether a file should be delete at the manager's site after it is not needed by the workflow (vine_undeclare_file).
Returns
A file object to use in vine_task_add_input, and vine_task_add_output

◆ vine_declare_url()

struct vine_file* vine_declare_url ( struct vine_manager *  m,
const char *  url,
vine_cache_level_t  cache,
vine_file_flags_t  flags 
)

Declare a file object from a remote URL.

Parameters
mA manager object
urlThe URL address of the object in text form.
cacheMethod for caching file at the workers: never, the default (VINE_CACHE_LEVEL_TASK), to cache only for the current manager (VINE_CACHE_LEVEL_WORKFLOW), to cache for the lifetime of the worker (VINE_CACHE_LEVEL_WORKER), or to cache at execution site even when worker terminates (VINE_CACHE_LEVEL_FOREVER).
flagsFlags that can be or'ed (|) to indicate whether a file should not be transferred among workers (VINE_PEER_NOSHARE) when peer transfers are enabled (vine_enable_peer_transfers), or whether a file should be delete at the manager's site after it is not needed by the workflow (vine_undeclare_file).
Returns
A file object to use in vine_task_add_input

◆ vine_declare_xrootd()

struct vine_file* vine_declare_xrootd ( struct vine_manager *  m,
const char *  source,
struct vine_file *  proxy,
struct vine_file *  env,
vine_cache_level_t  cache,
vine_file_flags_t  flags 
)

Create a file object of a remote file accessible from an xrootd server.

Parameters
mA manager object
sourceThe URL address of the root file in text form as: "root://XROOTSERVER[:port]//path/to/file"
proxyA proxy file object (e.g. from vine_declare_file) of a X509 proxy to use. If NULL, the environment variable X509_USER_PROXY and the file "$TMPDIR/$UID" are considered in that order. If no proxy is present, the transfer is tried without authentication.
envIf not NULL, an environment file (e.g poncho or starch, see vine_task_add_environment) that contains the xrootd executables. Otherwise assume xrootd is available at the worker.
cacheMethod for caching file at the workers: never, the default (VINE_CACHE_LEVEL_TASK), to cache only for the current manager (VINE_CACHE_LEVEL_WORKFLOW), to cache for the lifetime of the worker (VINE_CACHE_LEVEL_WORKER), or to cache at execution site even when worker terminates (VINE_CACHE_LEVEL_FOREVER).
flagsFlags that can be or'ed (|) to indicate whether a file should not be transferred among workers (VINE_PEER_NOSHARE) when peer transfers are enabled (vine_enable_peer_transfers), or whether a file should be delete at the manager's site after it is not needed by the workflow (vine_undeclare_file).
Returns
A file object to use in vine_task_add_input

◆ vine_declare_chirp()

struct vine_file* vine_declare_chirp ( struct vine_manager *  m,
const char *  server,
const char *  source,
struct vine_file *  ticket,
struct vine_file *  env,
vine_cache_level_t  cache,
vine_file_flags_t  flags 
)

Create a file object of a remote file accessible from a chirp server.

Parameters
mA manager object
serverThe chirp server address of the form "hostname[:port"]"
sourceThe name of the file in the server
ticketIf not NULL, a file object that provides a chirp an authentication ticket
envIf not NULL, an environment file (e.g poncho or starch, see vine_task_add_environment) that contains the chirp executables. Otherwise assume chirp is available at the worker.
cacheMethod for caching file at the workers: never, the default (VINE_CACHE_LEVEL_TASK), to cache only for the current manager (VINE_CACHE_LEVEL_WORKFLOW), to cache for the lifetime of the worker (VINE_CACHE_LEVEL_WORKER), or to cache at execution site even when worker terminates (VINE_CACHE_LEVEL_FOREVER).
flagsFlags that can be or'ed (|) to indicate whether a file should not be transferred among workers (VINE_PEER_NOSHARE) when peer transfers are enabled (vine_enable_peer_transfers), or whether a file should be delete at the manager's site after it is not needed by the workflow (vine_undeclare_file).
Returns
A file object to use in vine_task_add_input

◆ vine_declare_temp()

struct vine_file* vine_declare_temp ( struct vine_manager *  m)

Create a scratch file object.

A scratch file has no initial content, but is created as the output of a task, and may be consumed by other tasks.

Parameters
mA manager object
Returns
A file object to use in vine_task_add_input, vine_task_add_output

◆ vine_declare_buffer()

struct vine_file* vine_declare_buffer ( struct vine_manager *  m,
const char *  buffer,
size_t  size,
vine_cache_level_t  cache,
vine_file_flags_t  flags 
)

Create a file object from a data buffer.

Parameters
mA manager object
bufferThe contents of the buffer.
sizeThe length of the buffer, in bytes.
cacheMethod for caching file at the workers: never, the default (VINE_CACHE_LEVEL_TASK), to cache only for the current manager (VINE_CACHE_LEVEL_WORKFLOW), to cache for the lifetime of the worker (VINE_CACHE_LEVEL_WORKER), or to cache at execution site even when worker terminates (VINE_CACHE_LEVEL_FOREVER).
flagsFlags that can be or'ed (|) to indicate whether a file should not be transferred among workers (VINE_PEER_NOSHARE) when peer transfers are enabled (vine_enable_peer_transfers), or whether a file should be delete at the manager's site after it is not needed by the workflow (vine_undeclare_file).
Returns
A file object to use in vine_task_add_input, and vine_task_add_output

◆ vine_declare_mini_task()

struct vine_file* vine_declare_mini_task ( struct vine_manager *  m,
struct vine_task *  mini_task,
const char *  name,
vine_cache_level_t  cache,
vine_file_flags_t  flags 
)

Create a file object produced from a mini-task Attaches a task definition to produce an input file by running a Unix command.

This mini-task will be run on demand in order to produce the desired input file. This is useful if an input requires some prior step such as transferring, renaming, or unpacking to be useful. A mini-task should be a short-running activity with minimal resource consumption.

Parameters
mA manager object
mini_taskThe task which produces the file
nameThe name of the file in the task's sandbox to extract.
cacheMethod for caching file at the workers: never, the default (VINE_CACHE_LEVEL_TASK), to cache only for the current manager (VINE_CACHE_LEVEL_WORKFLOW), to cache for the lifetime of the worker (VINE_CACHE_LEVEL_WORKER), or to cache at execution site even when worker terminates (VINE_CACHE_LEVEL_FOREVER).
flagsFlags that can be or'ed (|) to indicate whether a file should not be transferred among workers (VINE_PEER_NOSHARE) when peer transfers are enabled (vine_enable_peer_transfers), or whether a file should be delete at the manager's site after it is not needed by the workflow (vine_undeclare_file).
Returns
A file object to use in vine_task_add_input

◆ vine_declare_untar()

struct vine_file* vine_declare_untar ( struct vine_manager *  m,
struct vine_file *  f,
vine_cache_level_t  cache,
vine_file_flags_t  flags 
)

Create a file object by unpacking a tar archive.

The archive may be compressed in any of the ways supported by tar, and so this function supports extensions .tar, .tar.gz, .tgz, tar.bz2, and so forth.

Parameters
mA manager object
fA file object corresponding to an archive packed by the tar command.
cacheMethod for caching file at the workers: never, the default (VINE_CACHE_LEVEL_TASK), to cache only for the current manager (VINE_CACHE_LEVEL_WORKFLOW), to cache for the lifetime of the worker (VINE_CACHE_LEVEL_WORKER), or to cache at execution site even when worker terminates (VINE_CACHE_LEVEL_FOREVER).
flagsFlags that can be or'ed (|) to indicate whether a file should not be transferred among workers (VINE_PEER_NOSHARE) when peer transfers are enabled (vine_enable_peer_transfers), or whether a file should be delete at the manager's site after it is not needed by the workflow (vine_undeclare_file).
Returns
A file object to use in vine_task_add_input

◆ vine_declare_poncho()

struct vine_file* vine_declare_poncho ( struct vine_manager *  m,
struct vine_file *  f,
vine_cache_level_t  cache,
vine_file_flags_t  flags 
)

Create a file object by unpacking a poncho package.

Parameters
mA manager object
fA file object corresponding to poncho or conda-pack tarball
cacheMethod for caching file at the workers: never, the default (VINE_CACHE_LEVEL_TASK), to cache only for the current manager (VINE_CACHE_LEVEL_WORKFLOW), to cache for the lifetime of the worker (VINE_CACHE_LEVEL_WORKER), or to cache at execution site even when worker terminates (VINE_CACHE_LEVEL_FOREVER).
flagsFlags that can be or'ed (|) to indicate whether a file should not be transferred among workers (VINE_PEER_NOSHARE) when peer transfers are enabled (vine_enable_peer_transfers), or whether a file should be delete at the manager's site after it is not needed by the workflow (vine_undeclare_file).
Returns
A file object to use in vine_task_add_input

◆ vine_declare_starch()

struct vine_file* vine_declare_starch ( struct vine_manager *  m,
struct vine_file *  f,
vine_cache_level_t  cache,
vine_file_flags_t  flags 
)

Create a file object by unpacking a starch package.

Parameters
mA manager object
fA file object representing a sfx archive.
cacheMethod for caching file at the workers: never, the default (VINE_CACHE_LEVEL_TASK), to cache only for the current manager (VINE_CACHE_LEVEL_WORKFLOW), to cache for the lifetime of the worker (VINE_CACHE_LEVEL_WORKER), or to cache at execution site even when worker terminates (VINE_CACHE_LEVEL_FOREVER).
flagsFlags that can be or'ed (|) to indicate whether a file should not be transferred among workers (VINE_PEER_NOSHARE) when peer transfers are enabled (vine_enable_peer_transfers), or whether a file should be delete at the manager's site after it is not needed by the workflow (vine_undeclare_file).
Returns
A file object to use in vine_task_add_input

◆ vine_fetch_file()

const char* vine_fetch_file ( struct vine_manager *  m,
struct vine_file *  f 
)

Fetch the contents of a file.

The contents of the given file will be loaded from disk or pulled back from the cluster and loaded into manager memory. This is particularly useful for temporary files and mini-tasks whose contents are not returned to the manager by default.

Parameters
mA manager object
fA file object.
Returns
A pointer to the contents of the file. This will be freed with the file object.

◆ vine_undeclare_file()

void vine_undeclare_file ( struct vine_manager *  m,
struct vine_file *  f 
)

Un-declare a file that was created by vine_declare_file or similar functions.

The given file or directory object is deleted from all worker's caches, and is no longer available for use as an input file. Completed tasks waiting for retrieval are not affected. Note that all declared files are automatically undeclared by vine_delete, however this function can be used for earlier cleanup of unneeded file objects.

Parameters
mA manager object
fAny file object.

◆ vine_create()

struct vine_manager* vine_create ( int  port)

Create a new manager.

Users may modify the behavior of vine_create by setting the following environmental variables before calling the function:

  • VINE_PORT: This sets the default port of the manager (if unset, the default is 9123).
  • VINE_LOW_PORT: If the user requests a random port, then this sets the first port number in the scan range (if unset, the default is 1024).
  • VINE_HIGH_PORT: If the user requests a random port, then this sets the last port number in the scan range (if unset, the default is 32767).
  • VINE_NAME: This sets the project name of the manager, which is reported to a catalog server (by default this is unset).
  • VINE_PRIORITY: This sets the priority of the manager, which is used by workers to sort managers such that higher priority managers will be served first (if unset, the default is 10).

If the manager has a project name, then manager statistics and information will be reported to a catalog server. To set the catalog server, the user may set the CATALOG_HOST and CATALOG_PORT environmental variables as described in catalog_query_create.

Parameters
portThe port number to listen on. If zero is specified, then the port stored in the VINE_PORT environment variable is used if available. If it isn't, or if -1 is specified, the first unused port between VINE_LOW_PORT and VINE_HIGH_PORT (1024 and 32767 by default) is chosen.
Returns
A new manager, or null if it could not be created.

◆ vine_ssl_create()

struct vine_manager* vine_ssl_create ( int  port,
const char *  key,
const char *  cert 
)

Create a new manager using SSL.

Like vine_create, but all communications with the manager are encoded using TLS with they key and certificate provided. If key or cert are NULL, then TLS is not activated.

Parameters
portThe port number to listen on. If zero is specified, then the port stored in the VINE_PORT environment variable is used if available. If it isn't, or if -1 is specified, the first unused port between VINE_LOW_PORT and VINE_HIGH_PORT (1024 and 32767 by default) is chosen.
keyA key in pem format.
certA certificate in pem format.

◆ vine_delete()

void vine_delete ( struct vine_manager *  m)

Delete a manager.

This function should only be called after vine_empty returns true.

Parameters
mA manager to delete.

◆ vine_submit()

int vine_submit ( struct vine_manager *  m,
struct vine_task *  t 
)

Submit a task to a manager.

Once a task is submitted to a manager, it is not longer under the user's control and should not be inspected until returned via vine_wait. Once returned, it is safe to re-submit the same take object via vine_submit.

Parameters
mA manager object
tA task object returned from vine_task_create.
Returns
An integer task_id assigned to the submitted task. Zero indicates a failure to submit due to an invalid task description.

◆ vine_manager_install_library()

void vine_manager_install_library ( struct vine_manager *  m,
struct vine_task *  t,
const char *  name 
)

Indicate the library to be installed on all workers connected to the manager.

The library is expected to run on all workers until they disconnect from the manager.

Parameters
mA manager object
tA task object.
nameThe library to be installed

◆ vine_manager_remove_library()

void vine_manager_remove_library ( struct vine_manager *  m,
const char *  name 
)

Indicate the library to be removed from all connected workers.

Parameters
mA manager object
nameThe library to be removed

◆ vine_wait()

struct vine_task* vine_wait ( struct vine_manager *  m,
int  timeout 
)

Wait for a task to complete.

This call will block until either a task has completed, the timeout has expired, or the manager is empty. If a task has completed, the corresponding task object will be returned by this function. The caller may examine the task and then dispose of it using vine_task_delete.

If the task ran to completion, then the result field will be zero and the return_status field will contain the Unix exit code of the task. If the task could not, then the result field will be non-zero and the return_status field will be undefined.

Parameters
mA manager object
timeoutThe number of seconds to wait for a completed task before returning. Use an integer time to set the timeout or the constant VINE_WAIT_FOREVER to block until a task has completed.
Returns
A completed task description, or null if the manager is empty, or the timeout was reached without a completed task, or there is completed child process (call process_wait to retrieve the status of the completed child process).

◆ vine_wait_for_tag()

struct vine_task* vine_wait_for_tag ( struct vine_manager *  m,
const char *  tag,
int  timeout 
)

Wait for a task with a given task to complete.

Similar to vine_wait, but guarantees that the returned task has the specified tag.

Parameters
mA manager object
tagThe desired tag. If NULL, then tasks are returned regardless of their tag.
timeoutThe number of seconds to wait for a completed task before returning. Use an integer time to set the timeout or the constant VINE_WAIT_FOREVER to block until a task has completed.
Returns
A completed task description, or null if the manager is empty, or the timeout was reached without a completed task, or there is completed child process (call process_wait to retrieve the status of the completed child process).

◆ vine_wait_for_task_id()

struct vine_task* vine_wait_for_task_id ( struct vine_manager *  m,
int  task_id,
int  timeout 
)

Wait for a task with a given task_id to complete.

Similar to vine_wait, but guarantees that the returned task has the specified task_id.

Parameters
mA manager object
task_idThe desired task_id. If -1, then tasks are returned regardless of their task_id.
timeoutThe number of seconds to wait for a completed task before returning. Use an integer time to set the timeout or the constant VINE_WAIT_FOREVER to block until a task has completed.
Returns
A completed task description, or null if the manager is empty, or the timeout was reached without a completed task, or there is completed child process (call process_wait to retrieve the status of the completed child process).

◆ vine_hungry()

int vine_hungry ( struct vine_manager *  m)

Determine whether the manager is 'hungry' for more tasks.

While the manager can handle a very large number of tasks, it runs most efficiently when the number of tasks is slightly larger than the number of active workers. This function gives the user of a flexible application a hint about whether it would be better to submit more tasks via vine_submit or wait for some to complete via vine_wait.

Parameters
mA manager object
Returns
The number of additional tasks that can be efficiently submitted, or zero if the manager has enough to work with right now.

◆ vine_empty()

int vine_empty ( struct vine_manager *  m)

Determine whether the manager is empty.

When all of the desired tasks have been submitted to the manager, the user should continue to call vine_wait until this function returns true.

Parameters
mA manager object
Returns
True if the manager is completely empty, false otherwise.

◆ vine_port()

int vine_port ( struct vine_manager *  m)

Get the listening port of the manager.

As noted in vine_create, there are many controls that affect what TCP port the manager will listen on. Rather than assuming a specific port, the user should simply call this function to determine what port was selected.

Parameters
mA manager object
Returns
The port the manager is listening on.

◆ vine_set_name()

void vine_set_name ( struct vine_manager *  m,
const char *  name 
)

Change the project name for a given manager.

Parameters
mA manager object
nameThe new project name.

◆ vine_get_name()

const char* vine_get_name ( struct vine_manager *  m)

Get the project name of the manager.

Parameters
mA manager object
Returns
The project name of the manager.

◆ vine_enable_monitoring()

int vine_enable_monitoring ( struct vine_manager *  m,
int  watchdog,
int  time_series 
)

Enables resource monitoring for tasks.

The resources measured are available in the resources_measured member of the respective vine_task.

Parameters
mA manager object
watchdogIf not 0, kill tasks that exhaust declared resources.
time_seriesIf not 0, generate a time series of resources per task in VINE_RUNTIME_INFO_DIR/vine-logs/time-series/ (WARNING: for long running tasks these files may reach gigabyte sizes. This function is mostly used for debugging.)
Returns
1 on success, 0 if monitoring could not be enabled.

◆ vine_enable_peer_transfers()

int vine_enable_peer_transfers ( struct vine_manager *  m)

Enable taskvine peer transfers to be scheduled by the manager.

◆ vine_disable_peer_transfers()

int vine_disable_peer_transfers ( struct vine_manager *  m)

Disable taskvine peer transfers to be scheduled by the manager.

◆ vine_set_task_id_min()

int vine_set_task_id_min ( struct vine_manager *  m,
int  minid 
)

Set the minimum task_id of future submitted tasks.

Further submitted tasks are guaranteed to have a task_id larger or equal to minid. This function is useful to make task_ids consistent in a workflow that consists of sequential managers. (Note: This function is rarely used). If the minimum id provided is smaller than the last task_id computed, the minimum id provided is ignored.

Parameters
mA manager object
minidMinimum desired task_id
Returns
Returns the actual minimum task_id for future tasks.

◆ vine_block_host()

void vine_block_host ( struct vine_manager *  m,
const char *  hostname 
)

Block workers in hostname from working for manager q.

Parameters
mA manager object
hostnameA string for hostname.

◆ vine_block_host_with_timeout()

void vine_block_host_with_timeout ( struct vine_manager *  m,
const char *  hostname,
time_t  seconds 
)

Block workers in hostname from a manager, but remove block after timeout seconds.

If timeout is less than 1, then the hostname is blocked indefinitely, as if vine_block_host was called instead.

Parameters
mA manager object
hostnameA string for hostname.
secondsNumber of seconds to the hostname will be blocked.

◆ vine_unblock_host()

void vine_unblock_host ( struct vine_manager *  m,
const char *  hostname 
)

Unblock host from a manager.

Parameters
mA manager object
hostnameA string for hostname.

◆ vine_unblock_all()

void vine_unblock_all ( struct vine_manager *  m)

Unblock all host.

Parameters
mA manager object

◆ vine_get_stats()

void vine_get_stats ( struct vine_manager *  m,
struct vine_stats s 
)

Get manager statistics (only from manager)

Parameters
mA manager object
sA pointer to a buffer that will be filed with statistics

◆ vine_get_stats_category()

void vine_get_stats_category ( struct vine_manager *  m,
const char *  c,
struct vine_stats s 
)

Get the task statistics for the given category.

Parameters
mA manager object
cA category name
sA pointer to a buffer that will be filed with statistics

◆ vine_get_status()

char* vine_get_status ( struct vine_manager *  m,
const char *  request 
)

Get manager information as json.

Parameters
mA manager object
requestOne of: manager, tasks, workers, or categories

◆ vine_summarize_workers()

struct rmsummary** vine_summarize_workers ( struct vine_manager *  m)

Summary data for all workers in buffer.

Parameters
mA manager object
Returns
A null terminated array of struct rmsummary. Each summary s indicates the number of s->workers with a certain number of s->cores, s->memory, and s->disk. The array and summaries need to be freed after use to avoid memory leaks.

◆ vine_set_bandwidth_limit()

void vine_set_bandwidth_limit ( struct vine_manager *  m,
const char *  bandwidth 
)

Limit the manager bandwidth when transferring files to and from workers.

Parameters
mA manager object
bandwidthThe bandwidth limit in bytes per second.

◆ vine_get_effective_bandwidth()

double vine_get_effective_bandwidth ( struct vine_manager *  m)

Get current manager bandwidth.

Parameters
mA manager object
Returns
The average bandwidth in MB/s measured by the manager.

◆ vine_enable_disconnect_slow_workers()

int vine_enable_disconnect_slow_workers ( struct vine_manager *  m,
double  multiplier 
)

Enable disconnect slow workers functionality for a given manager for tasks without an explicit category.

Given the multiplier, disconnect a worker when it is executing a task with a running time is larger than the average times the multiplier. The average is s computed per task category. The value specified here applies to all the categories for which vine_enable_disconnect_slow_workers_category was not explicitely called.

Parameters
mA manager object
multiplierThe multiplier of the average task time at which point to disconnect; Disabled if less than 1.
Returns
0 if activated, 1 if deactivated.

◆ vine_enable_disconnect_slow_workers_category()

int vine_enable_disconnect_slow_workers_category ( struct vine_manager *  m,
const char *  category,
double  multiplier 
)

Enable disconnect slow workers functionality for a given category.

As vine_enable_disconnect_slow_workers, but for a single task category. (Note: vine_enable_disconnect_slow_workers_category(q, "default", n) is the same as vine_enable_disconnect_slow_workers(q, n).)

Parameters
mA manager object
categoryA category name.
multiplierThe multiplier of the average task time at which point to disconnect; If less than one (default), use the multiplier of the "default" category.
Returns
0 if activated, 1 if deactivated.

◆ vine_set_draining_by_hostname()

int vine_set_draining_by_hostname ( struct vine_manager *  m,
const char *  hostname,
int  drain_flag 
)

Set the draining mode per worker hostname.

If drain_flag is 0, workers at hostname receive tasks as usual. If drain_flag is not 1, no new tasks are dispatched to workers at hostname, and if empty they are shutdown.

Parameters
mA manager object
hostnameThe hostname running the worker.
drain_flagDraining mode.

◆ vine_set_category_mode()

int vine_set_category_mode ( struct vine_manager *  m,
const char *  category,
vine_category_mode_t  mode 
)

Turn on or off first-allocation labeling for a given category.

By default, cores, memory, and disk are labeled, and gpus are unlabeled. Turn on/off other specific resources use vine_enable_category_resource

Parameters
mA manager object
categoryA category name.
modeOne of vine_category_mode_t.
Returns
1 if mode is valid, 0 otherwise.

◆ vine_enable_category_resource()

int vine_enable_category_resource ( struct vine_manager *  m,
const char *  category,
const char *  resource,
int  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 vine_set_category_mode.

Parameters
mA manager object
categoryA category name.
resourceA resource name.
autolabel0 off, 1 on.
Returns
1 if resource is valid, 0 otherwise.

◆ vine_set_scheduler()

void vine_set_scheduler ( struct vine_manager *  m,
vine_schedule_t  algorithm 
)

Change the worker selection algorithm.

This function controls which worker will be selected for a given task.

Parameters
mA manager object
algorithmThe algorithm to use in assigning a task to a worker. See vine_schedule_t for possible values.

◆ vine_set_priority()

void vine_set_priority ( struct vine_manager *  m,
int  priority 
)

Change the priority for a given manager.

Parameters
mA manager object
priorityThe new priority of the manager. Higher priority managers will attract workers first.

◆ vine_set_tasks_left_count()

void vine_set_tasks_left_count ( struct vine_manager *  m,
int  ntasks 
)

Specify the number of tasks not yet submitted to the manager.

It is used by vine_factory to determine the number of workers to launch. If not specified, it defaults to 0. vine_factory considers the number of tasks as: num tasks left + num tasks running + num tasks read.

Parameters
mA manager object
ntasksNumber of tasks yet to be submitted.

◆ vine_set_catalog_servers()

void vine_set_catalog_servers ( struct vine_manager *  m,
const char *  hosts 
)

Specify the catalog server(s) the manager should report to.

Parameters
mA manager object
hostsThe catalog servers given as a comma delimited list of hostnames or hostname:port

◆ vine_set_property()

void vine_set_property ( struct vine_manager *  m,
const char *  name,
const char *  value 
)

Add a global property to the manager which will be included in periodic reports to the catalog server and other telemetry destinations.

This is helpful for distinguishing higher level information about the entire run, such as the name of the framework being used, or the logical name of the dataset being processed.

Parameters
mA manager object
nameThe name of the property.
valueThe value of the property.

◆ vine_cancel_by_task_id()

int vine_cancel_by_task_id ( struct vine_manager *  m,
int  id 
)

Cancel a submitted task using its task id.

The cancelled task will be returned in the normal way via vine_wait with a result of VINE_RESULT_CANCELLED.

Parameters
mA manager object
idThe task_id returned from vine_submit.
Returns
True if the task was found in the manager and cancelled, false otherwise.

◆ vine_cancel_by_task_tag()

int vine_cancel_by_task_tag ( struct vine_manager *  m,
const char *  tag 
)

Cancel a submitted task using its tag and remove it from manager.

The cancelled task will be returned in the normal way via vine_wait with a result of VINE_RESULT_CANCELLED.

Parameters
mA manager object
tagThe tag name assigned to task using vine_task_set_tag.
Returns
True if the task was found in the manager and cancelled, false otherwise.

◆ vine_cancel_all()

int vine_cancel_all ( struct vine_manager *  m)

Cancel all submitted tasks and remove them from the manager.

Each cancelled task will be returned in the normal way via vine_wait with a result of VINE_RESULT_CANCELLED.

Parameters
mA manager object
Returns
The number of tasks cancelled.

◆ vine_enable_debug_log()

int vine_enable_debug_log ( const char *  logfile)

Turn on the debugging log output and send to the named file.

(Note it does not need the vine_manager structure, as it is enabled before the manager is created.)

Parameters
logfileThe filename.
Returns
1 if logfile was opened, 0 otherwise.

◆ vine_enable_perf_log()

int vine_enable_perf_log ( struct vine_manager *  m,
const char *  logfile 
)

Add a performance log file that records cummulative statistics of the connected workers and submitted tasks.

Parameters
mA manager object
logfileThe filename.
Returns
1 if logfile was opened, 0 otherwise.

◆ vine_enable_transactions_log()

int vine_enable_transactions_log ( struct vine_manager *  m,
const char *  logfile 
)

Add a log file that records the states of the connected workers and tasks.

Parameters
mA manager object
logfileThe filename.
Returns
1 if logfile was opened, 0 otherwise.

◆ vine_enable_taskgraph_log()

int vine_enable_taskgraph_log ( struct vine_manager *  m,
const char *  logfile 
)

Add an output log that produces the taskgraph in Grapvhiz Dot format.

Parameters
mA manager object
logfileThe filename.
Returns
1 if logfile was opened, 0 otherwise.

◆ vine_workers_shutdown()

int vine_workers_shutdown ( struct vine_manager *  m,
int  n 
)

Shut down workers connected to the manager.

Gives a best effort and then returns the number of workers given the shut down order.

Parameters
mA manager object
nThe number to shut down. All workers if given "0".

◆ vine_set_password()

void vine_set_password ( struct vine_manager *  m,
const char *  password 
)

Add a mandatory password that each worker must present.

Parameters
mA manager object
passwordThe password to require.

◆ vine_set_password_file()

int vine_set_password_file ( struct vine_manager *  m,
const char *  file 
)

Add a mandatory password file that each worker must present.

Parameters
mA manager object
fileThe name of the file containing the password.
Returns
True if the password was loaded, false otherwise.

◆ vine_set_keepalive_interval()

void vine_set_keepalive_interval ( struct vine_manager *  m,
int  interval 
)

Change the keepalive interval for a given manager.

Parameters
mA manager object
intervalThe minimum number of seconds to wait before sending new keepalive checks to workers.

◆ vine_set_keepalive_timeout()

void vine_set_keepalive_timeout ( struct vine_manager *  m,
int  timeout 
)

Change the keepalive timeout for identifying dead workers for a given manager.

Parameters
mA manager object
timeoutThe minimum number of seconds to wait for a keepalive response from worker before marking it as dead.

◆ vine_set_manager_preferred_connection()

void vine_set_manager_preferred_connection ( struct vine_manager *  m,
const char *  preferred_connection 
)

Set the preference for using hostname over IP address to connect.

'by_ip' uses IP addresses from the network interfaces of the manager (standard behavior), 'by_hostname' to use the hostname at the manager, or 'by_apparent_ip' to use the address of the manager as seen by the catalog server.

Parameters
mA manager object
preferred_connectionAn string to indicate using 'by_ip' or a 'by_hostname'.

◆ vine_tune()

int vine_tune ( struct vine_manager *  m,
const char *  name,
double  value 
)

Tune advanced parameters for manager.

Parameters
mA manager object
nameThe name of the parameter to tune
  • "resource-submit-multiplier" Treat each worker as having ({cores,memory,gpus} * multiplier) when submitting tasks. This allows for tasks to wait at a worker rather than the manager. (default = 1.0)
  • "min-transfer-timeout" Set the minimum number of seconds to wait for files to be transferred to or from a worker. (default=10)
  • "transfer-outlier-factor" Transfer that are this many times slower than the average will be terminated. (default=10x)
  • "default-transfer-rate" The assumed network bandwidth used until sufficient data has been collected. (1MB/s)
  • "disconnect-slow-workers-factor" Set the multiplier of the average task time at which point to disconnect; deactivated if less than 1. (default=0)
  • "keepalive-interval" Set the minimum number of seconds to wait before sending new keepalive checks to workers. (default=300)
  • "keepalive-timeout" Set the minimum number of seconds to wait for a keepalive response from worker before marking it as dead. (default=30)
  • "short-timeout" Set the minimum timeout when sending a brief message to a single worker. (default=5s)
  • "monitor-interval" Maximum number of seconds between resource monitor measurements. If less than 1, use default (5s). (default=5)
  • "category-steady-n-tasks" Set the number of tasks considered when computing category buckets.
  • "hungry-minimum" Mimimum number of tasks to consider manager not hungry. (default=10)
  • "wait-for-workers" Mimimum number of workers to connect before starting dispatching tasks. (default=0)
  • "attempt-schedule-depth" The amount of tasks to attempt scheduling on each pass of send_one_task in the main loop. (default=100)
  • "wait_retrieve_many" Parameter to alter how vine_wait works. If set to 0, vine_wait breaks out of the while loop whenever a task changes to VINE_TASK_DONE (wait_retrieve_one mode). If set to 1, vine_wait does not break, but continues recieving and dispatching tasks. This occurs until no task is sent or recieved, at which case it breaks out of the while loop (wait_retrieve_many mode). (default=0)
  • "monitor-interval" Parameter to change how frequently the resource monitor records resource consumption of a task in a times series, if this feature is enabled. See vine_enable_monitoring.
  • "update_interval" Seconds between updates to the catalog. (default=60)
  • "temp-replica-count" Degree of replication across workers for remote temp files (default=0)
  • "transient-error-interval" Time to wait in seconds after a resource failure before attempting to use it again (default=15)
  • "resource_management_interval" Seconds between measurement of manager local resources. (default=30)
  • "max_task_stdout_storage" Maximum size of standard output from task. (If larger, send to a separate file.) (default=1*GIGABYTE)
  • "max_new_workers" Maximum number of workers to add in a single cycle before dealing with other matters. (default=10)
  • "large_task_check_interval" How frequently to check for tasks that do not fit any worker. (default=180000000)
  • "option_blocklist_slow_workers_timeout" Timeout for slow workers to come back to the pool. (default=900)
valueThe value to set the parameter to.
Returns
0 on succes, -1 on failure.

◆ vine_set_resources_max()

void vine_set_resources_max ( struct vine_manager *  m,
const struct rmsummary rm 
)

Sets the maximum resources a task without an explicit category ("default" category).

rm specifies the maximum resources a task in the default category may use.

Parameters
mReference to the current manager object.
rmStructure indicating maximum values. See rmsummary for possible fields.

◆ vine_set_resources_min()

void vine_set_resources_min ( struct vine_manager *  m,
const struct rmsummary rm 
)

Sets the minimum resources a task without an explicit category ("default" category).

rm specifies the maximum resources a task in the default category may use.

Parameters
mReference to the current manager object.
rmStructure indicating maximum values. See rmsummary for possible fields.

◆ vine_set_category_resources_max()

void vine_set_category_resources_max ( struct vine_manager *  m,
const char *  category,
const struct rmsummary rm 
)

Sets the maximum resources a task in the category may use.

Parameters
mReference to the current manager object.
categoryName of the category.
rmStructure indicating minimum values. See rmsummary for possible fields.

◆ vine_set_category_resources_min()

void vine_set_category_resources_min ( struct vine_manager *  m,
const char *  category,
const struct rmsummary rm 
)

Sets the minimum resources a task in the category may use.

Parameters
mReference to the current manager object.
categoryName of the category.
rmStructure indicating minimum values. See rmsummary for possible fields.

◆ vine_set_category_first_allocation_guess()

void vine_set_category_first_allocation_guess ( struct vine_manager *  m,
const char *  category,
const struct rmsummary rm 
)

Set the initial guess for resource autolabeling for the given category.

Parameters
mReference to the current manager object.
categoryName of the category.
rmStructure indicating maximum values. Autolabeling available for cores, memory, disk, and gpus

◆ vine_initialize_categories()

void vine_initialize_categories ( struct vine_manager *  m,
struct rmsummary max,
const char *  summaries_file 
)

Initialize first value of categories.

Parameters
mReference to the current manager object.
maxStructure indicating maximum values. Autolabeling available for cores, memory, disk, and gpus
summaries_fileJSON file with resource summaries.

◆ vine_set_runtime_info_path()

void vine_set_runtime_info_path ( const char *  path)

Sets the path where runtime info directories (logs and staging) are created.

Parameters
pathA directory

◆ vine_log_debug_app()

void vine_log_debug_app ( struct vine_manager *  q,
const char *  entry 
)

Adds a custom APPLICATION entry to the debug log.

Parameters
mReference to the current manager object.
entryA custom debug message.

◆ vine_log_txn_app()

void vine_log_txn_app ( struct vine_manager *  q,
const char *  entry 
)

Adds a custom APPLICATION entry to the transactions log.

Parameters
mReference to the current manager object.
entryA custom transaction message.