enum DC_WUState

typedef enum {
	DC_WU_READY,	/* Created, but not yet submitted */
	DC_WU_RUNNING,	/* Submitted and running */
	DC_WU_FINISHED,	/* The WU finished normally according to the grid
			   infrastructure. Note that the application client
			   returning an error code is considered a 'normal'
			   shutdown as far as the infrastructure is concerned,
			   so you should check the exit status and/or other
			   output. */
	DC_WU_SUSPENDED,/* The work unit is suspended */
	DC_WU_ABORTED,	/* The WU was aborted for some reason (infrastructure
			   failure, no canonical result, or by calling
			   DC_cancel()) */
	DC_WU_UNKNOWN	/* The WU's state is not known. This may happen for
			   example when a WU is serialized, then it finishes,
			   and upon deserialization the underlying grid
			   infrastructure no longer knows about it */
} DC_WUState;

State of work units.

enum DC_MasterEventType

typedef enum {
	DC_MASTER_RESULT,	/* A DC_Result is available */
	DC_MASTER_SUBRESULT,	/* A sub-result is available */
	DC_MASTER_MESSAGE	/* A message has arrived */
} DC_MasterEventType;

Types of events the master application may receive.

DC_Workunit

typedef struct _DC_Workunit DC_Workunit;

Opaque type representing a work unit. A work unit consists of an executable client application together with its command-line parameters and input files.

DC_Result

typedef struct _DC_Result DC_Result;

Opaque type representing the result of a successfully completed work unit. The result structure contains the output files the work unit produced as well as (optionally, depending on the infrastructure) its exit code, standard output and error, and any log file created by the grid infrastructure.

DC_MasterEvent

typedef struct {
	DC_MasterEventType	type;
	DC_Workunit		*wu;
	union
	{
		DC_Result	*result;
		DC_PhysicalFile	*subresult;
		char		*message;
	};
} DC_MasterEvent;

Describes an event received by the master application.

DC_ResultCallback ()

void        (*DC_ResultCallback)            (DC_Workunit *wu,
                                             DC_Result *result);

Prototype of the callback function used for reporting results.

DC_SubresultCallback ()

void        (*DC_SubresultCallback)         (DC_Workunit *wu,
                                             const char *logicalFileName,
                                             const char *path);

Prototype of the callback function used for reporting subresults. Note that if the infrastructure supports redundant computation, subresults may arrive from all running instances, even if they will be later marked as invalid.

DC_MessageCallback ()

void        (*DC_MessageCallback)           (DC_Workunit *wu,
                                             const char *message);

Prototype of the callback function used for reporting messages. Note that if the infrastructure supports redundant computation, the master will receive messages from all running client instances, even if they will be later marked as invalid.

DC_initMaster ()

int         DC_initMaster                   (const char *configFile);

Initializes the master side of the DC-API. This function must be called first before calling any other DC-API functions.

DC_setMasterCb ()

void        DC_setMasterCb                  (DC_ResultCallback resultcb,
                                             DC_SubresultCallback subresultcb,
                                             DC_MessageCallback msgcb);

Sets the callback functions to be used for event reporting. One or more of the callbacks may be NULL if the master does not wish to receive the specific event.

DC_processMasterEvents ()

int         DC_processMasterEvents          (int timeout);

Processes work unit events. In case of a work unit completes and its result is available, or if a message or a subresult has arrived, the appropriate callback functions will be called.

The received event will be automatically destroyed when the callback function returns (including the deletion of files if the event was a result or subresult). If the master application wants to access any information belonging to the event (e.g. the output files the client created), then the callback function must explicitely make a copy of any data it is interested in. In case of physical files (i.e., results and subresults), the callback is allowed to simply rename the files therefore preventing DC-API from deleting them.

DC_waitMasterEvent ()

DC_MasterEvent* DC_waitMasterEvent          (const char *wuFilter,
                                             int timeout);

Checks for events and returns them directly. This function does not invoke any event-processing callbacks.

DC_waitWUEvent ()

DC_MasterEvent* DC_waitWUEvent              (DC_Workunit *wu,
                                             int timeout);

Checks for events for a particular work unit. This function does not invoke any event-processing callbacks.

DC_destroyMasterEvent ()

void        DC_destroyMasterEvent           (DC_MasterEvent *event);

Destroys a DC_MasterEvent obtained by calling DC_waitMasterEvent() or DC_waitWUEvent().

DC_getWUNumber ()

int         DC_getWUNumber                  (DC_WUState state);

Returns the number of existing work units having the specified state.

DC_createWU ()

DC_Workunit* DC_createWU                    (const char *clientName,
                                             const char *arguments[],
                                             int subresults,
                                             const char *tag);

Creates a new work unit. The work unit is not known to the underlying grid infrastructure until DC_submitWU() is called. The returned work unit is in the DC_WU_READY state.

DC_addWUInput ()

int         DC_addWUInput                   (DC_Workunit *wu,
                                             const char *logicalFileName,
                                             const char *URL,
                                             DC_FileMode fileMode);

Adds an input file to a work unit. This function may be called only for work units in state DC_WU_READY (i.e., before the work unit is submitted).

DC_addWUOutput ()

int         DC_addWUOutput                  (DC_Workunit *wu,
                                             const char *logicalFileName);

Adds an output file specification to a work unit. Files registered using this function will be transferred back to the master when the client finishes. This function may be called only for work units in state DC_WU_READY (i.e., before the work unit is submitted).

DC_setWUPriority ()

int         DC_setWUPriority                (DC_Workunit *wu,
                                             int priority);

Sets the priority of a work unit. Depending on the underlying grid infrastructure, this function may be called only for work units in state DC_WU_READY (i.e., before the work unit is submitted). The priority value may be in the range 1-100, higher number meaning more important work unit. The default priority is 50. Note that not all infrastructures support priorities and the number of supported levels may be fewer than 100.

DC_serializeWU ()

char*       DC_serializeWU                  (DC_Workunit *wu);

Serializes a DC_Workunit structure. The returned string may be stored on persistent storage and can be used to re-create the work unit description in a different process. The format of the returned string is not specified, the only guarantee DC-API gives is that it will not contain newline characters.

DC_deserializeWU ()

DC_Workunit* DC_deserializeWU               (const char *buf);

Restores a serialized work unit. May be called from a different process than the work unit was serialized in.

DC_getWUState ()

DC_WUState  DC_getWUState                   (DC_Workunit *wu);

Queries the state of a work unit.

DC_submitWU ()

int         DC_submitWU                     (DC_Workunit *wu);

Submits a work unit to the grid infrastructure. It is up to the infrastructure when the work unit actually begins execution.

DC_getWUId ()

char*       DC_getWUId                      (const DC_Workunit *wu);

Returns the infrastructure-specific low-level ID of the work unit. This identifier should appear in infrastructure-level log files and can be used to track the job if a problem with the grid infrastructure is suspected.

DC_getWUTag ()

char*       DC_getWUTag                     (const DC_Workunit *wu);

Returns the user-specified tag of a work unit.

DC_cancelWU ()

int         DC_cancelWU                     (DC_Workunit *wu);

Cancels all computation for a given work unit.

DC_suspendWU ()

int         DC_suspendWU                    (DC_Workunit *wu);

Suspends the execution of a work unit. If the client is running, it is instructed to perform a checkpoint; the checkpoint image is then transferred back to the master so it can be restarted later using DC_resumeWU().

DC_resumeWU ()

int         DC_resumeWU                     (DC_Workunit *wu);

Resumes the computation of a work unit that was previously suspended using DC_suspendWU().

DC_destroyWU ()

void        DC_destroyWU                    (DC_Workunit *wu);

Destroys a work unit. All input and output files belonging to the work unit will be deleted, and any internal resources allocated to the work unit will be de-allocated. If the work unit is still running, it will be cancelled.

DC_sendWUMessage ()

int         DC_sendWUMessage                (DC_Workunit *wu,
                                             const char *message);

Sends a message to a running work unit. The message is sent asynchronously and this function does not wait for the message to be delivered. Delivery of the message will happen only when the client explicitely checks for it which can take an arbitrary long time, depending on the infrastructure and on the client implementation. The maximum allowed length of messages can be determined with the DC_getMaxMessageSize() function.

DC_getClientCfgStr ()

char*       DC_getClientCfgStr              (const char *clientName,
                                             const char *key,
                                             int fallbackGlobal);

Returns the value belonging to the specified key key for the specific client application clientName in the configuration file.

DC_getClientCfgInt ()

int         DC_getClientCfgInt              (const char *clientName,
                                             const char *key,
                                             int defaultValue,
                                             int fallbackGlobal);

Returns the integer value belonging to the specified key key for the specific client application clientName in the configuration file. Unit suffixes like 'KB', 'GB' or 'hour' are also allowed.

DC_getClientCfgDouble ()

double      DC_getClientCfgDouble           (const char *clientName,
                                             const char *key,
                                             double defaultValue,
                                             int fallbackGlobal);

Returns the double precision floating point value belonging to the specified key key for the specific client application clientName in the configuration file. Unit suffixes like 'KB', 'GB' or 'hour' are also allowed.

DC_getClientCfgBool ()

int         DC_getClientCfgBool             (const char *clientName,
                                             const char *key,
                                             int defaultValue,
                                             int fallbackGlobal);

Returns the boolean value belonging to the specified key key for the specific client application clientName in the configuration file.

DC_getResultCapabilities ()

unsigned    DC_getResultCapabilities        (const DC_Result *result);

Determines what kind of information is present in the received result.

DC_getResultWU ()

DC_Workunit* DC_getResultWU                 (DC_Result *result);

Returns the work unit that generated this result.

DC_getResultExit ()

int         DC_getResultExit                (const DC_Result *result);

Returns the exit code of the client application.

DC_getResultOutput ()

char*       DC_getResultOutput              (const DC_Result *result,
                                             const char *logicalFileName);

Returns the real path name for a logical output file name.