All Classes Namespaces Files Functions Variables Pages
Public Member Functions | Static Public Member Functions | List of all members
dx::DXJob Class Reference

The instantiation of an applet or app. More...

#include <dxjob.h>

Public Member Functions

 DXJob (const std::string &dxid)
 
dx::JSON describe () const
 
void setID (const std::string &dxid)
 
std::string getState () const
 
std::string getID () const
 
void create (const dx::JSON &fn_input, const std::string &fn_name, const std::string &job_name="", const std::vector< std::string > &depends_on=std::vector< std::string >(), const dx::JSON &instance_type=dx::JSON(dx::JSON_NULL))
 
void terminate () const
 
void waitOnDone (const int timeout=std::numeric_limits< int >::max()) const
 
dx::JSON getOutputRef (const std::string &field)
 

Static Public Member Functions

static DXJob newDXJob (const dx::JSON &fn_input, const std::string &fn_name, const std::string &job_name="", const std::vector< std::string > &depends_on=std::vector< std::string >(), const dx::JSON &instance_type=dx::JSON(dx::JSON_NULL))
 

Detailed Description

The instantiation of an applet or app.

When a user runs an applet or app (for example with DXApplet::run or DXApp::run), a job object is created in the system; the job is then executed on a worker node.

A job may launch other jobs (for example, to parallelize its work). To facilitate this kind of pattern, an applet or app may define multiple entry points. The job may run a different entry point associated with the same applet or app, or another applet or app entirely.

Constructor & Destructor Documentation

dx::DXJob::DXJob ( const std::string &  dxid)
inline

Creates a DXJob handler for the specified remote job.

Parameters
dxidJob ID.

Member Function Documentation

void dx::DXJob::create ( const dx::JSON &  fn_input,
const std::string &  fn_name,
const std::string &  job_name = "",
const std::vector< std::string > &  depends_on = std::vector<std::string>(),
const dx::JSON &  instance_type = dx::JSON(dx::JSON_NULL) 
)

Creates a new job whose entry point is any function in the currently running app or applet. The specified input is provided to the new job. The handler is updated to point to the ID of the newly created job.

Note
This function can only be called from within a currently running job.
Parameters
fn_inputA hash of key/value pairs. This is a freeform JSON hash that will be passed verbatim to the job, after it is checked for the presence of links.
fn_nameName of the function (in the current app or applet) to use as the entry point.
job_nameName for the resulting job. If blank string is given, then (default name of parent job + ":fn_name") will be used instead.
depends_onA list of job IDs and/or data object IDs (string), representing jobs that must finish and/or data objects that must close before this job should start running.
instance_typeA string, or a JSON_HASH (values must be string), representing instance type on which the job will be run, or a mapping of function names to instance types. (Note: you can pass a std::map<string, string> as well)
JSON dx::DXJob::describe ( ) const

Returns a description of the job.

Returns
JSON hash describing the job, as given by the /job-xxxx/describe API method.
std::string dx::DXJob::getID ( ) const
inline

Returns the ID of the associated remote job.

Returns
A string giving the ID of a job, or blank string if the handler is associated with no job.
JSON dx::DXJob::getOutputRef ( const std::string &  field)

Constructs a JSON job-based object reference using the stored job ID and the given output field name. The JSON will be of the form

{"job": <job id>="">, "field", <job output="" field="" name>="">}

Parameters
fieldThe output field name to be referenced
Returns
JSON of the requested job-based object reference
std::string dx::DXJob::getState ( ) const
inline

Returns the current remote job state.

Returns
A string containing the current state of the job. Possible values are listed in the API specification.
DXJob dx::DXJob::newDXJob ( const dx::JSON &  fn_input,
const std::string &  fn_name,
const std::string &  job_name = "",
const std::vector< std::string > &  depends_on = std::vector<std::string>(),
const dx::JSON &  instance_type = dx::JSON(dx::JSON_NULL) 
)
static

Creates a new job whose entry point is any function in the currently running app or applet. The specified input is provided to the new job. The handler is updated to point to the ID of the newly created job.

Note
This function can only be called from within a currently running job.
Parameters
fn_inputA hash of key/value pairs. This is a freeform JSON hash that will be passed verbatim to the job, after it is checked for the presence of links.
fn_nameName of the function (in the current app or applet) to use as the entry point.
job_nameName for the resulting job. If blank string is given, then (default name of parent job + ":fn_name") will be used instead.
depends_onA list of Job ID's (string), representing jobs that must finish before this job should start running.
instance_typeA string, or a JSON_HASH (values must be string), representing instance type on which the job will be run, or a mapping of function names to instance types. (Note: you can pass a std::map<string, string> as well)
Returns
A DXJob handler for the newly created job.
void dx::DXJob::setID ( const std::string &  dxid)
inline

Updates the handler to refer to the specified remote job ID.

Parameters
dxidJob ID.
void dx::DXJob::terminate ( ) const

Terminates the job and all its descendant jobs.

This call is only valid for a job which has no parent.

void dx::DXJob::waitOnDone ( const int  timeout = std::numeric_limits<int>::max()) const

This function blocks until the associated job is in the "done" state, or the specified timeout value is exceeded.

Parameters
timeoutMaximum number of seconds to wait for job to move into "done" state. (Default ~= Infinity ( > 60yrs)).
Note
The actual timeout value in practice can be up to 2 seconds larger.
Warning
If the job the failed state, and no timeout value was provided, then this function will block forever. Use with caution.

The documentation for this class was generated from the following files: