Client

Client — functionality specific to the client-side of DC-API.

Synopsis


#include <dc_client.h>


enum        DC_FileType;
#define     DC_CHECKPOINT_FILE
enum        DC_ClientEventType;
            DC_ClientEvent;

int         DC_initClient                   (void);
char*       DC_resolveFileName              (DC_FileType type,
                                             const char *logicalFileName);
int         DC_sendResult                   (const char *logicalFileName,
                                             const char *path,
                                             DC_FileMode fileMode);
int         DC_sendMessage                  (const char *message);
DC_ClientEvent* DC_checkClientEvent         (void);
void        DC_destroyClientEvent           (DC_ClientEvent *event);
void        DC_checkpointMade               (const char *fileName);
void        DC_fractionDone                 (double fraction);
void        DC_finishClient                 (int exitcode);

Description

This section describes the functions and definitions available for DC-API applications on the client side.

Details

enum DC_FileType

typedef enum {
	DC_FILE_IN,
	DC_FILE_OUT,
	DC_FILE_TMP
} DC_FileType;

File types for the DC_resolveFileName() function. Some grid infrastructures use different locations for storing files of different usage, therefore DC-API needs to know the expected usage of logical files to be able to determine the correct physical location.

`DC_FILE_IN`	the file is an input file.
`DC_FILE_OUT`	the file is an output file.
`DC_FILE_TMP`	the file is a temporary file that will not sent back to the master.

DC_CHECKPOINT_FILE

#define DC_CHECKPOINT_FILE	"__DC_CHECKPOINT_"

Logical name of the application-level checkpoint file. See DC_resolveFileName() for details about checkpoint file usage.

enum DC_ClientEventType

typedef enum {
	DC_CLIENT_CHECKPOINT,	/* Checkpointing is requested */
	DC_CLIENT_FINISH,	/* Computation should be aborted */
	DC_CLIENT_MESSAGE	/* A message has arrived */
} DC_ClientEventType;

ClientEvent types that can be received.

`DC_CLIENT_CHECKPOINT`	a checkpoint should be made. The application must call `DC_checkpointMade()` to acknowledge the request even if it does not support checkpointing (it should pass a `NULL` pointer as the file name in this case).
`DC_CLIENT_FINISH`	the computation should be aborted.
`DC_CLIENT_MESSAGE`	a message has arrived.

DC_ClientEvent

typedef struct {
	DC_ClientEventType	type;
	union
	{
		char		*message;
	};
} DC_ClientEvent;

ClientEvent received from the master.

DC_ClientEventType `type`;	type of the event.
char *`message`;	contents of the message if `type` is `DC_CLIENT_MESSAGE`.

DC_initClient ()

int         DC_initClient                   (void);

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

Returns :

0 if successful or a DC_ErrorCode.

DC_resolveFileName ()

char*       DC_resolveFileName              (DC_FileType type,
                                             const char *logicalFileName);

Resolves the local name of input/output files. The real name (and path) of an input/output file may be different from what the client expects. This function performs the translation from the logical names used by the client to the real names used by the infrastructure.

Note

The client must not assume that it can read/write/create any files other than the names returned by this function.

The handling of application-level checkpoint files is special. The intention is to never modify an already completed checkpoint file, so even if the client is interrupted in the middle of writing to the checkpoint file, the previous checkpoint is still intact and can be used to resume computation.

When logicalFileName is DC_CHECKPOINT_FILE, type is interpreted as follows:

If type is DC_FILE_IN, then the path name of the last completed checkpoint file (as indicated by the client by calling DC_checkpointMade() previously) is returned. The client must not modify this file in any way. If the client did not create any checkpoints so far but it was resumed from a previous checkpoint, then the path name of the original checkpoint file is returned. If there are no previous checkpoints at all, NULL is returned.
If type is DC_FILE_OUT, then a name for a new non-existant checkpoint file is returned. The client should write the checkpoint information to this file and should call DC_checkpointMade() with this file name to indicate that the checkpoint is complete. After calling DC_checkpointMade(), the client is not allowed to modify the checkpoint file in any way, and must call DC_resolveFileName() again to obtain a new name for a new checkpoint file.

When logicalFileName is not DC_CHECKPOINT_FILE, the following rules apply:

If type is DC_FILE_IN, then logicalFileName must be one of the names the master registered using DC_addWUInput() when the work unit was created.
If type is DC_FILE_OUT, then logicalFileName must be one of the names the master registered using DC_addWUOutput() when the work unit was created.
If type is DC_FILE_TMP, then logicalFileName must not match any registered input or output logical names.

`type` :	the tpe of the file.
`logicalFileName` :	the logical name of the file used by the client.
Returns :	the real path name of the file. The value should be deallocated using `free()` when it is no longer needed. `NULL` is returned if `type` is invalid or `logicalFileName` is not known to the infrastructure.

DC_sendResult ()

int         DC_sendResult                   (const char *logicalFileName,
                                             const char *path,
                                             DC_FileMode fileMode);

Sends a sub-result file back to the master. The sending of the file may happen asynchronously, in this case this function will not wait for the transfer to finish (or even to start).

`logicalFileName` :	the logical name of the file to send. This identifier will be received by the master.
`path` :	the local path name of the file to send.
`fileMode` :	tells how the file should be handled.
Returns :	0 if successful or a DC_ErrorCode.

DC_sendMessage ()

int         DC_sendMessage                  (const char *message);

Sends a message to the master. The sending of the message may happen asynchronously, in this case this function will not wait for the transfer to finish (or even to start). The maximum length of a message that may be sent using this function can be determined by calling DC_getMaxMessageSize().

`message` :	the message to send.
Returns :	0 if successful or a DC_ErrorCode.

DC_checkClientEvent ()

DC_ClientEvent* DC_checkClientEvent         (void);

Checks for client control events. The returned event should be destroyed using DC_destroyClientEvent() when it is no longer needed. If the returned event is DC_CLIENT_CHECKPOINT but the client does not support checkpointing, it should still call the DC_checkpointMade() function with a NULL argument to inform the grid infrastructure that no checkpoint will be delivered.

Returns : a DC_ClientEvent or NULL if there are no outstanding events.

DC_destroyClientEvent ()

void        DC_destroyClientEvent           (DC_ClientEvent *event);

Destroys an event returned by DC_checkClientEvent().

event : the event to destroy.

DC_checkpointMade ()

void        DC_checkpointMade               (const char *fileName);

Informs the DC-API that an application-level checkpoint has been made. See the DC_resolveFileName() for a description of checkpoint file handling.

fileName : the name of the checkpoint file. This should be a value returned by DC_resolveFileName(DC_FILE_OUT, DC_CHECKPOINT_FILE). The checkpoint file must not be modified after this function has been called. fileName can also be NULL meaning that the application does not in fact support checkpointing, but just acknowledges a DC_CLIENT_CHECKPOINT event.

DC_fractionDone ()

void        DC_fractionDone                 (double fraction);

Informs the controlling environment about the fraction of the work already done. Ideally this should be the CPU time used so far divided by the total CPU time that will be needed for the computation.

fraction : the fraction of the work completed.

DC_finishClient ()

void        DC_finishClient                 (int exitcode);

Finishes computation. Tells the DC-API to finish this work unit and start a new one. All output files are transferred to the master and the master is notified about the completion of the work unit.

exitcode : the return code of the process that will be reported back to the master. 0 means success; any other value tells the grid infrastructure that the work unit has failed.