mpi_queue.h File Reference

An MPI implementation of Work Queue. More...

#include "timestamp.h"

Go to the source code of this file.

Data Structures
struct	mpi_queue_task
	A task description. More...
Functions
struct mpi_queue_task *	mpi_queue_task_create (const char *full_command)
	Create a new task specification.
void	mpi_queue_task_specify_file (struct mpi_queue_task *t, const char *name, int type)
	Add a file to a task.
void	mpi_queue_task_specify_tag (struct mpi_queue_task *t, const char *tag)
	Attach a user defined logical name to the task.
void	mpi_queue_task_delete (struct mpi_queue_task *t)
	Delete a task specification.
struct mpi_queue *	mpi_queue_create (int port)
	Create a new work queue.
int	mpi_queue_submit (struct mpi_queue *q, struct mpi_queue_task *t)
	Submit a job to a work queue.
struct mpi_queue_task *	mpi_queue_wait (struct mpi_queue *q, int timeout)
	Wait for tasks to complete.
int	mpi_queue_empty (struct mpi_queue *q)
	Determine whether there are any known tasks queued, running, or waiting to be collected.
int	mpi_queue_port (struct mpi_queue *q)
	Get the listening port of the queue.
void	mpi_queue_delete (struct mpi_queue *q)
	Delete a work queue.

---

Detailed Description

An MPI implementation of Work Queue.

---

Function Documentation

struct mpi_queue_task* mpi_queue_task_create

(

const char *

full_command

)

[read]

Create a new task specification.

Once created, the task may be passed to mpi_queue_submit.

Parameters:

full_command

The shell command line to be executed by the task.

Returns:

A new mpi_queue_task structure.

void mpi_queue_task_specify_file	(	struct mpi_queue_task *	t,
		const char *	name,
		int	type
	)

Add a file to a task.

Parameters:

	t	The task to which to add a file.
	name	The name of the file on local disk or shared filesystem.
	type	Must be one of the following values: MPI_QUEUE_INPUT to indicate an input file to be consumed by the task MPI_QUEUE_OUTPUT to indicate an output file to be produced by the task

void mpi_queue_task_specify_tag	(	struct mpi_queue_task *	t,
		const char *	tag
	)

Attach a user defined logical name to the task.

This field is not interpreted by the work queue, but simply maintained to help the user track tasks.

Parameters:

	t	The task to which to add parameters
	tag	The tag to attach to task t.

void mpi_queue_task_delete

(

struct mpi_queue_task *

t

)

Delete a task specification.

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

Parameters:

t

The task specification to delete.

struct mpi_queue* mpi_queue_create

(

int

port

)

[read]

Create a new work queue.

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

• MPI_QUEUE_PORT: This sets the default port of the queue (if unset, the default is 9123).
• MPI_QUEUE_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).
• MPI_QUEUE_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).
• MPI_QUEUE_NAME: This sets the project name of the queue, which is reported to a catalog server (by default this is unset).
• MPI_QUEUE_PRIORITY: This sets the priority of the queue, which is used by workers to sort masters such that higher priority masters will be served first (if unset, the default is 10).

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

Parameters:

port

The port number to listen on. If zero is specified, then the default is chosen, and if -1 is specified, a random port is chosen.

Returns:

A new work queue, or null if it could not be created.

int mpi_queue_submit	(	struct mpi_queue *	q,
		struct mpi_queue_task *	t
	)

Submit a job to a work queue.

It is safe to re-submit a task returned by mpi_queue_wait.

Parameters:

	q	A work queue returned from mpi_queue_create.
	t	A task description returned from mpi_queue_task_create.

Returns:

The unique taskid assigned to the submitted task.

struct mpi_queue_task* mpi_queue_wait	(	struct mpi_queue *	q,
		int	timeout
	)			[read]

Wait for tasks to complete.

This call will block until the timeout has elapsed.

Parameters:

	q	The work queue to wait on.
	timeout	The number of seconds to wait for a completed task before returning. Use an integer time to set the timeout or the constant WAITFORTASK to block until a task has completed.

Returns:

A completed task description, or null if the queue is empty or the timeout was reached without a completed task. The returned task must be deleted with mpi_queue_task_delete or resubmitted with mpi_queue_submit.

int mpi_queue_empty

(

struct mpi_queue *

q

)

Determine whether there are any known tasks queued, running, or waiting to be collected.

Returns 0 if there are tasks remaining in the system, 1 if the system is "empty".

Parameters:

q

A pointer to the queue to query.

int mpi_queue_port

(

struct mpi_queue *

q

)

Get the listening port of the queue.

Parameters:

q

The work queue of interest.

Returns:

The port the queue is listening on.

void mpi_queue_delete

(

struct mpi_queue *

q

)

Delete a work queue.

Parameters:

q

The work queue to delete.