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

GATJobDescription.c Go to the documentation of this file. /** @file GATJobDescription.c * Source file for the GATJobDescription class. * * An instance of this class describes a job to be run. * * @date Thu Oct 23 2003 * * @version $Header: /export/cvs-gridlab/wp-1/Codes/GATEngine/C-reference/src/GATJobDescription.c,v 1.14 2004/04/02 12:31:57 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/GATJobDescription.c,v 1.14 2004/04/02 12:31:57 hartmutkaiser Exp $"; /* System Header Files */ #include <stdlib.h> #include <string.h> /* GAT Header Files */ #include "GATInternal.h" #include "GATErrors.h" #include "GATType.h" #include "GATRegistry.h" #include "GATResourceDescription.h" #include "GATSoftwareDescription.h" #include "GATJobDescription.h" #include "GATResourceBroker.h" #include "GATXdsWrapper.h" /* define the vtable types */ GATOBJECT_DEFINE_VTABLE(GATJobDescription); GATSERIALISABLE_DEFINE_VTABLE(GATJobDescription); /* define the converters to/from GATObject */ GATOBJECT_DEFINE_CONVERTERS(GATJobDescription) /* Macros */ /* Structures, unions and enums */ struct GATJobDescription_S { GATJobDescription_vtable *GATObject__vtable; GATJobDescription_ISerialisable_vtable *GATSerialisable__vtable; GATBool isdirty; GATSoftwareDescription software; GATResourceDescription description; GATResource resource; }; /* Static function prototypes */ static int GATJobDescription_DeSerialise_Create(GATContext context, GATObject stream, GATSoftwareDescription software, GATType type, GATObject resource, GATJobDescription *new_object); /* File scope variables */ GATJobDescription_vtable GATJobDescription__vtable = { GATJobDescription_GetType, GATJobDescription_Destroy, GATJobDescription_Equals, GATJobDescription_Clone, GATJobDescription_GetInterface, NULL }; static GATJobDescription_ISerialisable_vtable GATJobDescription_ISerialisable__vtable = { GATJobDescription_Serialise, GATJobDescription_DeSerialise, GATJobDescription_GetIsDirty, }; /* External functions */ /** GATJobDescription_Register_GATSerialisable * The GATJobDescription_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 GATJobDescription_Register_GATSerialisable(void) { return GATObject_Register_GATSerialisable(GATType_GATJobDescription, &GATJobDescription_ISerialisable__vtable); } /** GATJobDescription_Create * @brief Create a new GATJobDescription object * * The function @c GATJobDescription_Create creates a new * GATJobDescription object * * @param context The GAT context to use while thie initialisation of the * new object. * @param software The software description of the job to describe. * @param resource The resource description for the job to describe. * * @return Returns a handle to the newly created GATJobDescription object. * Returns 0 (zero) if an error occurs. */ GATJobDescription GATJobDescription_Create_Description(GATContext context, GATSoftwareDescription_const software, GATResourceDescription_const description) { GATResult err_code = GAT_MEMORYFAILURE; GATJobDescription retval = (GATJobDescription) malloc( sizeof(struct GATJobDescription_S)); GAT_UNUSED_PARAMETER(context); if (NULL != retval) { memset(retval, 0, sizeof(struct GATJobDescription_S)); retval->GATObject__vtable = &GATJobDescription__vtable; retval->GATSerialisable__vtable = &GATJobDescription_ISerialisable__vtable; retval->isdirty = GATFalse; err_code = GATSoftwareDescription_Clone(software, &retval->software); if (GAT_SUCCEEDED(err_code)) { GATObject_const object = GATResourceDescription_ToGATObject_const(description); GATType type = GATObject_GetType(object); if (GATType_GATSoftwareResourceDescription == type) { err_code = GATSoftwareResourceDescription_Clone( (GATSoftwareResourceDescription_const) description, (GATSoftwareResourceDescription *) &retval->description); } else { err_code = GATHardwareResourceDescription_Clone( (GATHardwareResourceDescription_const) description, (GATHardwareResourceDescription *) &retval->description); } } } /* error handling */ if (GAT_FAILED(err_code)) { GATJobDescription_Destroy(&retval); } return retval; } /** GATJobDescription_Create * @brief Create a new GATJobDescription object * * The function @c GATJobDescription_Create creates a new * GATJobDescription object * * @param context The GAT context to use while thie initialisation of the * new object. * @param software The software description of the job to describe. * @param resource The resource for the job to describe. * * @return Returns a handle to the newly created GATJobDescription object. * Returns 0 (zero) if an error occurs. */ GATJobDescription GATJobDescription_Create(GATContext context, GATSoftwareDescription_const software, GATResource_const resource) { GATResult err_code = GAT_MEMORYFAILURE; GATJobDescription retval = (GATJobDescription) malloc( sizeof(struct GATJobDescription_S)); GAT_UNUSED_PARAMETER(context); if (NULL != retval) { memset(retval, 0, sizeof(struct GATJobDescription_S)); retval->GATObject__vtable = &GATJobDescription__vtable; retval->GATSerialisable__vtable = &GATJobDescription_ISerialisable__vtable; retval->isdirty = GATFalse; err_code = GATSoftwareDescription_Clone(software, &retval->software); if (GAT_SUCCEEDED(err_code)) { err_code = GATResource_Clone(resource, &retval->resource); } } /* error handling */ if (GAT_FAILED(err_code)) { GATJobDescription_Destroy(&retval); } return retval; } /** void GATJobDescription_Destroy(GATJobDescription *resource) * * The function GATJobDescription_Destroy is the destructor used to * free all the memory allocated by an GATJobDescription instance. * * @param description The pointer to the GATJobDescription to destroy */ void GATJobDescription_Destroy(GATJobDescription *object) { if (NULL != object && NULL != *object) { GATSoftwareDescription_Destroy(&(*object)->software); if (NULL != (*object)->description) { GATObject obj = GATResourceDescription_ToGATObject( (*object)->description); GATObject_Destroy(&obj); } if (NULL != (*object)->resource) { GATResource_Destroy(&(*object)->resource); } free(*object); *object = NULL; } } /** GATJobDescription_Equals * @brief Compare two GATJobDescription objects * * The function @c GATJobDescription_Equals compares two objects of the * @c GATJobDescription type. * * @param lhs The first list to compare * @param rhs The second list to compare * @param isequal The pointer to the location, where the outcome of the * function has to be stored. * * @return An error code. */ GATResult GATJobDescription_Equals(GATJobDescription_const lhs, GATJobDescription_const rhs, GATBool *isequal) { GATResult retval = GAT_INVALID_HANDLE; if (NULL != lhs && NULL != rhs) { retval = GAT_INVALID_PARAMETER; if (NULL != isequal) { retval = GATSoftwareDescription_Equals(lhs->software, rhs->software, isequal); if (GAT_SUCCEEDED(retval) && GATTrue == *isequal) { if (NULL != lhs->description && NULL != rhs->description) { retval = GATResourceDescription_Equals(lhs->description, rhs->description, isequal); } else if (NULL != lhs->resource && NULL != rhs->description) { retval = GATResource_Equals(lhs->resource, rhs->resource, isequal); } else { *isequal = GATFalse; retval = GAT_SUCCESS; } } } } return retval; } /** GATJobDescription_Clone * @brief Clone the given GATJobDescription * * The function @c GATJobDescription_Clone generates a (deep) copy of * the given GATJobDescription. * * @param description The object to clone * @param new_object The pointer, through which the result is to be * returned. * * @return An error type. */ GATResult GATJobDescription_Clone(GATJobDescription_const object, GATJobDescription *new_handle) { GATResult retval = GAT_INVALID_HANDLE; if (NULL != object) { if (NULL == new_handle) { retval = GAT_INVALID_PARAMETER; } else { GATJobDescription new_object = (GATJobDescription) malloc(sizeof(struct GATJobDescription_S)); *new_handle = NULL; if (NULL == new_object) { retval = GAT_MEMORYFAILURE; } else { memset(new_object, 0, sizeof(struct GATJobDescription_S)); new_object->GATObject__vtable = &GATJobDescription__vtable; new_object->GATSerialisable__vtable = &GATJobDescription_ISerialisable__vtable; new_object->isdirty = object->isdirty; retval = GATSoftwareDescription_Clone(object->software, &new_object->software); if (GAT_SUCCEEDED(retval)) { if (NULL != object->description) { GATType type = GATResourceDescription_GetType(object->description); retval = GATResourceDescription_Clone(type, object->description, &new_object->description); } if (NULL != object->resource) { retval = GATResource_Clone(object->resource, &new_object->resource); } } } if (GAT_FAILED(retval)) { GATJobDescription_Destroy(&new_object); } else { *new_handle = new_object; } } } return retval; } /** GATType GATJobDescription_GetType(GATJobDescription_const resource) * @brief Return the type of the GATJobDescription * * The function @c GATJobDescription_GetType always returns * @c #GATType_GATJobDescription. * * @param object The object to inspect * * @return Returns always @c #GATType_GATJobDescription. */ GATType GATJobDescription_GetType(GATJobDescription_const description) { GAT_UNUSED_PARAMETER(description); return GATType_GATJobDescription; } /** GATResult GATJobDescription_GetInterface(GATJobDescription_const file, GATInterface iftype, void const **ifp) * @brief Get an interface supported by a GATObject * * The function GATJobDescription_GetInterface allows to get a pointer to an * additional interface supported by this GATJobDescription. * * @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 GATJobDescription_GetInterface(GATJobDescription_const object, GATInterface iftype, void const **ifp) { GATResult retval = GAT_INVALID_PARAMETER; if (NULL != ifp) { *ifp = NULL; if (GATInterface_ISerialisable == iftype) { *ifp = (void const *) &object->GATSerialisable__vtable; retval = GAT_SUCCESS; } else { retval = GAT_NO_INTERFACE; } } return retval; } /* Return the software description describing this job */ GATSoftwareDescription_const GATJobDescription_GetSoftwareDescription(GATJobDescription_const object) { GATSoftwareDescription_const retval = NULL; if (NULL != object) { retval = object->software; } return retval; } /* Return the of the resources the job can be run on */ GATResourceDescription_const GATJobDescription_GetResourceDescription(GATJobDescription_const object) { GATResourceDescription_const retval = NULL; if (NULL != object) { retval = object->description; } return retval; } /* Return the resource the job SHOULD be run on */ GATResource_const GATJobDescription_GetResource(GATJobDescription_const object) { GATResource_const retval = NULL; if (NULL != object) { retval = object->resource; } return retval; } /* GATSerialisable API */ /** GATResult GATJobDescription_Serialise(GATJobDescription object, GATObject stream, GATBool clear_dirty) * @brief Serialise a GATJobDescription object * * The function GATJobDescription_Serialise serialises the given GATFIle object * into the given stream. * * @param object The GATJobDescription 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 GATJobDescription_Serialise(GATJobDescription object, GATObject stream, GATBool clear_dirty) { GATResult retval = GAT_INVALID_HANDLE; if (NULL != object) { if (NULL != object->description) { retval = GATXds_SerialiseObject( GATJobDescription_ToGATObject(object), stream, clear_dirty, 0, "uint32 uint32 object object", GATJOBDESCRIPTION_VERSION1, GATType_GATResourceDescription, object->software, clear_dirty, object->description, clear_dirty); } else if (NULL != object->resource) { retval = GATXds_SerialiseObject( GATJobDescription_ToGATObject(object), stream, clear_dirty, 0, "uint32 uint32 object object", GATJOBDESCRIPTION_VERSION1, GATType_GATResource, object->software, clear_dirty, object->resource, clear_dirty); } else { retval = GAT_INVALID_PARAMETER; } if (GAT_SUCCEEDED(retval) && clear_dirty) { object->isdirty = GATFalse; } } return retval; } /** GATJobDescription_VersionCallback * * The function GATJobDescription_VersionCallback is used as a callback function * during the de-serialisation of a GATJobDescription. 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 GATJobDescription_VersionCallback(GATuint32 version) { GATBool retval = GATFalse; if ((version & ~GATJOBDESCRIPTION_MINOR_MASK) <= GATJOBDESCRIPTION_LASTVERSION) { retval = GATTrue; } return retval; } /** GATJobDescription_DeSerialiseCallback * * The function GATJobDescription_DeSerialiseCallback is used as a callback function * during the de-serialisation of a GATJobDescription. It should be provided for the * instantiation of the new GATJobDescription 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 * GATJobDescription_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 GATJobDescription_DeSerialiseCallback(GATContext context, GATObject stream, GATObject *new_object, GATuint32 version, va_list args) { GAT_USES_STATUS(context, "GATJobDescription_DeSerialiseCallback"); /* the version was eaten already */ GATuint32 *type = va_arg(args, GATuint32 *); GATSoftwareDescription *software = va_arg(args, GATSoftwareDescription *); GATObject *resource = va_arg(args, GATObject *); GATJobDescription object = NULL; GAT_UNUSED_PARAMETER(version); /* construct the new object */ GAT_CREATE_STATUS(GATJobDescription_DeSerialise_Create(context, stream, *software, (GATType)*type, *resource, &object)); if (GAT_SUCCEEDED(GAT_CURRENT_STATUS())) { if (NULL != object) { *new_object = GATJobDescription_ToGATObject(object); } else { GATJobDescription_Destroy(&object); GAT_CREATE_STATUS(GAT_INVALID_PARAMETER); } } return GAT_RETURN_STATUS(); } /** GATJobDescription GATJobDescription_DeSerialise(GATContext context, GATObject stream, GATBool clear_dirty) * @brief De-serialise a GATJobDescription object * * The function GATJobDescription_DeSerialise de-serialises a streamed * GATJobDescription 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 GATJobDescription object. */ GATJobDescription GATJobDescription_DeSerialise(GATContext context, GATObject stream, GATResult *result) { GAT_USES_STATUS(context, "GATJobDescription_DeSerialise"); GATObject object = NULL; /* the new object will be created here */ /* we must provide all instance data items to be de-serialised for this GATJobDescription object accordingly to the provided format string */ GATuint32 version = 0; GATSoftwareDescription software = NULL; GATuint32 type = GATType_NoType; GATObject resource = NULL; /* read the data */ GATResult retval = GATXds_DeSerialiseObject(context, stream, GATJobDescription_DeSerialiseCallback, GATJobDescription_VersionCallback, &object, "uint32 uint32 object object", &version, &type, &software, &resource); GAT_CREATE_STATUS(retval); GATSoftwareDescription_Destroy(&software); GATObject_Destroy(&resource); if (NULL != result) { *result = GAT_RETURN_STATUS(); } else { GAT_STORE_STATUS(); } return GATObject_ToGATJobDescription(object); } /** GATJobDescription_GetIsDirty * * The function GATJobDescription_GetIsDirty retrieves the status of the dirty flag of * this GATJobDescription object. * * @param file The GATJobDescription object to inspect for its dirty status. * @param isdirty The pointer to a variable, which receives the dirty status. * * @return An error code. */ GATResult GATJobDescription_GetIsDirty(GATJobDescription_const object, GATBool *isdirty) { GATResult retval = GAT_INVALID_HANDLE; if (NULL != object) { if (NULL != isdirty) { *isdirty = object->isdirty; retval = GAT_SUCCESS; } else { retval = GAT_INVALID_PARAMETER; } } return retval; } /* internal functions */ /* GATJobDescription_internal_GetEnvironment * * The function GATJobDescription_internal_GetEnvironment gets a reference to * the table, which stores the environment variables for the job described. * * @param jd The job description to query for the environemnt table. * @param env The variable receiving the resulting Table reference. * * @return An error code. */ GATResult GATJobDescription_internal_GetEnvironment(GATJobDescription jd, GATTable *env) { GATResult retval = GAT_INVALID_HANDLE; if (NULL != jd) { GATObject obj = NULL; retval = GATTable_internal_Get_GATObjectRef( GATSoftwareDescription_GetAttributes(jd->software), "environment", &obj); if (GAT_FAILED(retval)) { /* need to create the environment table in the softwrae description */ GATTable environment = GATTable_Create(); if (NULL != environment) { GATTable attr = NULL; retval = GATSoftwareDescription_internal_GetAttributesRef(jd->software, &attr); if (GAT_SUCCEEDED(retval)) { retval = GATTable_Add_GATObject(attr, "environment", GATTable_ToGATObject_const(environment)); } /* access the newly created table */ retval = GATTable_internal_Get_GATObjectRef(attr, "environment", &obj); GATTable_Destroy(&environment); } else { retval = GAT_MEMORYFAILURE; } } if (GAT_SUCCEEDED(retval)) { if (NULL != env) { *env = GATObject_ToGATTable(obj); retval = GAT_SUCCESS; } else { retval = GAT_INVALID_PARAMETER; } } } return retval; } /* Local functions */ /** GATJobDescription_DeSerialise_Create * * The function GATJobDescription_DeSerialise_Create creates a new * GATJobDescription object. * * @param context The GAT context to use for creation of the GATJobDescription * object. * @param stream The object from which the adaptor should read the streamed * instance data. * @param software The software description to use for creation of the new job * description. * @param type This parameter should be equal to GATType_GATResourceDescription * or GATType_GATResource. * @param resource This is the resoure description or the resource to be used * for creation of the new job description. * @param new_object The pointer to the variable, which should receive the * newly constructed GATJobDescription object. * * @return An error code. */ static GATResult GATJobDescription_DeSerialise_Create(GATContext context, GATObject stream, GATSoftwareDescription software, GATType type, GATObject resource, GATJobDescription *object) { GAT_USES_STATUS(context, "GATJobDescription_DeSerialise_Create"); GATJobDescription new_object = (GATJobDescription) malloc(sizeof(struct GATJobDescription_S)); GAT_UNUSED_PARAMETER(stream); if(NULL != new_object) { memset(new_object, 0, sizeof(struct GATJobDescription_S)); new_object->GATObject__vtable = &GATJobDescription__vtable; new_object->GATSerialisable__vtable = &GATJobDescription_ISerialisable__vtable; new_object->isdirty = GATFalse; GAT_CREATE_STATUS(GATSoftwareDescription_Clone(software, &new_object->software)); if (GATType_GATResourceDescription == type) { GATType resource_type = GATObject_GetType(resource); GAT_CREATE_STATUS(GATResourceDescription_Clone(resource_type, (GATResourceDescription) resource, &new_object->description)); } else if (GATType_GATResource == type) { GAT_CREATE_STATUS(GATResource_Clone((GATResource) object, &new_object->resource)); } else { GAT_CREATE_STATUS(GAT_INVALID_PARAMETER); } } if (GAT_SUCCEEDED(GAT_CURRENT_STATUS())) { if (NULL != new_object) { *object = new_object; } else { GATJobDescription_Destroy(&new_object); GAT_CREATE_STATUS(GAT_INVALID_PARAMETER); } } else { GATJobDescription_Destroy(&new_object); } return GAT_RETURN_STATUS(); }