Grid Application Toolkit A simple API for Grid Applications

Menu Home API-Specification API-Overview Status C Reference Manual Download Java Java-Reference General GridLab - WP-1 Links

job.c Go to the documentation of this file. /** @file job.c * Source file for the sample Job CPI provider. * * @date Sat Oct 25 2003 * * @version $Header: /export/cvs-gridlab/wp-1/Codes/GATEngine/C-reference/adaptors/resourcebroker/job.c,v 1.12 2004/04/26 15:45:00 hartmutkaiser Exp $ * * Copyright (C) Hartmut Kaiser * This file is part of the GAT Engine. * Contributed by Hartmut Kaiser <hartm utkaiser [at] t-online [dot] de>. * * Use, modification and distribution is subject to the Gridlab Software * License. (See accompanying file GLlicense.txt or copy at * http://www.gridlab.org/GLlicense.txt) */ static const char *rcsid = "$Header: /export/cvs-gridlab/wp-1/Codes/GATEngine/C-reference/adaptors/resourcebroker/job.c,v 1.12 2004/04/26 15:45:00 hartmutkaiser Exp $"; /* System Header Files */ #include <stdio.h> #include <stdlib.h> #include <string.h> /* GAT Header Files */ #include "GATCPI.h" #include "GATJobCPIInstanceData.h" /* Macros */ #define __countof(x) (sizeof(x)/sizeof(x[0])) /* Structures, unions and enums */ /* Static function prototypes */ static void resourcebroker_adaptor_GATJobCPI_Destroy(void *data); /* instance specific functions */ static GATResult resourcebroker_adaptor_GATJobCPI_ServiceActions(void *data, GATJobCPI_Instance *instance_data, GATTimePeriod_const timeout /* = 0 */); static GATResult resourcebroker_adaptor_GATJobCPI_CreateInstance( void *data, GATJobCPI_Instance *instance_data, void *initialisation_data); static void resourcebroker_adaptor_GATJobCPI_DestroyInstance( void *data, GATJobCPI_Instance *instance_data); static GATResult resourcebroker_adaptor_GATJobCPI_CloneInstance( void *data, GATJobCPI_Instance const *instance_data, GATJobCPI_Instance *new_instance_data); static GATResult resourcebroker_adaptor_GATJobCPI_EqualsInstance( void *data, GATJobCPI_Instance const *lhs, GATJobCPI_Instance const *rhs, GATBool *isequal); /* Monitoring support */ static GATResult resourcebroker_adaptor_GATJobCPI_GetMetrics( void *data, GATJobCPI_Instance const *instance_data, GATList_GATMetric *metrics); static GATResult resourcebroker_adaptor_GATJobCPI_GetMetricEvent( void *data, GATJobCPI_Instance const *instance_data, GATMetric metric, GATMetricEvent *event); /* Serialisation support */ static GATResult resourcebroker_adaptor_GATJobCPI_Serialise( void *data, GATJobCPI_Instance const *instance_data, GATObject stream, GATBool clear_dirty); static GATResult resourcebroker_adaptor_GATJobCPI_DeSerialise( void *data, GATObject stream, GATJobCPI_Instance *instance_data); /* CPI API functionality */ static GATResult resourcebroker_adaptor_GATJobCPI_UnSchedule(void *data, GATJobCPI_Instance const *instance_data); static GATResult resourcebroker_adaptor_GATJobCPI_Checkpoint(void *data, GATJobCPI_Instance const *instance_data); static GATResult resourcebroker_adaptor_GATJobCPI_CloneJob(void *data, GATJobCPI_Instance const *instance_data, GATHardwareResource_const hr, GATJob *cloned_job); static GATResult resourcebroker_adaptor_GATJobCPI_Migrate(void *data, GATJobCPI_Instance const *instance_data, GATHardwareResource_const hr, GATJob *migrated_job); static GATResult resourcebroker_adaptor_GATJobCPI_Stop(void *data, GATJobCPI_Instance const *instance_data); static GATResult resourcebroker_adaptor_GATJobCPI_GetJobDescription(void *data, GATJobCPI_Instance const *instance_data, GATJobDescription_const *jd); static GATResult resourcebroker_adaptor_GATJobCPI_GetInfo(void *data, GATJobCPI_Instance const *instance_data, GATTable_const *jobinfo); static GATResult resourcebroker_adaptor_GATJobCPI_GetJobID(void *data, GATJobCPI_Instance const *instance_data, GATJobID_const *jobid); static GATResult resourcebroker_adaptor_GATJobCPI_GetStatus(void *data, GATJobCPI_Instance const *instance_data, GATStatus_const *jobstatus); /* File scope variables */ /* supported metrics */ static GATStaticMetric metric_data[] = { /* job.status_changed event */ { "job.status_changed", /* name */ GATMeasurementType_EventLike, /* type */ GATType_GATuint32, /* data type (actually a GATJobState) */ "", /* unit */ 0, /* parameter count */ 0 /* parameters */ }, }; /* symbolic constants for the metric positions inside the metric_data array */ #define METRIC_STATUS_CHANGED 0 /* External functions */ /* Register the CPI to implement */ GATResult resourcebroker_adaptor_Register_GATJobCPI( GATContext error_context, GATRegistry registry, GATTable_const system_config, GATTable_const instance_config, void *token) { GAT_USES_STATUS(error_context, "resourcebroker_adaptor_Register_GATJobCPI"); GATJobCPI cpi = NULL; GATJobCPI_Data cpidata; { memset(&cpidata, 0, sizeof(GATJobCPI_Data)); /* * provide the appropriate callback functions */ cpidata.data = NULL; /* no adaptor instance data */ cpidata.destroy = resourcebroker_adaptor_GATJobCPI_Destroy; /* instance data handling */ cpidata.service_actions = resourcebroker_adaptor_GATJobCPI_ServiceActions; cpidata.create_instance = resourcebroker_adaptor_GATJobCPI_CreateInstance; cpidata.destroy_instance = resourcebroker_adaptor_GATJobCPI_DestroyInstance; cpidata.clone_instance = resourcebroker_adaptor_GATJobCPI_CloneInstance; cpidata.equals_instance = resourcebroker_adaptor_GATJobCPI_EqualsInstance; /* monitoring support functions */ cpidata.get_metrics = resourcebroker_adaptor_GATJobCPI_GetMetrics; cpidata.get_metric_event = resourcebroker_adaptor_GATJobCPI_GetMetricEvent; /* serialisation support functions */ cpidata.serialise = resourcebroker_adaptor_GATJobCPI_Serialise; cpidata.deserialise = resourcebroker_adaptor_GATJobCPI_DeSerialise; /* CPI specific API functions */ cpidata.unschedule = resourcebroker_adaptor_GATJobCPI_UnSchedule; cpidata.checkpoint = resourcebroker_adaptor_GATJobCPI_Checkpoint; cpidata.clonejob = resourcebroker_adaptor_GATJobCPI_CloneJob; cpidata.migratejob = resourcebroker_adaptor_GATJobCPI_Migrate; cpidata.stopjob = resourcebroker_adaptor_GATJobCPI_Stop; cpidata.get_jobdescription = resourcebroker_adaptor_GATJobCPI_GetJobDescription; cpidata.get_jobinfo = resourcebroker_adaptor_GATJobCPI_GetInfo; cpidata.get_jobid = resourcebroker_adaptor_GATJobCPI_GetJobID; cpidata.get_status = resourcebroker_adaptor_GATJobCPI_GetStatus; /* Create a GATJobCPI object. */ cpi = GATJobCPI_Create(GATJOBCPI_VERSION, &cpidata); if(NULL != cpi) { /* Need to pass preferences to allow matching * of a user's preferences with what this adaptor does. */ GATPreferences preferences = GATPreferences_Create(); if(NULL != preferences) { GAT_CREATE_STATUS(GATPreferences_Add(preferences, "Name", "resourcebroker_adaptor")); GAT_CREATE_STATUS(GATPreferences_Add(preferences, "Security", "none")); GAT_CREATE_STATUS(GATPreferences_Add(preferences, "Local", "true")); GAT_CREATE_STATUS(GATRegistry_AddGATJobCPI(registry, cpi, token, preferences)); GATPreferences_Destroy(&preferences); } } } if (GAT_FAILED(GAT_CURRENT_STATUS())) { GATJobCPI_Destroy(&cpi); } return GAT_RETURN_STATUS(); } /* Local functions */ static void resourcebroker_adaptor_GATJobCPI_Destroy(void *data) { /* nothing to do here (no internal data allocated) */ assert(NULL == data); } /* instance specific functions */ /** resourcebroker_adaptor_GATJobCPI_ServiceActions * * The function resourcebroker_adaptor_GATJobCPI_ServiceActions is called, whenever * the client calls GATContext_ServiceActions. This function is called for * every created object. * This function should be used to update all instance specific data, which * may have been changed asynchronously or to fire pending events. * * @param data Adaptor-provided data object. * @param instance_data The instance data of this CPI object * @param timeout This may be a 0 timeout to indicate no timeout at all, or * a specific time length. * * @return An error code. */ static GATResult resourcebroker_adaptor_GATJobCPI_ServiceActions(void *data, GATJobCPI_Instance *instance_data, GATTimePeriod_const timeout) { return GAT_NOTIMPL; } /** resourcebroker_adaptor_GATJobCPI_CreateInstance * Create a new CPI object instance. * Adaptor implementation of create instance capability. * * @param data Adaptor-provided data object. * @param context The GATContext for this CPI instance * @param target The location of the file in question. * @param new_instance_data The pointer to the variable, where the instance * data of this CPI object is to be returned to. * * @return An error code. */ static GATResult resourcebroker_adaptor_GATJobCPI_CreateInstance(void *data, GATJobCPI_Instance *new_instance_data, void *initialisation_data) { GAT_USES_STATUS(new_instance_data->context, "resourcebroker_adaptor_GATJobCPI_CreateInstance"); if (NULL != new_instance_data) { GAT_CREATE_STATUS(GATJobCPIInstance_Data_Clone( (GATJobCPIInstance_Data *) initialisation_data, (GATJobCPIInstance_Data **) &new_instance_data->instance_data)); } return GAT_RETURN_STATUS(); } /** resourcebroker_adaptor_GATJobCPI_DestroyInstance * Destroy a CPI object instance. * Adaptor implementation of destroy instance capability. * * @param data Adaptor-provided data object. * @param instance_data The instance data of the CPI object to destroy. */ static void resourcebroker_adaptor_GATJobCPI_DestroyInstance(void *data, GATJobCPI_Instance *instance_data) { GATJobCPIInstance_Data_Destroy( (GATJobCPIInstance_Data **) &instance_data->instance_data); } /** resourcebroker_adaptor_GATJobCPI_CloneInstance * Clone a CPI object instance. * Adaptor implementation of the clone instance capability. * * @param data Adaptor-provided data object. * @param instance_data The instance data of this CPI object * @param new_instance_data The pointer to the variable, where the instance * data of the cloned CPI object is to be returned to. * * @return An error code. */ static GATResult resourcebroker_adaptor_GATJobCPI_CloneInstance( void *data, GATJobCPI_Instance const *instance_data, GATJobCPI_Instance *new_instance_data) { GAT_USES_STATUS(instance_data->context, "resourcebroker_adaptor_GATJobCPI_CloneInstance"); if (NULL != instance_data && NULL != new_instance_data) { GAT_CREATE_STATUS(GATJobCPIInstance_Data_Clone( (GATJobCPIInstance_Data *) instance_data->instance_data, (GATJobCPIInstance_Data **) &new_instance_data->instance_data)); } else { GAT_CREATE_STATUS(GAT_INVALID_PARAMETER); } return GAT_RETURN_STATUS(); } /** resourcebroker_adaptor_GATJobCPI_EqualsInstance * Clone a CPI object instance. * Adaptor implementation of the clone instance capability. * * @param data Adaptor-provided data object. * @param lhs The instance data of the left CPI object. * @param lhs The instance data of the right CPI object. * @param isequal The pointer to the variable, where the result is to be * returned to. * * @return An error code. */ static GATResult resourcebroker_adaptor_GATJobCPI_EqualsInstance( void *data, GATJobCPI_Instance const *lhs, GATJobCPI_Instance const *rhs, GATBool *isequal) { GAT_USES_STATUS(lhs->context, "resourcebroker_adaptor_GATResourceCPI_CloneInstance"); if (NULL != lhs && NULL != rhs) { GAT_CREATE_STATUS(GATJobCPIInstance_Data_Equals( (GATJobCPIInstance_Data *) lhs->instance_data, (GATJobCPIInstance_Data *) rhs->instance_data, isequal)); } else { GAT_CREATE_STATUS(GAT_INVALID_HANDLE); } return GAT_RETURN_STATUS(); } /* Monitoring support */ /** resourcebroker_adaptor_GATJobCPI_GetMetrics * * The function resourcebroker_adaptor_GATJobCPI_GetMetrics should return a * list of GATMetric objects supported by this adaptor. I.e. the adaptor is * capable to fire GATMetricEvents for the returned metrics. This list should * include all the supported metrics, event like and continuous ones. * * @param data Adaptor-provided data object. * @param instance_data Instance data for the CPI provider object. * @param metrics The pointer to the variable, which receives the returned * list of metrics. * * @return An error code. */ static GATResult resourcebroker_adaptor_GATJobCPI_GetMetrics(void *data, GATJobCPI_Instance const *instance_data, GATList_GATMetric *metrics) { return GATMetric_CreateListOfMetrics(metric_data, __countof(metric_data), metrics); } /** resourcebroker_adaptor_GATJobCPI_GetMetricEvent * * The function resourcebroker_adaptor_GATJobCPI_GetMetricEvent should * return the GATMetricEvent associated with the given continuous metric. This * function gets called for continuous metrics only, since returning the * metric event object to the caller is th only way for the client to get * access to it. * * @param data Adaptor-provided data object. * @param instance_data Instance data for the CPI provider object. * @param metric The metric instance describing the metric event to return. * This metric should be equivalent to one of the metrics returned by * our own GetMetrics CPI function (see above). If this is another * (not known to us metric), an error should be returned. * @param event The pointer to the variable, which receives the metric event * to return. * * @return An error code. */ static GATResult resourcebroker_adaptor_GATJobCPI_GetMetricEvent(void *data, GATJobCPI_Instance const *instance_data, GATMetric metric, GATMetricEvent *event) { return GAT_NOTIMPL; } /* Serialisation support */ /** resourcebroker_adaptor_GATJobCPI_Serialise * * The function resourcebroker_adaptor_GATJobCPI_Serialise is called by the * GAT engine, whenever the client requested a Serialise operation on the * corresponding object. The function should serialise into the given stream * all the instance specific data of the object. * * @param data Adaptor-provided data object. * @param instance_data The instance data of this CPI object. * @param stream The GATSTream object to use for serialisation of the instance * data. * @param clear_dirty If the clear_dirty parameter is set to GATTrue, the * internal dirty flag of this object is to be reset. * * @return An error code */ static GATResult resourcebroker_adaptor_GATJobCPI_Serialise(void *data, GATJobCPI_Instance const *instance_data, GATObject stream, GATBool clear_dirty) { GAT_USES_STATUS(instance_data->context, "resourcebroker_adaptor_GATJobCPI_Serialise"); GAT_CREATE_STATUS(GATJobCPIInstance_Data_Serialize( (GATJobCPIInstance_Data const *) instance_data->instance_data, stream, clear_dirty)); return GAT_RETURN_STATUS(); } /** resourcebroker_adaptor_GATJobCPI_DeSerialise * * The function resourcebroker_adaptor_GATJobCPI_DeSerialise is called by * the GATEngine, whenever the client requested a DeSerialise operation for * a corresponding object. The function should deserialise all the instance * specific data of the object from the given stream. * * @param data Adaptor-provided data object. * @param stream The GATSTream object to use for de-serialisation of the * instance data. * @param instance_data The instance data of this CPI object. * * @return An error code */ static GATResult resourcebroker_adaptor_GATJobCPI_DeSerialise(void *data, GATObject stream, GATJobCPI_Instance *instance_data) { GAT_USES_STATUS(instance_data->context, "resourcebroker_adaptor_GATJobCPI_DeSerialise"); GAT_CREATE_STATUS(GATJobCPIInstance_Data_DeSerialize( instance_data->context, stream, (GATJobCPIInstance_Data **) &instance_data->instance_data)); return GAT_RETURN_STATUS(); } /* CPI specific API functions */ /** resourcebroker_adaptor_GATJobCPI_UnSchedule * * The function resourcebroker_adaptor_GATJobCPI_UnSchedule guarantees that * the GATJob corresponding to this GATJobCPI is not scheduled to a job queue, * its state is GAT Initial. This operation can only be called * on a GATJob in the GAT Scheduled state, otherwise an error will is issued. * * @param data Adaptor-provided data object. * @param instance_data The instance data of this CPI object. * * @return An error code. */ static GATResult resourcebroker_adaptor_GATJobCPI_UnSchedule(void *data, GATJobCPI_Instance const *instance_data) { return GAT_NOTIMPL; } /** resourcebroker_adaptor_GATJobCPI_Checkpoint * * The function resourcebroker_adaptor_GATJobCPI_Checkpoint triggers a * checkpoint operation for the given GATJob. The call can only succeed on * processes which support application level checkpointing, or on resources * which provide system level checkpointing. * The call returns immediately after delivering the checkpointing request to * the job or to the resource the job is running on; the actual checkpoint * may happen some time after this return. * * @param data Adaptor-provided data object. * @param instance_data The instance data of this CPI object. * * @return An error code. */ static GATResult resourcebroker_adaptor_GATJobCPI_Checkpoint(void *data, GATJobCPI_Instance const *instance_data) { return GAT_NOTIMPL; } /** resourcebroker_adaptor_GATJobCPI_CloneJob * * The function resourcebroker_adaptor_GATJobCPI_CloneJob creates a copy of * the GATJob. The resulting GATJob has the same GATSoftwareDescription in its * GATJobDescription, but the GATResourceDescriptions or GATResources of its * GATJobDescription may be altered. * * @param data Adaptor-provided data object. * @param instance_data The instance data of this CPI object. * @param hr (optional) The GATHardwareResource to use to schedule the clones * job. If this parameter is not given (zero) the GATHardwareResource is * used, which was used to create the current GATJob. * @param cloned_job The pointer to a variable receiving the cloned job object. * * @return An error code. */ static GATResult resourcebroker_adaptor_GATJobCPI_CloneJob(void *data, GATJobCPI_Instance const *instance_data, GATHardwareResource_const hr, GATJob *cloned_job) { return GAT_NOTIMPL; } /** resourcebroker_adaptor_GATJobCPI_Migrate * * The function resourcebroker_adaptor_GATJobCPI_Migrate provides similar * functionality as the resourcebroker_adaptor_GATJobCPI_CloneJob operation. * The only difference is that the calling GATJob instance is discontinued * after the new job is spawned off successfully — its state is * #GATJobState_Stopped then. * * @param data Adaptor-provided data object. * @param instance_data The instance data of this CPI object. * @param hr (optional) The GATHardwareResource to use to schedule the clones * job. If this parameter is not given (zero) the GATHardwareResource is * used, which was used to create the current GATJob. * @param migrated_job The pointer to a variable receiving the cloned job * object. * * @return An error code. */ static GATResult resourcebroker_adaptor_GATJobCPI_Migrate(void *data, GATJobCPI_Instance const *instance_data, GATHardwareResource_const hr, GATJob *migrated_job) { return GAT_NOTIMPL; } /** resourcebroker_adaptor_GATJobCPI_Stop * * The function resourcebroker_adaptor_GATJobCPI_Stop stops the GATJob. Upon a * successful call to this operation, the processes associated with the GATJob * are forcibly terminated. This operation can only be called on a GATJob in * the #GATJobState_Running state. * * @param data Adaptor-provided data object. * @param instance_data The instance data of this CPI object. * * @return An error code. */ static GATResult resourcebroker_adaptor_GATJobCPI_Stop(void *data, GATJobCPI_Instance const *instance_data) { return GAT_NOTIMPL; } /** resourcebroker_adaptor_GATJobCPI_GetJobDescription * * The function resourcebroker_adaptor_GATJobCPI_GetJobDescription returns the * GATJobDescription instance used to create that GATJob instance. * * @param data Adaptor-provided data object. * @param instance_data The instance data of this CPI object. * @param jd The pointer to a variable, which should receive the associated * job description. * * @return An error code. */ static GATResult resourcebroker_adaptor_GATJobCPI_GetJobDescription(void *data, GATJobCPI_Instance const *instance_data, GATJobDescription_const *jd) { GAT_USES_STATUS(instance_data->context, "resourcebroker_adaptor_GATJobCPI_GetJobDescription"); if (NULL != jd) { *jd = ((GATJobCPIInstance_Data *)instance_data->instance_data)->description; } else { GAT_CREATE_STATUS(GAT_INVALID_PARAMETER); } return GAT_RETURN_STATUS(); } /** resourcebroker_adaptor_GATJobCPI_GetInfo * * The function resourcebroker_adaptor_GATJobCPI_GetInfo returns an instance * of the class GATTable, which contains the essential information about the * GATJob object, such as the host name, the schedule time, the start time, * the stop time, whether the GATJob is checkpointable etc. * * @param data Adaptor-provided data object. * @param instance_data The instance data of this CPI object. * @param jobinfo The pointer to a variable, which should receive the returned * GATTable containing the job information. * * @return An error code. */ static GATResult resourcebroker_adaptor_GATJobCPI_GetInfo(void *data, GATJobCPI_Instance const *instance_data, GATTable_const *jobinfo) { GAT_USES_STATUS(instance_data->context, "resourcebroker_adaptor_GATJobCPI_GetInfo"); if (NULL != jobinfo) { *jobinfo = ((GATJobCPIInstance_Data *)instance_data->instance_data)->parameters; } else { GAT_CREATE_STATUS(GAT_INVALID_PARAMETER); } return GAT_RETURN_STATUS(); } /** resourcebroker_adaptor_GATJobCPI_GetJobID * * The function resourcebroker_adaptor_GATJobCPI_GetJobID returns the job id, * a globally unique identifier for the represented process corresponding to * this instance. This operation SHOULD be called on a GATJob instance only * when the instance is in a GAT Running or GAT Scheduled state, otherwise * an error will be issued. * * @param data Adaptor-provided data object. * @param instance_data The instance data of this CPI object. * @param jobid The pointer to a variable, which should receive the resulting * job id. * * @return An error code. */ static GATResult resourcebroker_adaptor_GATJobCPI_GetJobID(void *data, GATJobCPI_Instance const *instance_data, GATJobID_const *jobid) { GAT_USES_STATUS(instance_data->context, "resourcebroker_adaptor_GATJobCPI_GetJobID"); if (NULL != jobid) { *jobid = instance_data->jobid; } else { GAT_CREATE_STATUS(GAT_INVALID_PARAMETER); } return GAT_RETURN_STATUS(); } /** resourcebroker_adaptor_GATJobCPI_GetStatus * * The function resourcebroker_adaptor_GATJobCPI_GetStatus SHOULD provide a * GATStatus instance which gives further information as to the cause of the * error, if the job is in the GAT SubmissionError state. * * @param data Adaptor-provided data object. * @param instance_data The instance data of this CPI object. * @param status The variable, which should receive the associated GATStatus * object. * * @return An error code. */ static GATResult resourcebroker_adaptor_GATJobCPI_GetStatus(void *data, GATJobCPI_Instance const *instance_data, GATStatus_const *jobstatus) { GAT_USES_STATUS(instance_data->context, "resourcebroker_adaptor_GATJobCPI_GetStatus"); if (NULL != jobstatus) { *jobstatus = ((GATJobCPIInstance_Data *)instance_data->instance_data)->status; } else { GAT_CREATE_STATUS(GAT_INVALID_PARAMETER); } return GAT_RETURN_STATUS(); }