A Tool for running Drmaa jobs. More...

#include <drmaa_tool.h>

Public Member Functions
DrmaaTool *	AllocateDrmaaTool (const char program_name_s, const uuid_t id, GrassrootsServer grassroots_p)
	Allocate a DrmaaTool to run the given program. More...

bool	InitDrmaaTool (DrmaaTool tool_p, const char program_name_s, const uuid_t id, GrassrootsServer *grassroots_p)
	Initialise a DrmaaTool to run the given program. More...

void	FreeDrmaaTool (DrmaaTool *tool_p)
	Free a DrmaaTool. More...

void	ClearDrmaaTool (DrmaaTool *tool_p)
	Clear a DrmaaTool. More...

bool	SetDrmaaToolCurrentWorkingDirectory (DrmaaTool tool_p, const char path_s)
	Set the current working directory for a DrmaaTool. More...

bool	SetDrmaaToolQueueName (DrmaaTool tool_p, const char queue_name_s)
	Set the queue name that a DrmaaTool will set for run its program on. More...

bool	SetDrmaaToolEnvVars (DrmaaTool tool_p, const char env_vars_s)
	Set the environment variables that a DrmaaTool will set when it runs its program. More...

bool	SetDrmaaToolCores (DrmaaTool *tool_p, uint32 num_cores)
	Set the number of cores that a DrmaaTool will use when it runs. More...

bool	SetDrmaaToolMemory (DrmaaTool *tool_p, uint32 mem)
	Set the amount of memory that a DrmaaTool will set for its program when it runs. More...

bool	SetDrmaaToolHostName (DrmaaTool tool_p, const char host_name_s)
	Set the host that a DrmaaTool will set for run its program on. More...

bool	SetDrmaaToolJobId (DrmaaTool tool_p, const char id_s)
	Set the id that represents the job that a DrmaaTool will run. More...

bool	SetDrmaaToolJobOutId (DrmaaTool tool_p, const char id_s)
	Set the id that represents the job output that a DrmaaTool will run. More...

bool	SetDrmaaToolJobName (DrmaaTool tool_p, const char job_name_s)
	Set the program that a DrmaaTool will run. More...

bool	SetDrmaaToolOutputFilename (DrmaaTool tool_p, const char output_name_s)
	Redirect the stdout/stderr streams from a DrmaaTool to a file. More...

bool	AddDrmaaToolArgument (DrmaaTool tool_p, const char arg_s)
	Add an argument to the program that a DrmaaTool will run. More...

bool	RunDrmaaTool (DrmaaTool tool_p, const bool async_flag, const char const log_s)
	Run a DrmaaTool. More...

OperationStatus	GetDrmaaToolStatus (DrmaaTool *tool_p)
	Get the status of job for a DrmaaTool. More...

bool	SetDrmaaToolEmailNotifications (DrmaaTool tool_p, const char *email_addresses_ss)
	Set the email recipients for any job notifications for a DrmaaTool. More...

json_t *	ConvertDrmaaToolToJSON (const DrmaaTool *const tool_p)
	Serialise the DrmaaTool into a JSON fragment. More...

DrmaaTool *	ConvertDrmaaToolFromJSON (const json_t const json_p, GrassrootsServer grassroots_p)
	Deserialise a DrmaaTool from a JSON fragment. More...

unsigned char *	SerialiseDrmaaTool (const DrmaaTool const job_p, const size_t size_p)
	Convert a DrmaaTool into a raw unsigned char array for use with the APRJobsManager. More...

DrmaaTool *	DeserialiseDrmaaTool (const unsigned char *const data_s)
	Create a DrmaaTool from an unsigned char array. More...

Detailed Description

A Tool for running Drmaa jobs.

Drmaa is a programmatic way of running jobs on grids, clusters or cloud-based systems. It allows to specify things such as the job to run, what resources it will use, whether to run asynchronously, etc.

Member Function Documentation

◆ AllocateDrmaaTool()

DrmaaTool * AllocateDrmaaTool	(	const char *	program_name_s,
		const uuid_t	id,
		GrassrootsServer *	grassroots_p
	)

Allocate a DrmaaTool to run the given program.

Parameters

program_name_s	The program that this DrmaaTool will run.
id	The id to give to this DrmaaTool.

Returns: A newly-allocated DrmaaTool or NULL upon error.

◆ InitDrmaaTool()

bool InitDrmaaTool	(	DrmaaTool *	tool_p,
		const char *	program_name_s,
		const uuid_t	id,
		GrassrootsServer *	grassroots_p
	)

Initialise a DrmaaTool to run the given program.

Parameters

tool_p	The DrmaaTool to initialise.
program_name_s	The program that this DrmaaTool will run.
id	The id to give to this DrmaaTool.

Returns: true if the DrmaaTool was initialised successfully, false upon error.

◆ FreeDrmaaTool()

void FreeDrmaaTool ( DrmaaTool * tool_p )

Free a DrmaaTool.

The DrmaaTool will be cleared and then the memory for the tool will be freed.

Parameters

tool_p The DrmaaTool to free.

See also: ClearDrmaaTool

◆ ClearDrmaaTool()

void ClearDrmaaTool ( DrmaaTool * tool_p )

Clear a DrmaaTool.

Parameters

tool_p The DrmaaTool to clear.

◆ SetDrmaaToolCurrentWorkingDirectory()

bool SetDrmaaToolCurrentWorkingDirectory	(	DrmaaTool *	tool_p,
		const char *	path_s
	)

Set the current working directory for a DrmaaTool.

Parameters

tool_p	The DrmaaTool to set the current working directory for.
path_s	The new current working directory . The DrmaaTool will make a copy of this so the parameter does not need to remain in memory after this call.

Returns: true if the current working directory was set successfully, false otherwise.

◆ SetDrmaaToolQueueName()

bool SetDrmaaToolQueueName	(	DrmaaTool *	tool_p,
		const char *	queue_name_s
	)

Set the queue name that a DrmaaTool will set for run its program on.

Parameters

tool_p	The DrmaaTool to set the queue name for.
queue_name_s	The queue name to use. The DrmaaTool will make a copy of this so the parameter does not need to remain in memory after this call.

Returns: true if the queue name was set successfully, false otherwise.

◆ SetDrmaaToolEnvVars()

bool SetDrmaaToolEnvVars	(	DrmaaTool *	tool_p,
		const char *	env_vars_s
	)

Set the environment variables that a DrmaaTool will set when it runs its program.

Parameters

tool_p	The DrmaaTool to set the environment variables for.
env_vars_s	The environment variables to use. The DrmaaTool will make a copy of this so the parameter does not need to remain in memory after this call.

Returns: true if the environment variables were set successfully, false otherwise.

◆ SetDrmaaToolCores()

bool SetDrmaaToolCores	(	DrmaaTool *	tool_p,
		uint32	num_cores
	)

Set the number of cores that a DrmaaTool will use when it runs.

Parameters

tool_p	The DrmaaTool to set the number of cores for.
num_cores	The number of cores that this DrmaaTool will use.

Returns: true if the number of cores was set successfully, false otherwise.

◆ SetDrmaaToolMemory()

bool SetDrmaaToolMemory	(	DrmaaTool *	tool_p,
		uint32	mem
	)

Set the amount of memory that a DrmaaTool will set for its program when it runs.

Parameters

tool_p	The DrmaaTool to set the memory for.
mem	The amount of memory in MB that this DrmaaTool will use.

Returns: true if the amount of memory was set successfully, false otherwise.

◆ SetDrmaaToolHostName()

bool SetDrmaaToolHostName	(	DrmaaTool *	tool_p,
		const char *	host_name_s
	)

Set the host that a DrmaaTool will set for run its program on.

Parameters

tool_p	The DrmaaTool to set the hostname for.
host_name_s	The hostname to use. The DrmaaTool will make a copy of this so the parameter does not need to remain in memory after this call.

Returns: true if the hostname was set successfully, false otherwise.

◆ SetDrmaaToolJobId()

bool SetDrmaaToolJobId	(	DrmaaTool *	tool_p,
		const char *	id_s
	)

Set the id that represents the job that a DrmaaTool will run.

Parameters

tool_p	The DrmaaTool to set the id for.
id_s	The id of the job.

Returns: true if the id was set successfully, false otherwise.

◆ SetDrmaaToolJobOutId()

bool SetDrmaaToolJobOutId	(	DrmaaTool *	tool_p,
		const char *	id_s
	)

Set the id that represents the job output that a DrmaaTool will run.

Parameters

tool_p	The DrmaaTool to set the id for.
id_s	The id of the job.

Returns: true if the id was set successfully, false otherwise.

◆ SetDrmaaToolJobName()

bool SetDrmaaToolJobName	(	DrmaaTool *	tool_p,
		const char *	job_name_s
	)

Set the program that a DrmaaTool will run.

Parameters

tool_p	The DrmaaTool to set the job for.
job_name_s	The program that this DrmaaTool will run. The DrmaaTool will make a copy of this so the parameter does not need to remain in memory after this call.

Returns: true if the program was set successfully, false otherwise.

◆ SetDrmaaToolOutputFilename()

bool SetDrmaaToolOutputFilename	(	DrmaaTool *	tool_p,
		const char *	output_name_s
	)

Redirect the stdout/stderr streams from a DrmaaTool to a file.

Parameters

tool_p	The DrmaaTool to redirect the streams for.
output_name_s	The filename where the streams output will be written to. The DrmaaTool will make a copy of this so the parameter does not need to remain in memory after this call.

Returns: true if the filename was set successfully, false otherwise.

◆ AddDrmaaToolArgument()

bool AddDrmaaToolArgument	(	DrmaaTool *	tool_p,
		const char *	arg_s
	)

Add an argument to the program that a DrmaaTool will run.

Parameters

tool_p	The DrmaaTool to add the argument for.
arg_s	The argument to add. The DrmaaTool will make a copy of this so the parameter does not need to remain in memory after this call.

Returns: true if the argument was added successfully, false otherwise.

◆ RunDrmaaTool()

bool RunDrmaaTool	(	DrmaaTool *	tool_p,
		const bool	async_flag,
		const char *const	log_s
	)

Run a DrmaaTool.

Parameters

tool_p	The DrmaaTool to add the argument for.
async_flag	If this is `true` then the method will return straight away and the job will continue to run asynchrnously or in the background. If this is `false` then this method will not return until the job has completed.
log_s	Optional filename for where to store the id of the Drmaa job that this DrmaaTool runs. If this is `NULL`, then the id will not be written to a file.

Returns: true if the job was started successfully, false otherwise. To get the status of whether the job completed successfully, use GetDrmaaToolStatus

See also: GetDrmaaToolStatus.

◆ GetDrmaaToolStatus()

OperationStatus GetDrmaaToolStatus ( DrmaaTool * tool_p )

Get the status of job for a DrmaaTool.

Parameters

tool_p The DrmaaTool to get the job status for.

Returns: The current status of the job for this DrmaaTool.

◆ SetDrmaaToolEmailNotifications()

bool SetDrmaaToolEmailNotifications	(	DrmaaTool *	tool_p,
		const char **	email_addresses_ss
	)

Set the email recipients for any job notifications for a DrmaaTool.

Parameters

tool_p	The DrmaaTool to get the job status for.
email_addresses_ss	An array of email addresses with the final element being NULL.

Returns: true if the email addresses were set successfully, false otherwise.

◆ ConvertDrmaaToolToJSON()

json_t * ConvertDrmaaToolToJSON ( const DrmaaTool *const tool_p )

Serialise the DrmaaTool into a JSON fragment.

Parameters

tool_p The DrmaaTool.

Returns: The JSON fragment or NULL upon error.

See also: ConvertDrmaaToolFromJSON

◆ ConvertDrmaaToolFromJSON()

DrmaaTool * ConvertDrmaaToolFromJSON	(	const json_t *const	json_p,
		GrassrootsServer *	grassroots_p
	)

Deserialise a DrmaaTool from a JSON fragment.

Parameters

json_p The JSON fragment.

Returns: The DrmaaTool or NULL upon error.

See also: ConvertDrmaaToolFromJSON

◆ SerialiseDrmaaTool()

unsigned char * SerialiseDrmaaTool	(	const DrmaaTool *const	job_p,
		const size_t *	size_p
	)

Convert a DrmaaTool into a raw unsigned char array for use with the APRJobsManager.

Parameters

job_p	The DrmaaTool to serialise.
size_p	Upon success, the size of the array will be stored here.

Returns: The raw unsigned char array or NULL upon error.

See also: DeserialiseDrmaaTool

◆ DeserialiseDrmaaTool()

DrmaaTool * DeserialiseDrmaaTool ( const unsigned char *const data_s )

Create a DrmaaTool from an unsigned char array.

Parameters

data_s The raw serialised data representing a DrmaaTool.

Returns: The DrmaaTool or NULL upon error.

See also: SerialiseDrmaaTool

The documentation for this struct was generated from the following file:

drmaa_tool.h

Public Member Functions

Detailed Description

Member Function Documentation

◆ AllocateDrmaaTool()

◆ InitDrmaaTool()

◆ FreeDrmaaTool()

◆ ClearDrmaaTool()

◆ SetDrmaaToolCurrentWorkingDirectory()

◆ SetDrmaaToolQueueName()

◆ SetDrmaaToolEnvVars()

◆ SetDrmaaToolCores()

◆ SetDrmaaToolMemory()

◆ SetDrmaaToolHostName()

◆ SetDrmaaToolJobId()

◆ SetDrmaaToolJobOutId()

◆ SetDrmaaToolJobName()

◆ SetDrmaaToolOutputFilename()

◆ AddDrmaaToolArgument()

◆ RunDrmaaTool()

◆ GetDrmaaToolStatus()

◆ SetDrmaaToolEmailNotifications()

◆ ConvertDrmaaToolToJSON()

◆ ConvertDrmaaToolFromJSON()

◆ SerialiseDrmaaTool()

◆ DeserialiseDrmaaTool()