boinc/dcapi/include/dc.h

/* API for Master-worker applications on Distributed Computing Platforms
   API for the Master program
   v0.2 Norbert Podhorszki
   MTA SZTAKI, 2004
*/

#ifndef __DC_H_
#define __DC_H_

#ifdef __cplusplus
extern "C" {
#endif

#include <sys/syslog.h>
#include <stdarg.h>
#include <dc_common.h>

typedef enum {
	DC_RESULT_FINAL,
	DC_RESULT_SUB
} DC_ResultStatus;

/** The first function to be invoked by the main application before using DC 
 *  
 *  Return:  DC_OK on success
 *              >1 on error   (MORE DETAILS NEEDED!)
 *
 *  Configuration file is not specified yet but it should contain some information
 *  about the DC platform to be used, the download and upload data servers,
 *  authentication staff etc.
 */
int DC_init(
   const char *project_name,         // name of the project, if NULL application_name is used
   const char *application_name,     // name of the application
   const char *configfile            // path+name of DC configuration file to be processed
);

/* Workunit.
 * It describes one work unit to be computed on a computing client.
 */
typedef int DC_Workunit;


/* Result
   It describes one result for one work unit.
   In redundant computing there are more than one results for one work unit.
*/

#define MAX_OUTFILES 4
typedef struct {
    char *name;				// unique string ID of the Result
    DC_Workunit wu;			// workunit index in the WUtable
    DC_ResultStatus status;		// status of the workunit
    int exitcode;			// the exit code of the client program

    char *outfiles_dir;			// directory of output files
    char *outfiles[MAX_OUTFILES];	// output files
    int  noutfiles;			// number of output files

    /* clgr-specific fields */
    char *std_out;
    char *std_err;
    char *sys_log;
} dc_result;

/* Result.
 * It describes one result for one work unit.
 */
typedef dc_result* DC_Result;


/** Create one work unit
 *  Lets DC create a workunit. 
 *  Several functions should be called to set the parameters:
 *     - DC_setInput      to assign input data
 *     - DC_setPriority   to set priority
 *  It should be submitted after that.
 *
 *  Parameters:
 *      application Application client name
 *      arguments   Command line argument for the client
 *
 *  Return: DC_Workunit type.  This is the number of the WU.
 * 	    The functions bellow will need this DC_Workunit.
 *	    If the value of this DC_Workunit is minus, it means ERROR!
 * 	    If it is 0 or higher, its OK!
 */
DC_Workunit DC_createWU (const char *application_client,
		 const char *arguments);

/** Specify an input file for the work unit.
 *  Parameters:
 *  URL is either
 *     - a path to a file in master's file system or
 *     - an URL to a downloadable file 
 *  The input file will be renamed to 'localFileName' on the client node.
 *  I.e. client should use 'localFileName' to open the file 
 *  (or it should get the name as command line argument
 *
 *  Return: DC_OK
 */

int DC_setInput (DC_Workunit wu, char * URL, char * localFileName);


/** Set the priority for the work unit.
 *  The priority should be less or equal than the priority of the application.
 *
 *  Return: DC_OK
 */
int DC_setPriority (DC_Workunit wu, int priority);


/** Submit work unit
 *  Lets DC to submit a workunit to a client machine.
 *  Return:  DC_OK on submission success 
 *              >1 on error
 */
int DC_submitWU (DC_Workunit wu);

/** Cancel all computations for a given work unit.
 *  All files will be deleted.
 *  Return: DC_OK 
 */
int DC_cancelWU (DC_Workunit wu);

/** DC_suspend.
 *  It cancels the running of the given work unit.
 *  It is not deleted from the hdd, or from the memmory,
 *  only from the execution system.
 *
 *  return: DC_OK
 *
 *  Comment: This has no meaning on BOINC, so nothing will happen with the
 *           running client, but you will not get back the results even if
 *           the wu is finished.
 *           Even this feature is not implemented yet.
 */
int DC_suspendWU(DC_Workunit wu);

/** DC_resubmit.
 *  It restarts the given, suspended work unit.
 *
 *  return: DC_OK;
 *
 *  Comment: In BOINC based implementation, nothing happens to the client
 *           but from now on you can get back the results.
 *           Even this feature is not implemented yet.
 */
int DC_resubmitWU(DC_Workunit wu);

/** Destroy allocated memory for a given work unit.
 *  Return:  DC_OK on success
 *              >1 on error
 */
int DC_destroyWU(DC_Workunit wu);


/** Check for results.
 *  Waits for available results and returns the first.
 *  Return:  DC_OK on success
 *              >1 on error
 *  Parameters:
 *     timeout    function blocks and waits until a result becomes available 
 *                but returns after the specified timeout (seconds).
 *                timeout = 0 means: waiting forever.
 *                timeout < 0 means: single check only, no blocking 
 *     func1      callback function for checking (accepting) a result
 *     func2      callback function for assimilating result within the application
 */
int DC_checkForResult(int  timeout,
		      void (*cb_assimilate_result)(DC_Result result)
		      );

/* Callback functions
   These functions should be provided by the application.

   Parameters:
     result     Result, memory allocated by the function using malloc.
                It will be deallocated automatically after the return 
                from assimilation.

   int cb_check_result(DC_Result result)

       Checking the result when it is available.
       Return DC_RESULT_ACCEPT  if result is accepted
              DC_RESULT_INVALID if result is invalid


   void cb_assimilate_result(DC_Result result)

       Assimilate the result within the application.
       On return, the result will be deleted within DC.

*/

/** Logging function, like printf
 *  In configfile (given at DC_Init()), you can define to which level logging information
 *  will be printed, and also, to which file it should be printed:
 *  LogLevel = Debug (or Error, Warning, Notice, Info, Debug)
 *  LogFile  = dsp.log
 *
 *  Logging levels: LOG_ERR, LOG_WARNING, LOG_NOTICE, LOG_INFO, LOG_DEBUG
 */
void DC_log(int level, const char *fmt, ...)
	__attribute__((format(printf, 2, 3)));
void DC_vlog(int level, const char *fmt, va_list args)
	__attribute__((format(printf, 2, 0)));

#ifdef __cplusplus
}
#endif

#endif /* __DC_H_ */