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

GATResourceBroker.c Go to the documentation of this file. /** @file GATResourceBroker.c * Source file for the GATResourceBroker class. * * An instance of this class is used to broker Resources. A resource can * either be a node or a component. * * @date Thu Oct 23 2003 * * @version $Header: /export/cvs-gridlab/wp-1/Codes/GATEngine/C-reference/src/GATResourceBroker.c,v 1.18 2004/04/20 12:33:22 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/GATResourceBroker.c,v 1.18 2004/04/20 12:33:22 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 "GATResourceBrokerCPI.h" /* * Define the type specific interface functions for the GATList_GATResource * list */ GATLIST_IMPLEMENT(extern, GATResource, GATList_GATResource, GATType_GATResource); /* define the vtable types */ GATOBJECT_DEFINE_VTABLE(GATResourceBroker); /* define the converters to/from GATObject */ GATOBJECT_DEFINE_CONVERTERS(GATResourceBroker) /* Macros */ /* Structures, unions and enums */ struct GATResourceBroker_S { /* supported interfaces */ GATResourceBroker_vtable *GATObject__vtable; /* instance data */ GATResourceBrokerCPI_Instance data; /* instance data of the corresponding CPI object */ GATResourceBrokerCPI cpi; /* CPI object to use for all subsequent operations */ GATResourceBrokerCPIList cpilist; /* CPI list of appropriate CPI objects */ }; /* Static function prototypes */ static GATResult GATResourceBroker_GetCPIInstanceData(GATResourceBroker object, void **data); static GATResult GATResourceBroker_SetJobEnvironment(GATResourceBroker broker, GATJobDescription description, GATJobID_const gatjobid); /* file scope variables */ GATResourceBroker_vtable GATResourceBroker__vtable = { GATResourceBroker_GetType, GATResourceBroker_Destroy, GATResourceBroker_Equals, GATResourceBroker_Clone, GATResourceBroker_GetInterface, GATResourceBroker_GetCPIInstanceData }; /* External functions */ /** GATResourceBroker_Create * @brief Create a new GATResourceBroker object * * The function @c GATResourceBroker_Create creates a new * GATResourceBroker 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. * * @return Returns a handle to the newly created GATResourceBroker object. * Returns 0 (zero) if an error occurs. */ GATResourceBroker GATResourceBroker_Create(GATContext context, GATPreferences_const preferences, GATString vo_name) { GATResult err_code = GAT_MEMORYFAILURE; GATResourceBroker retval = (GATResourceBroker) malloc( sizeof(struct GATResourceBroker_S)); if (NULL != retval) { memset(retval, 0, sizeof(struct GATResourceBroker_S)); retval->GATObject__vtable = &GATResourceBroker__vtable; retval->data.context = context; /* the name of the virtual organisation to use is optional */ if (NULL != vo_name) { err_code = GATString_Clone(vo_name, &retval->data.vo_name); } else { err_code = GAT_SUCCESS; } /* find a CPI object, which can handle this object */ if (GAT_SUCCEEDED(err_code)) { GATBool found_cpi = GATFalse; GATResourceBrokerCPIList current = NULL; GATRegistry_const registry = GATContext_internal_GetRegistry(context); /* use default preferences, if appropriate */ if (NULL == preferences) { preferences = GATContext_GetPreferences(context); } retval->cpilist = GATRegistry_FindGATResourceBrokerCPI(registry, preferences); if (NULL == retval->cpilist) { GATResourceBroker_Destroy(&retval); err_code = GAT_NO_REGISTERED_CPI; } else { /* create a new instance of the CPI provider */ err_code = GAT_NO_MATCHING_CPI; for(current = retval->cpilist; NULL != current; current = current->next) { err_code = GATResourceBrokerCPI_CreateInstance(current->cpi, &retval->data); if (GAT_SUCCESS == err_code) { retval->cpi = current->cpi; found_cpi = GATTrue; break; } } /* register this object with the engine */ if (GAT_SUCCEEDED(retval)) { err_code = GATRegistry_AddGATResourceBrokerToCPIList(context, retval->cpi, retval); } } } } /* error handling */ if (GAT_SUCCESS != err_code) { GATResourceBroker_Destroy(&retval); } return retval; } /** void GATResourceBroker_Destroy(GATResourceBroker *resource) * * The function GATResourceBroker_Destroy is the destructor used to * free all the memory allocated by an GATResourceBroker instance. * * @param description The pointer to the GATResourceBroker to destroy */ void GATResourceBroker_Destroy(GATResourceBroker *object) { if (NULL != object && NULL != *object) { GATString_Destroy(&(*object)->data.vo_name); if (NULL != (*object)->cpi) /* during creation this may be zero */ { GATRegistry_RemoveGATResourceBrokerFromCPIList((*object)->data.context, (*object)->cpi, *object); GATResourceBrokerCPI_DestroyInstance((*object)->cpi, &(*object)->data); } GATResourceBrokerCPIList_Destroy((*object)->cpilist); free(*object); *object = NULL; } } /** GATResourceBroker_Equals * @brief Compare two GATResourceBroker objects * * The function @c GATResourceBroker_Equals compares two objects of the * @c GATResourceBroker 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 GATResourceBroker_Equals(GATResourceBroker_const lhs, GATResourceBroker_const rhs, GATBool *isequal) { GATResult retval = GAT_INVALID_HANDLE; if (NULL != lhs && NULL != rhs) { retval = GAT_INVALID_PARAMETER; if (NULL != isequal) { if (NULL == lhs->data.vo_name && NULL == rhs->data.vo_name) { retval = GAT_SUCCESS; *isequal = GATTrue; } else if (NULL != lhs->data.vo_name && NULL != rhs->data.vo_name) { retval = GATString_Equals(lhs->data.vo_name, rhs->data.vo_name, isequal); } else { retval = GAT_SUCCESS; *isequal = GATFalse; } if (GAT_SUCCEEDED(retval) && GATTrue == *isequal) { retval = GATResourceBrokerCPI_EqualsInstance(lhs->cpi, &lhs->data, &rhs->data, isequal); } } } return retval; } /** GATResourceBroker_Clone * @brief Clone the given GATResourceBroker * * The function @c GATResourceBroker_Clone generates a (deep) copy of * the given GATResourceBroker. * * @param description The object to clone * @param new_object The pointer, through which the result is to be * returned. * * @return An error type. */ GATResult GATResourceBroker_Clone(GATResourceBroker_const handle, GATResourceBroker *new_handle) { if (NULL != handle) { GAT_USES_STATUS(handle->data.context, "GATResourceBroker_Clone"); if (NULL == new_handle) { GAT_CREATE_STATUS(GAT_INVALID_PARAMETER); } else { struct GATResourceBroker_S const *object = handle; GATResourceBroker new_object = (GATResourceBroker) malloc(sizeof(struct GATResourceBroker_S)); *new_handle = NULL; if (NULL == new_object) { GAT_CREATE_STATUS(GAT_MEMORYFAILURE); } else { memset(new_object, 0, sizeof(struct GATResourceBroker_S)); new_object->GATObject__vtable = &GATResourceBroker__vtable; new_object->data.context = object->data.context; if (NULL != object->data.vo_name) { GAT_CREATE_STATUS(GATString_Clone(object->data.vo_name, &new_object->data.vo_name)); } new_object->cpilist = GATRegistry_CloneGATResourceBrokerCPIList(object->cpilist); if (GAT_FAILED(GAT_CURRENT_STATUS()) || NULL == new_object->cpilist) { GAT_CREATE_STATUS(GAT_MEMORYFAILURE); } if (GAT_SUCCEEDED(GAT_CURRENT_STATUS())) { /* re-find the cpi to use */ GATResourceBrokerCPIList current = object->cpilist; GATResourceBrokerCPIList 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(GATResourceBrokerCPI_CloneInstance(object->cpi, &object->data, &new_object->data)); /* register this object with the engine */ GAT_CREATE_STATUS(GATRegistry_AddGATResourceBrokerToCPIList( new_object->data.context, new_object->cpi, new_object)); } } /* destroy the newly allocated object, if some error occured */ if (GAT_FAILED(GAT_CURRENT_STATUS())) { GATResourceBroker_Destroy(&new_object); } else { /* return the new object */ *new_handle = new_object; } } } return GAT_INVALID_HANDLE; } /** GATType GATResourceBroker_GetType(GATResourceBroker_const resource) * @brief Return the type of the GATResourceBroker * * The function @c GATResourceBroker_GetType always returns * @c #GATType_GATResourceBroker. * * @param object The object to inspect * * @return Returns always @c #GATType_GATResourceBroker. */ GATType GATResourceBroker_GetType(GATResourceBroker_const object) { GAT_UNUSED_PARAMETER(object); return GATType_GATResourceBroker; } /** int GATResourceBroker_GetInterface(GATResourceBroker_const file, GATInterface iftype, void const **ifp) * @brief Get an interface supported by a GATObject * * The function GATResourceBroker_GetInterface allows to get a pointer to an * additional interface supported by this GATResourceBroker. * * @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 GATResourceBroker_GetInterface(GATResourceBroker_const object, GATInterface iftype, void const **ifp) { GAT_UNUSED_PARAMETER(object); GAT_UNUSED_PARAMETER(iftype); if (NULL != object) { GAT_STATUS_APIENTRY(object->data.context, "GATResourceBroker_GetInterface"); if (NULL != ifp) { *ifp = NULL; GAT_CREATE_STATUS(GAT_NO_INTERFACE); } else { GAT_CREATE_STATUS(GAT_INVALID_PARAMETER); } return GAT_RETURN_STATUS(); } return GAT_INVALID_HANDLE; } /** GATResourceBroker_ReserveResource_Description * @brief reserve a resource matching the description * * The function @c GATResourceBroker_ReserveResource_Description tries to find * a resource, which matches the provided description and returns a * reservation for this resource. * * @param broker The resource broker to use for this operation. * @param description The resource description needed for selecting the * required resource. * @param time The (optional) time, when the reservation has to start. * @param duration The (optional) time period for which to reserve the * resource. * @param reservation The pointer to the GATReservation variable to use to * return the resulting reservation. * * @return An error code. */ GATResult GATResourceBroker_ReserveResource_Description(GATResourceBroker broker, GATResourceDescription_const description, GATTime_const time_of_start, GATTimePeriod_const duration, GATReservation *reservation) { if (NULL != broker) { GAT_STATUS_APIENTRY(broker->data.context, "GATResourceBroker_ReserveResource"); GAT_CREATE_STATUS(GATResourceBrokerCPI_ReserveResource_Description( broker->cpi, &broker->data, description, time_of_start, duration, reservation)); return GAT_RETURN_STATUS(); } return GAT_INVALID_HANDLE; } /** GATResourceBroker_ReserveResource * @brief Reserve a given resource. * * The function @c GATResourceBroker_ReserveResource tries to reserve * the given resource and returns a reservation for this resource. * * @param broker The resource broker to use for this operation. * @param context The associated GAT context. * @param resource The resource to reserve. * @param time The (optional) time, when the reservation has to start. * @param duration The (optional) time period for which to reserve the * resource. * @param reservation The pointer to the GATReservation variable to use to * return the resulting reservation. * * @return An error value. */ GATResult GATResourceBroker_ReserveResource(GATResourceBroker broker, GATResource_const resource, GATTime_const time_of_start, GATTimePeriod_const duration, GATReservation *reservation) { if (NULL != broker) { GAT_STATUS_APIENTRY(broker->data.context, "GATResourceBroker_ReserveResource"); GAT_CREATE_STATUS(GATResourceBrokerCPI_ReserveResource(broker->cpi, &broker->data, resource, time_of_start, duration, reservation)); return GAT_RETURN_STATUS(); } return GAT_INVALID_HANDLE; } /** GATResourceBroker_FindResources * @brief Find a list of matching resources. * * The function GATResourceBroker_FindResources tries to find all resources * matching the given description and returns the found resources as a list. * * @param broker The resource broker to use for this operation. * @param description The description to match while searching for resources. * @param resources The pointer to a variable receiving the resulting list of * matching resources. * * @return An error value. */ GATResult GATResourceBroker_FindResources(GATResourceBroker broker, GATResourceDescription_const description, GATList_GATResource *resources) { if (NULL != broker) { GAT_STATUS_APIENTRY(broker->data.context, "GATResourceBroker_FindResources"); GAT_CREATE_STATUS(GATResourceBrokerCPI_FindResources(broker->cpi, &broker->data, description, resources)); return GAT_RETURN_STATUS(); } return GAT_INVALID_HANDLE; } /** GATResourceBroker_SubmitJob * @brief Submit a new job. * * The function GATResourceBroker_SubmitJob submits a new job to the resource * described by the given job description. * * @param broker The resource broker to use for this operation. * @param description The job description containing the information about the * job iteslf and the resource to use. * @param job The pointer to a variable receiving the resulting GATJob object * handle. * * @return An error value. */ GATResult GATResourceBroker_SubmitJob(GATResourceBroker broker, GATJobDescription_const description, GATJob *job) { if (NULL != broker) { GAT_STATUS_APIENTRY(broker->data.context, "GATResourceBroker_SubmitJob"); GATJobDescription desc = NULL; /* create a new GAT jobid */ GATString gatjobid = NULL; GATSelf_const self = GATContext_internal_GetSelf(broker->data.context); GAT_CREATE_STATUS(GATSelf_internal_CreateGATJobId(self, broker->data.context, &gatjobid)); /* add the GAT_JOBID related environment variables for the new job */ GAT_CREATE_STATUS(GATJobDescription_Clone(description, &desc)); GAT_CREATE_STATUS(GATResourceBroker_SetJobEnvironment(broker, desc, gatjobid)); /* submit the job */ GAT_CREATE_STATUS(GATResourceBrokerCPI_SubmitJob(broker->cpi, &broker->data, desc, job)); GATJobDescription_Destroy(&desc); /* associate a new GAT job id with this new job */ GAT_CREATE_STATUS(GATJob_internal_SetGATJobId(*job, gatjobid)); GATString_Destroy(&gatjobid); return GAT_RETURN_STATUS(); } return GAT_INVALID_HANDLE; } /* Local functions */ /* GATResourceBroker_GetCPIInstanceData * * The function GATResourceBroker_GetCPIInstanceData returns the CPI instance data, * associated with the given GATResourceBroker object. * * @param broker 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 GATResourceBroker_GetCPIInstanceData(GATResourceBroker broker, void **data) { if (NULL != broker) { GAT_USES_STATUS(broker->data.context, "GATResourceBroker_GetCPIInstanceData"); if (NULL != data) { *data = (void *)&broker->data; } else { GAT_CREATE_STATUS(GAT_INVALID_PARAMETER); } return GAT_RETURN_STATUS(); } return GAT_INVALID_HANDLE; } /* GATResourceBroker_SetJobEnvironment * * The function GATResourceBroker_SetJobEnvironment sets the GAT_JOBID and * GAT_PARENT_JOBID in the environment of the jobdescription for the job to * spawn. * * @param broker The resource broker to use. * @param description The job description to use for job submission. * @param gatjobid The GAT job id to assign to the new job. * * @return An error code. */ static GATResult GATResourceBroker_SetJobEnvironment(GATResourceBroker broker, GATJobDescription desc, GATJobID_const gatjobid) { if (NULL != broker) { GAT_USES_STATUS(broker->data.context, "GATResourceBroker_SetJobEnvironment"); GATSelf_const self = GATContext_internal_GetSelf(broker->data.context); /* these are references only, do not destroy them ! */ GATJobID_const parent_gatjobid = NULL; GATTable env = NULL; GAT_CREATE_STATUS(GATJobDescription_internal_GetEnvironment(desc, &env)); GAT_CREATE_STATUS(GATTable_Add_String(env, "GAT_JOBID", GATString_GetBuffer(gatjobid))); GAT_CREATE_STATUS(GATSelf_internal_GetGATJobId(self, broker->data.context, &parent_gatjobid)); GAT_CREATE_STATUS(GATTable_Add_String(env, "PARENT_GAT_JOBID", GATString_GetBuffer(parent_gatjobid))); return GAT_RETURN_STATUS(); } return GAT_INVALID_HANDLE; }