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

GATJob.c Go to the documentation of this file. /** @file GATJob.c * Source file for the GATJob class. * * A GATJob represents one or more processes which are running or may be * submitted to a resource management system, e.g. by a globusrun command. * * @date Thu Oct 23 2003 * * @version $Header: /export/cvs-gridlab/wp-1/Codes/GATEngine/C-reference/src/GATJob.c,v 1.24 2004/05/12 18:56:00 hartmutkaiser Exp $ * * Copyright (C) Hartmut Kaiser * This file is part of the GAT Engine. * Contributed by Hartmut Kaiser <hartmutkaiser [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/src/GATJob.c,v 1.24 2004/05/12 18:56:00 hartmutkaiser Exp $"; /* System Header objects */ #include <stdlib.h> #include <string.h> #include <assert.h> /* GAT Header objects */ #include "GAT.h" #include "GATInternal.h" #include "GATRegistry.h" #include "GATJobCPI.h" #include "GATXdsWrapper.h" #include "GATMetricEvent.h" /* define the vtable types */ GATOBJECT_DEFINE_VTABLE(GATJob); GATSERIALISABLE_DEFINE_VTABLE(GATJob); GATMONITORABLE_DEFINE_VTABLE(GATJob); /* define the converters to/from GATObject */ GATOBJECT_DEFINE_CONVERTERS(GATJob) /* Macros */ /* Structures, unions and enums */ struct GATJob_S { /* supported interfaces */ GATJob_vtable *GATObject__vtable; GATJob_ISerialisable_vtable *GATSerialisable__vtable; GATJob_IMonitorable_vtable *GATMonitorable__vtable; /* instance data */ GATJobID gatjobid; /* the GAT job id */ GATJobCPI_Instance data; /* instance data of the corresponding CPI object */ GATJobCPI cpi; /* CPI object to use for all subsequent operations */ GATJobCPIList cpilist; /* CPI list of appropriate CPI objects */ }; /* Static function prototypes */ static GATResult GATJob_DeSerialise_Create(GATContext context, GATObject stream, GATJobID jobid, GATJobState state, GATJob *new_object); static GATResult GATJob_GetCPIInstanceData(GATJob job, void **data); /* file scope variables */ GATJob_vtable GATJob__vtable = { GATJob_GetType, GATJob_Destroy, GATJob_Equals, GATJob_Clone, GATJob_GetInterface, GATJob_GetCPIInstanceData }; static GATJob_ISerialisable_vtable GATJob_ISerialisable__vtable = { GATJob_Serialise, GATJob_DeSerialise, GATJob_GetIsDirty, }; static GATJob_IMonitorable_vtable GATJob_IMonitorable__vtable = { GATJob_AddMetricListener, GATJob_RegisterPolling, GATJob_RemoveRegisteredMetric, GATJob_GetMetrics }; /* External functions */ /** GATJob_Register_GATSerialisable * The GATJob_Register_GATSerialisable function registers the serialization * vtable with the GAT engine to allow generic object creation. * This function is called by the GAT engine, there is no need to use it * directly. */ GATResult GATJob_Register_GATSerialisable(void) { return GATObject_Register_GATSerialisable(GATType_GATJob, &GATJob_ISerialisable__vtable); } /** GATJob_Create * @brief Create a new GATJob object * * The function @c GATJob_Create creates a new * GATJob object * * @param context The GAT context to use while the initialisation of the * new object. * @param preferences The preferences to use while selecting the adaptor for * the corresponding CPI. * @param jobid The job id of the new job, which was assigned by the resource * management system, which cretaed this job. * @param initialisation_data This is the data to be used to initialise the * internal job instance data. The type of this data is defined by the * adaptor creating this job. This data is handed byck to the adaptor * during job construction. * * @return Returns a handle to the newly created GATJob object. * Returns 0 (zero) if an error occurs. */ GATJob GATJob_Create(GATContext context, GATPreferences_const preferences, GATJobID jobid, void *initialisation_data) { GAT_STATUS_APIENTRY(context, "GATJob_Create"); GATJob retval = (GATJob) malloc(sizeof(struct GATJob_S)); if (NULL != retval) { memset(retval, 0, sizeof(struct GATJob_S)); retval->GATObject__vtable = &GATJob__vtable; retval->GATSerialisable__vtable = &GATJob_ISerialisable__vtable; retval->GATMonitorable__vtable = &GATJob_IMonitorable__vtable; retval->gatjobid = NULL; /* should be set later */ retval->data.context = context; retval->data.isdirty = GATFalse; retval->data.source = GATJob_ToGATObject_const(retval); retval->data.state = GATJobState_Initial; GAT_CREATE_STATUS(GATString_Clone(jobid, &retval->data.jobid)); /* find a CPI object, which can handle this object */ if (GAT_SUCCEEDED(GAT_CURRENT_STATUS())) { GATRegistry_const registry = GATContext_internal_GetRegistry(context); /* use default preferences, if appropriate */ if (NULL == preferences) { preferences = GATContext_GetPreferences(context); } retval->cpilist = GATRegistry_FindGATJobCPI(registry, preferences); if (NULL == retval->cpilist) { GAT_CREATE_STATUS(GAT_NO_REGISTERED_CPI); } else { /* create a new instance of the CPI provider */ GATBool found_cpi = GATFalse; GATJobCPIList current = NULL; for(current = retval->cpilist; NULL != current; current = current->next) { GAT_CREATE_STATUS(GATJobCPI_CreateInstance(current->cpi, &retval->data, initialisation_data)); if (GAT_SUCCEEDED(GAT_CURRENT_STATUS())) { retval->cpi = current->cpi; found_cpi = GATTrue; break; } } /* no available CPI object can handle this */ if (GATFalse == found_cpi) { GAT_CREATE_STATUS(GAT_NO_REGISTERED_CPI); } else { /* now, initialise the monitoring framework with the help of the CPI provider found */ GATList_GATMetric metrics = NULL; GATResult err_code = GATJobCPI_GetMetrics(retval->cpi, &retval->data, &metrics); if (GAT_SUCCEEDED(err_code)) { retval->data.monitorable = GATMonitorable_Impl_Create(metrics); if (NULL == retval->data.monitorable) { GAT_CREATE_STATUS(GAT_MEMORYFAILURE); } GATList_GATMetric_Destroy(&metrics); } else if (GAT_NOTIMPL == err_code) { err_code = GAT_SUCCESS; /* no monitoring supported here */ } else { GAT_CREATE_STATUS(err_code); } /* register this object with the engine */ if (GAT_SUCCEEDED(err_code)) { GAT_CREATE_STATUS(GATRegistry_AddGATJobToCPIList(context, retval->cpi, retval)); } } } } } else { GAT_CREATE_STATUS(GAT_MEMORYFAILURE); } /* error handling */ if (GAT_FAILED(GAT_CURRENT_STATUS())) { GATJob_Destroy(&retval); } GAT_STORE_STATUS(); return retval; } /** void GATJob_Destroy(GATJob *resource) * * The function GATJob_Destroy is the destructor used to * free all the memory allocated by an GATJob instance. * * @param description The pointer to the GATJob to destroy */ void GATJob_Destroy(GATJob *object) { if (NULL != object && NULL != *object) { GATString_Destroy(&(*object)->gatjobid); GATString_Destroy(&(*object)->data.jobid); GATMonitorable_Impl_Destroy(&(*object)->data.monitorable); if (NULL != (*object)->cpi) /* during creation this may be zero */ { GATRegistry_RemoveGATJobFromCPIList((*object)->data.context, (*object)->cpi, *object); GATJobCPI_DestroyInstance((*object)->cpi, &(*object)->data); } GATJobCPIList_Destroy((*object)->cpilist); free(*object); *object = NULL; } } /** GATJob_Equals * @brief Compare two GATJob objects * * The function @c GATJob_Equals compares two objects of the * @c GATJob type. * * @param lhs The first list to compare * @param rhs The second list to compare * @param isequal The pointer to the GATBool variable, which should receive * the result if the comparision * * @return An error code. */ GATResult GATJob_Equals(GATJob_const lhs, GATJob_const rhs, GATBool *isequal) { if (NULL != lhs && NULL != rhs) { GAT_STATUS_APIENTRY(lhs->data.context, "GATJob_Equals"); if (NULL != isequal) { if (lhs->data.state != rhs->data.state) { *isequal = GATFalse; } else { GAT_CREATE_STATUS(GATJobCPI_EqualsInstance(lhs->cpi, &lhs->data, &rhs->data, isequal)); } } return GAT_RETURN_STATUS(); } return GAT_INVALID_HANDLE; } /** GATJob_Clone * @brief Clone the given GATJob * * The function @c GATJob_Clone generates a (deep) copy of * the given GATJob. * * @param description The object to clone * @param new_object The pointer, through which the result is to be * returned. * * @return An error type. */ GATResult GATJob_Clone(GATJob_const handle, GATJob *new_handle) { if (NULL != handle) { GAT_STATUS_APIENTRY(handle->data.context, "GATJob_Clone"); if (NULL == new_handle) { GAT_CREATE_STATUS(GAT_INVALID_PARAMETER); } else { struct GATJob_S const *object = handle; GATJob new_object = (GATJob) malloc(sizeof(struct GATJob_S)); *new_handle = NULL; if (NULL == new_object) { GAT_CREATE_STATUS(GAT_MEMORYFAILURE); } else { memset(new_object, 0, sizeof(struct GATJob_S)); new_object->GATObject__vtable = &GATJob__vtable; new_object->GATSerialisable__vtable = &GATJob_ISerialisable__vtable; new_object->GATMonitorable__vtable = &GATJob_IMonitorable__vtable; new_object->data.context = object->data.context; new_object->data.isdirty = GATFalse; new_object->data.source = GATJob_ToGATObject_const(new_object); new_object->data.state = object->data.state; new_object->cpilist = GATRegistry_CloneGATJobCPIList(object->cpilist); if (NULL == new_object->cpilist) { GAT_CREATE_STATUS(GAT_MEMORYFAILURE); } GAT_CREATE_STATUS(GATString_Clone(object->data.jobid, &new_object->data.jobid)); if (GAT_SUCCEEDED(GAT_CURRENT_STATUS())) { /* re-find the cpi to use */ GATJobCPIList current = object->cpilist; GATJobCPIList new_current = new_object->cpilist; for (/**/; NULL != current; current = current->next, new_current = new_current->next) { if (current->cpi == object->cpi) { new_object->cpi = new_current->cpi; break; } } assert(NULL != new_object->cpi); /* clone the instance data */ GAT_CREATE_STATUS(GATJobCPI_CloneInstance(object->cpi, &object->data, &new_object->data)); /* clone the monitoring data */ if (NULL != object->data.monitorable) { GAT_CREATE_STATUS(GATMonitorable_Impl_Clone(object->data.monitorable, &new_object->data.monitorable)); } /* register this object with the engine */ GAT_CREATE_STATUS(GATRegistry_AddGATJobToCPIList( new_object->data.context, new_object->cpi, new_object)); } } /* destroy the newly allocated object, if some error occured */ if (GAT_FAILED(GAT_CURRENT_STATUS())) { GATJob_Destroy(&new_object); } else { /* return the new object */ *new_handle = new_object; } } return GAT_RETURN_STATUS(); } return GAT_INVALID_HANDLE; } /** GATType GATJob_GetType(GATJob_const resource) * @brief Return the type of the GATJob * * The function @c GATJob_GetType always returns * @c #GATType_GATJob. * * @param object The object to inspect * * @return Returns always @c #GATType_GATJob. */ GATType GATJob_GetType(GATJob_const object) { GAT_UNUSED_PARAMETER(object); return GATType_GATJob; } /** GATResult GATJob_GetInterface(GATJob_const file, GATInterface iftype, void const **ifp) * @brief Get an interface supported by a GATObject * * The function GATJob_GetInterface allows to get a pointer to an * additional interface supported by this GATJob. * * @param object The object to be asked for the new interface. * @param iftype The interface the object is to be asked for. * @param ifp The pointer, through which the result is to be returned. * * @return An error type. */ GATResult GATJob_GetInterface(GATJob_const object, GATInterface iftype, void const **ifp) { if (NULL != object) { GAT_STATUS_APIENTRY(object->data.context, "GATJob_GetInterface"); if (NULL != ifp) { if (GATInterface_ISerialisable == iftype || GATInterface_IAdvertisable == iftype) { *ifp = (void const *) &object->GATSerialisable__vtable; } else if (GATInterface_IMonitorable == iftype && NULL != object->data.monitorable) { *ifp = (void const *) &object->GATMonitorable__vtable; } else { *ifp = NULL; GAT_CREATE_STATUS(GAT_NO_INTERFACE); } } return GAT_RETURN_STATUS(); } return GAT_INVALID_HANDLE; } /* GATMonitorable API */ /** GATJob_AddMetricListener * * The function GATJob_AddMetricListener adds the passed instance of a * GATMetricListener to the list of GATMetricListeners which are notified of * fired GATMetricEvents of the type described by the provided GATMetric * instance. * * @param object The GATJob instance to add the GATMetricListener to. * @param listener The GATMetricListener to call, when the corresponding * GATMetricEvent is fired. * @param listener_data The client supplied data, which will be passed through * to the GATMetricListener. * @param metric The GATMetric instance describing the GATMetricEvent to pass * to the GATMetricListener. * @param cookie The returned value should be used to remove the * GATMetricListener from this GATMonitorable. * * @return An error code. */ GATResult GATJob_AddMetricListener(GATJob object, GATMetricListener listener, void *listener_data, GATMetric metric, GATuint32 *cookie) { if (NULL != object) { GAT_STATUS_APIENTRY(object->data.context, "GATJob_AddMetricListener"); if (NULL != object->data.monitorable) { GAT_CREATE_STATUS(GATMonitorable_Impl_AddMetricListener(object->data.monitorable, listener, listener_data, metric, cookie)); } else { /* this may happen, if the adaptor has not registered any GATMetrics */ GAT_CREATE_STATUS(GAT_NO_INTERFACE); } return GAT_RETURN_STATUS(); } return GAT_INVALID_HANDLE; } /** GATJob_RegisterPolling * * The function GATJob_RegisterPolling registers a continuous * metric with the given GATJob instance. * * @param object The GATJob instance to register the metric with. * @param metric The GATMetric instance describing the GATMetricEvent to pass * to the GATMetricListener. This metric instance must be of type * GATMeasurementType_Continuous, otherwise an error is returned. * @param event The pointer to a variable, which should receive the resulting * GATMetricEvent. The GATMetricEvent instance should be freed by the * caller when it isn't used anymore. * @param cookie The returned value should be used to remove the * GATMetricListener from this GATJob. * * @return An error code. */ GATResult GATJob_RegisterPolling(GATJob object, GATMetric metric, GATMetricEvent *event, GATuint32 *cookie) { if (NULL != object) { GAT_STATUS_APIENTRY(object->data.context, "GATJob_RegisterPolling"); if (NULL != object->data.monitorable) { GAT_CREATE_STATUS(GATMonitorable_Impl_RegisterPolling( object->data.monitorable, metric, 0, cookie)); /* ask the CPI provider to return the corresponding metric event */ GAT_CREATE_STATUS(GATJobCPI_GetMetricEvent(object->cpi, &object->data, metric, event)); if (GAT_FAILED(GAT_CURRENT_STATUS()) && NULL != cookie && 0 != *cookie) { GATMonitorable_Impl_RemoveRegisteredMetric(object->data.monitorable, metric, *cookie); *cookie = 0; } } else { /* this may happen, if the adaptor has not registered any GATMetrics */ GAT_CREATE_STATUS(GAT_NO_INTERFACE); } return GAT_RETURN_STATUS(); } return GAT_INVALID_HANDLE; } /** GATJob_RemoveRegisteredMetric * * The function GATJob_RemoveRegisteredMetric removes a GATMetricListener, * which was previously registered with GATJob_AddMetricListener. * * @param object The GATJob instance to remove the GATMetricListener from. * @param listener The GTAMetricListener to call, when the corresponding * GATMetricEvent is fired. * @param metric The GATMetric instance describing the GATMetricEvent to pass * to the GATMetricListener. * @param cookie This value identifies the GATMetricListener to remove, it * was returned from the corresponding GATMonitorable_AddMetricListener * or GATMonitorable_MetricRegisterPolling functions. * * @return An error code. */ GATResult GATJob_RemoveRegisteredMetric(GATJob object, GATMetric metric, GATuint32 cookie) { if (NULL != object) { GAT_STATUS_APIENTRY(object->data.context, "GATJob_RemoveRegisteredMetric"); if (NULL != object->data.monitorable) { GAT_CREATE_STATUS(GATMonitorable_Impl_RemoveRegisteredMetric( object->data.monitorable, metric, cookie)); } else { /* this may happen, if the adaptor has not registered any GATMetrics */ GAT_CREATE_STATUS(GAT_NO_INTERFACE); } return GAT_RETURN_STATUS(); } return GAT_INVALID_HANDLE; } /** GATJob_GetMetrics * * The function GATJob_GetMetrics returns a list of metrics supported * by this GATJob. * * @param object The GATJob instance, for which the supported metrics * should be returned. * @param metrics The pointer to the variable, which receives the resulting * list of metrics. * * @return An error code. */ GATResult GATJob_GetMetrics(GATJob_const object, GATList_GATMetric *metrics) { if (NULL != object) { GAT_STATUS_APIENTRY(object->data.context, "GATJob_GetMetrics"); if (NULL != object->data.monitorable) { GAT_CREATE_STATUS(GATMonitorable_Impl_GetMetrics(object->data.monitorable, metrics)); } else { /* this may happen, if the adaptor has not registered any GATMetrics */ GAT_CREATE_STATUS(GAT_NO_INTERFACE); } return GAT_RETURN_STATUS(); } return GAT_INVALID_HANDLE; } /* GATAdvertiseable API */ /** GATJobCPI_SerialiseCallback * * The function GATJobCPI_SerialiseCallback is used as a callback function * for the serialisation of a GATJob object. * It should be provided to * serialise the associated CPI provider data for the given object. * * @param object The object to serialise. This is the same as the object * passed as the first parameter to the function GATXds_SerialiseObject. * @param stream The stream interface to use for the serialisation. * @param clear_dirty If the clear_dirty parameter is set to GATTrue, the * internal dirty flag of this object is to be reset (no used here) * * @return An error code. * * @remark This function is called from the GAT engine, there is no need to * call it directly. */ static GATResult GATJobCPI_SerialiseCallback(GATObject handle, GATObject stream, GATBool clear_dirty) { GATJob object = GATObject_ToGATJob(handle); if (NULL != object) { GAT_USES_STATUS(object->data.context, "GATJobCPI_SerialiseCallback"); GAT_CREATE_STATUS(GATJobCPI_Serialise(object->cpi, &object->data, stream, clear_dirty)); if (GAT_SUCCEEDED(GAT_CURRENT_STATUS()) && GATTrue == clear_dirty) { object->data.isdirty = GATFalse; } return GAT_RETURN_STATUS(); } return GAT_INVALID_HANDLE; } /** GATResult GATJob_Serialise(GATJob object, GATObject stream, GATBool clear_dirty) * @brief Serialise a GATJob object * * The function GATJob_Serialise serialises the given GATJob object into the * given stream. * * @param object The GATJob object to serialise. * @param stream The stream interface to use for the serialisation. * @param clear_dirty If the clear_dirty parameter is set to GATTrue, the * internal dirty flag of this object is to be reset (no used here) * * @return An error code. */ GATResult GATJob_Serialise(GATJob object, GATObject stream, GATBool clear_dirty) { if (NULL != object) { GAT_USES_STATUS(object->data.context, "GATJob_Serialise"); GAT_CREATE_STATUS(GATXds_SerialiseObject(GATJob_ToGATObject(object), stream, clear_dirty, GATJobCPI_SerialiseCallback, "uint32 uint32 string", GATJOB_VERSION1, (GATuint32) object->data.state, object->data.jobid)); return GAT_RETURN_STATUS(); } return GAT_INVALID_HANDLE; } /** GATJob_VersionCallback * * The function GATJob_VersionCallback is used as a callback function * during the de-serialisation of a GATJob. It should be provided to test, * whether the de-serialised version matches the expected version. * * @param version The version number, which was de-serialised from the stream. * * @return This function should return GATTrue, if the version matches the * expected value (version is valid), GATFalse otherwise. * * @remark This function is called from the GAT engine, there is no need to * call it directly. */ static GATBool GATJob_VersionCallback(GATuint32 version) { GATBool retval = GATFalse; if ((version & ~GATJOB_MINOR_MASK) <= GATJOB_LASTVERSION) { retval = GATTrue; } return retval; } /** GATJob_DeSerialiseCallback * * The function GATJob_DeSerialiseCallback is used as a callback function * during the de-serialisation of a GATJob. It should be provided for the * instantiation of the new GATJob object based on the already de-serialised * data items and the de-serialisation of the associated CPI provider data for * the given object. * * @param context The GAT context to be used for object construction. * @param stream The stream interface to use for the serialisation. * @param object The pointer to the variable, which should receive the newly * constructed object. * @param version The version of the saved data read from the input stream. * @param args This parameter is the pointer to the va_list containing * pointers to the already de-serialised data items accordingly to the * format string, provided during the call to the * GATJob_DeSerialise function. * * @return An error code. * * @remark This function is called from the GAT engine, there is no need to * call it directly. */ static GATResult GATJob_DeSerialiseCallback(GATContext context, GATObject stream, GATObject *new_object, GATuint32 version, va_list args) { GAT_USES_STATUS(context, "GATJob_DeSerialiseCallback"); /* the version was eaten already */ GATuint32 *state = va_arg(args, GATuint32 *); GATJobID *jobid = va_arg(args, GATJobID *); GATJob object = NULL; /* construct the new object */ GAT_CREATE_STATUS(GATJob_DeSerialise_Create(context, stream, *jobid, (GATJobState)*state, &object)); GAT_UNUSED_PARAMETER(version); if (GAT_SUCCEEDED(GAT_CURRENT_STATUS())) { if (NULL != object) { *new_object = GATJob_ToGATObject(object); } else { GATJob_Destroy(&object); GAT_CREATE_STATUS(GAT_INVALID_PARAMETER); } } return GAT_RETURN_STATUS(); } /** GATJob GATJob_DeSerialise(GATContext context, GATObject stream, GATBool clear_dirty) * @brief De-serialise a GATJob object * * The function GATJob_DeSerialise de-serialises a streamed GATJob object * from the given stream It constructs a new instance of the de-serialised * object. * * @param context The GAT context to be used for object construction. * @param stream The stream interface to use for the serialisation. * @param result The pointer to a variable, which receives the status code of * the operation. * * @return The newly constructed GATJob object. */ GATJob GATJob_DeSerialise(GATContext context, GATObject stream, GATResult *result) { GAT_USES_STATUS(context, "GATJob_DeSerialise"); GATObject object = NULL; /* the new object will be created here */ GATJob job = NULL; /* we must provide all instance data items to be de-serialised for this GATJob object accordingly to the provided format string */ GATuint32 version = 0; GATJobID jobid = NULL; GATuint32 state = GATJobState_Unknown; /* read the data */ GAT_CREATE_STATUS(GATXds_DeSerialiseObject(context, stream, GATJob_DeSerialiseCallback, GATJob_VersionCallback, &object, "uint32 uint32 string", &version, &state, &jobid)); GATString_Destroy(&jobid); job = GATObject_ToGATJob(object); if (NULL == job) { GAT_CREATE_STATUS(GAT_BAD_OBJECT_CONVERSION); } if (GAT_FAILED(GAT_CURRENT_STATUS())) { GATObject_Destroy(&object); job = NULL; } if (NULL != result) { *result = GAT_CURRENT_STATUS(); } GAT_STORE_STATUS(); return job; } /** GATJob_GetIsDirty * * The function GATJob_GetIsDirty retrieves the status of the dirty flag of * this GATJob object. * * @param file The GATJob object to inspect for its dirty status. * @param isdirty The pointer to a variable, which receives the dirty status. * * @return An error code. */ GATResult GATJob_GetIsDirty(GATJob_const object, GATBool *isdirty) { if (NULL != object) { GAT_STATUS_APIENTRY(object->data.context, "GATJob_GetIsDirty"); if (NULL != isdirty) { *isdirty = object->data.isdirty; } else { GAT_CREATE_STATUS(GAT_INVALID_PARAMETER); } return GAT_RETURN_STATUS(); } return GAT_INVALID_PARAMETER; } /* Local functions */ /** GATJob_DeSerialise_Create * * The function GATJob_DeSerialise_Create creates a new GATJob object. * Further it tries find a CPI provider to associate with this file object. * The CPI provider is selected by testing, which adapter is able to handle the * streamed instance data of the original CPI provider. * * @param context The GAT context to use for creation of the GATJob object. * @param stream The object from which the adaptor should read the streamed * instance data. * @param state The state of the GATJob object. * @param jobid The job id of the job to create. * @param new_object The pointer to the variable, which should receive the * newly constructed GATJob object. * * @return An error code. */ static GATResult GATJob_DeSerialise_Create(GATContext context, GATObject stream, GATJobID jobid, GATJobState state, GATJob *object) { GAT_USES_STATUS(context, "GATJob_DeSerialise_Create"); GATJob new_object = (GATJob) malloc(sizeof(struct GATJob_S)); if(NULL != new_object) { memset(new_object, 0, sizeof(struct GATJob_S)); new_object->GATObject__vtable = &GATJob__vtable; new_object->GATSerialisable__vtable = &GATJob_ISerialisable__vtable; new_object->GATMonitorable__vtable = &GATJob_IMonitorable__vtable; new_object->data.context = context; new_object->data.isdirty = GATFalse; new_object->data.source = GATJob_ToGATObject_const(new_object); new_object->data.state = state; GAT_CREATE_STATUS(GATString_Clone(jobid, &new_object->data.jobid)); /* find a CPI object, which can handle the data at the given stream location */ if (GAT_SUCCEEDED(GAT_CURRENT_STATUS())) { GATRegistry_const registry = GATContext_internal_GetRegistry(context); GATPreferences_const preferences = NULL; /* use default preferences, if appropriate */ if (NULL == preferences) { preferences = GATContext_GetPreferences(context); } new_object->cpilist = GATRegistry_FindGATJobCPI(registry, preferences); if (NULL == new_object->cpilist) { GAT_CREATE_STATUS(GAT_NO_REGISTERED_CPI); } else { /* find out the current stream position */ GATuint32 offset = 0; GATBool found_cpi = GATFalse; GATJobCPIList current = NULL; GAT_CREATE_STATUS(GATStreamable_Seek(stream, GATOrigin_Current, 0, &offset)); if (GAT_SUCCEEDED(GAT_CURRENT_STATUS())) { /* create new instance data of the CPI provider */ for(current = new_object->cpilist; NULL != current; current = current->next) { /* try, whether this CPI can handle the input */ GAT_CREATE_STATUS(GATJobCPI_DeSerialise(current->cpi, stream, &new_object->data)); if (GAT_SUCCEEDED(GAT_CURRENT_STATUS())) { new_object->cpi = current->cpi; found_cpi = GATTrue; break; } /* reset stream pointer to the beginning of the CPI instance data */ GAT_CREATE_STATUS(GATStreamable_Seek(stream, GATOrigin_Set, offset, 0)); } } /* no available CPI object can handle this */ if (GATFalse == found_cpi) { GAT_CREATE_STATUS(GAT_NO_MATCHING_CPI); } else { /* try to re-init the monitoring support, since the adaptor found may support another set of GATMetric's, than the original one. */ GATList_GATMetric metrics = NULL; GATResult retval = GATJobCPI_GetMetrics(new_object->cpi, &new_object->data, &metrics); if (GAT_SUCCEEDED(retval)) { new_object->data.monitorable = GATMonitorable_Impl_Create(metrics); if (NULL != new_object->data.monitorable) { GAT_CREATE_STATUS(GAT_MEMORYFAILURE); } GATList_GATMetric_Destroy(&metrics); } else if (GAT_NOTIMPL != retval) { GAT_CREATE_STATUS(retval); } else { retval = GAT_SUCCESS; /* no monitoring supported here */ } if (GAT_SUCCEEDED(retval)) { GAT_CREATE_STATUS(GATRegistry_AddGATJobToCPIList(new_object->data.context, new_object->cpi, new_object)); } } } } } else { GAT_CREATE_STATUS(GAT_MEMORYFAILURE); } if (GAT_SUCCEEDED(GAT_CURRENT_STATUS())) { if (NULL != new_object) { *object = new_object; } else { GATJob_Destroy(&new_object); GAT_CREATE_STATUS(GAT_INVALID_PARAMETER); } } else { GATJob_Destroy(&new_object); } return GAT_RETURN_STATUS(); } /** GATJob_UnSchedule * * The function GATJob_UnSchedule guarantees that this GATJob 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 object The job to unschedule. * * @return An error code. */ GATResult GATJob_UnSchedule(GATJob_const object) { if (NULL != object) { GAT_STATUS_APIENTRY(object->data.context, "GATJob_UnSchedule"); GAT_CREATE_STATUS(GATJobCPI_UnSchedule(object->cpi, &object->data)); return GAT_RETURN_STATUS(); } return GAT_INVALID_HANDLE; } /** GATJob_Checkpoint * * The function GATJob_Checkpoint triggers a checkpoint operation for the * 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 object The job to checkpoint. * * @return An error code. */ GATResult GATJob_Checkpoint(GATJob_const object) { if (NULL != object) { GAT_STATUS_APIENTRY(object->data.context, "GATJob_Checkpoint"); GAT_CREATE_STATUS(GATJobCPI_Checkpoint(object->cpi, &object->data)); return GAT_RETURN_STATUS(); } return GAT_INVALID_HANDLE; } /** GATJob_CloneJob * * The function GATJob_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 object The job to clone to a new hardware. * @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. */ GATResult GATJob_CloneJob(GATJob_const object, GATHardwareResource_const hr, GATJob *cloned_job) { if (NULL != object) { GAT_STATUS_APIENTRY(object->data.context, "GATJob_CloneJob"); GAT_CREATE_STATUS(GATJobCPI_CloneJob(object->cpi, &object->data, hr, cloned_job)); return GAT_RETURN_STATUS(); } return GAT_INVALID_HANDLE; } /** GATJob_Migrate * * The function GATJob_Migrate provides similar functionality to the * #GATJob_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 object The job to migrate to a new hardware. * @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. */ GATResult GATJob_Migrate(GATJob_const object, GATHardwareResource_const hr, GATJob *migrated_job) { if (NULL != object) { GAT_STATUS_APIENTRY(object->data.context, "GATJob_Migrate"); GAT_CREATE_STATUS(GATJobCPI_Migrate(object->cpi, &object->data, hr, migrated_job)); return GAT_RETURN_STATUS(); } return GAT_INVALID_HANDLE; } /** GATJob_Stop * * The function GATJob_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 object The job to stop. * * @return An error code. */ GATResult GATJob_Stop(GATJob object) { if (NULL != object) { GAT_STATUS_APIENTRY(object->data.context, "GATJob_Stop"); GAT_CREATE_STATUS(GATJobCPI_Stop(object->cpi, &object->data)); return GAT_RETURN_STATUS(); } return GAT_INVALID_HANDLE; } /** GATJob_GetJobDescription * * The function GATJob_GetJobDescription returns the GATJobDescription * instance used to create that GATJob instance. * * @param object The job for which the associated GATJobDescription should be * returned. * @param jd The ppointer to a variable, which should receive the associated * job description. * * @return An error code. */ GATResult GATJob_GetJobDescription(GATJob_const object, GATJobDescription_const *jd) { if (NULL != object) { GAT_STATUS_APIENTRY(object->data.context, "GATJob_GetJobDescription"); GAT_CREATE_STATUS(GATJobCPI_GetJobDescription(object->cpi, &object->data, jd)); return GAT_RETURN_STATUS(); } return GAT_INVALID_HANDLE; } /** GATJob_GetState * * The function GATJob_GetState returns the state of the represented process. * This is one of the associated public class constants #GATJobState_Initial, * #GATJobState_Scheduled, #GATJobState_Running, or #GATJobState_Stopped. * * @param object The job The job for which the associated GATJobState should be * returned. * @param state The pointer to a variable, which should receive the resulting * GATJobState. * * @return An error code. */ GATResult GATJob_GetState(GATJob_const object, GATJobState *state) { if (NULL != object) { GAT_STATUS_APIENTRY(object->data.context, "GATJob_GetState"); if (NULL != state) { *state = object->data.state; } else { GAT_CREATE_STATUS(GAT_INVALID_PARAMETER); } return GAT_RETURN_STATUS(); } return GAT_INVALID_HANDLE; } /** GATJob_GetInfo * * The function GATJob_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 * GATJob is checkpointable etc. * * @param object The job to ask for its parameter info. * @param jobinfo The pointer to a variable, which should receive the returned * GATTable containing the job information. * * @return An error code. */ GATResult GATJob_GetInfo(GATJob_const object, GATTable_const *jobinfo) { if (NULL != object) { GAT_STATUS_APIENTRY(object->data.context, "GATJob_GetInfo"); GAT_CREATE_STATUS(GATJobCPI_GetInfo(object->cpi, &object->data, jobinfo)); return GAT_RETURN_STATUS(); } return GAT_INVALID_HANDLE; } /** GATJob_GetJobID * * The function GATJob_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 object The job to get the job id for. * @param jobid The pointer to a variable, which should receive the resulting * job id. * * @return An error code. */ GATResult GATJob_GetJobID(GATJob_const object, GATJobID_const *jobid) { if (NULL != object) { GAT_STATUS_APIENTRY(object->data.context, "GATJob_GetJobID"); if (NULL != jobid) { *jobid = object->gatjobid; } else { GAT_CREATE_STATUS(GAT_INVALID_PARAMETER); } return GAT_RETURN_STATUS(); } return GAT_INVALID_HANDLE; } /** GATJob_GetNativeID * * The function GATJob_GetNativeID returns the job id, which was assigned to * this job by the resource management service starting this job. If no such * native id exists, this function will fail. * * @param object The job to get the job id for. * @param jobid The pointer to a variable, which should receive the resulting * GRMS job id. * * @return An error code. */ GATResult GATJob_GetNativeID(GATJob_const object, GATJobID_const *jobid) { if (NULL != object) { GAT_STATUS_APIENTRY(object->data.context, "GATJob_GetNativeID"); if (NULL != jobid) { *jobid = object->data.jobid; } else { GAT_CREATE_STATUS(GAT_INVALID_PARAMETER); } return GAT_RETURN_STATUS(); } return GAT_INVALID_HANDLE; } /** GATJob_GetStatus * * The function GATJob_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 object The job to ask for the associated GATStatus object. * @param status The variable, which should receive the associated GATStatus * object. * * @return An error code. */ GATResult GATJob_GetStatus(GATJob_const object, GATStatus_const *jobstatus) { if (NULL != object) { GAT_STATUS_APIENTRY(object->data.context, "GATJob_GetStatus"); GAT_CREATE_STATUS(GATJobCPI_GetStatus(object->cpi, &object->data, jobstatus)); return GAT_RETURN_STATUS(); } return GAT_INVALID_HANDLE; } /* GATJob_GetCPIInstanceData * * The function GATJob_GetCPIInstanceData returns the CPI instance data, * associated with the given GATJob object. * * @param job The object, for which to return the CPI instance data. * @param data The pointer to the variable, which should receive the * resulting CPI instance data. * * @return An error code. */ static GATResult GATJob_GetCPIInstanceData(GATJob job, void **data) { if (NULL != job) { GAT_USES_STATUS(job->data.context, "GATJob_GetCPIInstanceData"); if (NULL != data) { *data = (void *)&job->data; } else { GAT_CREATE_STATUS(GAT_INVALID_PARAMETER); } return GAT_RETURN_STATUS(); } return GAT_INVALID_HANDLE; } /* GATJob_internal_SetGATJobId * * The function GATJob_internal_SetGATJobId sets the GAT related job id, which * is maintained independently of the job id assigned my some resource * management system. * */ GATResult GATJob_internal_SetGATJobId(GATJob job, GATString_const gatjobid) { if (NULL != job) { GAT_USES_STATUS(job->data.context, "GATJob_internal_SetGATJobId"); if (NULL != job->gatjobid) { GATString_Destroy(&job->gatjobid); } GAT_CREATE_STATUS(GATString_Clone(gatjobid, &job->gatjobid)); return GAT_RETURN_STATUS(); } return GAT_INVALID_HANDLE; }