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

dxid Job 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_input	A 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_name	Name of the function (in the current app or applet) to use as the entry point.
job_name	Name for the resulting job. If blank string is given, then (default name of parent job + ":fn_name") will be used instead.
depends_on	A 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_type	A 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

field The 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_input	A 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_name	Name of the function (in the current app or applet) to use as the entry point.
job_name	Name for the resulting job. If blank string is given, then (default name of parent job + ":fn_name") will be used instead.
depends_on	A list of Job ID's (string), representing jobs that must finish before this job should start running.
instance_type	A 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

dxid Job 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

timeout Maximum 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:

cpp/dxcpp/bindings/dxjob.h
cpp/dxcpp/bindings/dxjob.cc

Public Member Functions

Static Public Member Functions

Detailed Description

Constructor & Destructor Documentation

Member Function Documentation