cctools
taskvine_json.h File Reference

Provides a higher-level JSON-oriented abstraction on top of the standard C interface in taskvine.h. More...

Go to the source code of this file.

Functions

struct vine_manager * vine_json_create (const char *str)
 Create a new manager object. More...
 
int vine_json_submit (struct vine_manager *m, const char *str)
 Submit a task to a manager. More...
 
char * vine_json_wait (struct vine_manager *m, int timeout)
 Wait for a task to complete. More...
 
int vine_json_empty (struct vine_manager *m)
 Determine whether the manager is 'hungry' for more tasks. More...
 
int vine_json_hungry (struct vine_manager *m)
 Determine whether the manager is empty. More...
 
char * vine_json_remove (struct vine_manager *m, int id)
 Remove a task from the manager. More...
 
char * vine_json_get_status (struct vine_manager *m)
 Get the status for a given manager. More...
 
void vine_json_delete (struct vine_manager *m)
 Delete a vine_manager object. More...
 

Detailed Description

Provides a higher-level JSON-oriented abstraction on top of the standard C interface in taskvine.h.

An application uses vine_json_create to create a manager, then vine_json_submit to submit tasks, and vine_json_wait to wait for completion. Details of tasks and the manager are carried in JSON details (which must be parsed) rather than in C structures. This provides a starting point for building interfaces to languages outside of C, without relying on SWIG.

This module is a work in progress and is not yet ready for production.

Function Documentation

struct vine_manager* vine_json_create ( const char *  str)

Create a new manager object.

Parameters
strA json document with properties to configure a new manager. Allowed properties are port, name, and priority.
Returns
A new manager, or null if it could not be created.
int vine_json_submit ( struct vine_manager *  m,
const char *  str 
)

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.
strA JSON description of a task.

task document: (only "command_line" is required.) { "command_line" : string, "input_files" : array of objects with one object per input file (see file document below), "output_files" : array of objects with one object per output file (see file document below), "environment" : object with environment variables names and values (see environment document below), "tag" : string, # arbitrary string to identify the task by the user. }

file document: { "local_name" : string, # name of the file at the machine running the manager "remote_name" : string, # name of the file local_name is copied to/from the machine running the task. "flags" : { "cache" : boolean, # whether the file should be cached at the worker. Default is false. "watch" : boolean, # For output files only. Whether appends to the file should be sent as they occur. Default is false. } }

environment document: { string : string, # name and value of an environment variable to be set for the task. string : string, ... }

Returns
An integer task_id assigned to the submitted task.
char* vine_json_wait ( struct vine_manager *  m,
int  timeout 
)

Wait for a task to complete.

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 JSON description of the completed task 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). Return string should be freed using free().

{ "command_line" : string , "tag" : string , "output" : string , "task_id" : integer , "return_status" : integer , "result" : integer }

int vine_json_empty ( struct vine_manager *  m)

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

While a taskvine 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 vine_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.
int vine_json_hungry ( 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 vine_manager object
Returns
True if the manager is completely empty, false otherwise.
char* vine_json_remove ( struct vine_manager *  m,
int  id 
)

Remove a task from the manager.

Parameters
mA manager object.
idThe id of the task to be removed from the manager.
Returns
A JSON description of the removed task.
char* vine_json_get_status ( struct vine_manager *  m)

Get the status for a given manager.

Parameters
mA manager object.
Returns
A JSON description of the stats of the given manager object.
void vine_json_delete ( struct vine_manager *  m)

Delete a vine_manager object.

Parameters
mA manager object.