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

GATObject.c Go to the documentation of this file. /** @file GATObject.c.cpp * Source file for the GATObject class. * * This file contains mostly generic implementations of the different * interfaces used throughout the GAT engine. * * @date Fri Oct 10 2003 * * @version $Header: /export/cvs-gridlab/wp-1/Codes/GATEngine/C-reference/src/GATObject.c,v 1.34 2004/04/18 18:35:10 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/GATObject.c,v 1.34 2004/04/18 18:35:10 hartmutkaiser Exp $"; /* System Header Files */ #include "xds_p.h" /* GAT Header Files */ #include "GAT.h" #include "GATInternal.h" #include "GATInterfaceMap.h" /* Macros */ /* structs and typedefs */ /* define the vtable types */ GATOBJECT_DEFINE_VTABLE(GATObject); GATSERIALISABLE_DEFINE_VTABLE(GATObject); GATSTREAMABLE_DEFINE_VTABLE(GATObject); GATMONITORABLE_DEFINE_VTABLE(GATObject); GATRESOURCE_DEFINE_VTABLE(GATObject); /* the following data structures are used as a placeholder for the real object structures */ struct GATObject_S { GATObject_vtable *__vtable; }; struct GATSerialise_S { GATObject_ISerialisable_vtable *__vtable; }; struct GATStreamable_S { GATObject_IStreamable_vtable *__vtable; }; struct GATMonitorable_S { GATObject_IMonitorable_vtable *__vtable; }; struct GATResource_S { GATObject_IResource_vtable *__vtable; }; /* Static function prototypes */ /* File scope variables */ /* External functions */ /** GATType GATObject_GetType(GATObject const object) * @brief Get the type from a GATObject * * The function GATObject_GetType implements a generic way to return the * actual type of a given GATObject. * * @param object The GATObject, for which its type has to be returned * * @return The @c #GATType of the object under inspection */ GATType GATObject_GetType(GATObject_const object) { GATType retval = GATType_NoType; if (NULL != object) { retval = object->__vtable->get_type(object); } return retval; } /** void GATObject_Destroy(GATObject *object) * @brief Destroy a GATObject * * The function GATObject_Destroy implements a generic way to destroy an * arbitrary GATObject. * * @param object The GATObject, which has to be destroyed. */ void GATObject_Destroy(GATObject *object) { if (NULL != object && NULL != *object) (*object)->__vtable->destroy(object); } /** int GATObject_Equals(GATObject const lhs, GATObject const rhs, GATBool *isequal) * @brief Compare to GATObject's * * The function GATObject_Equals allows to compare generically two arbitrary * GATObject's. * * @param lhs The first GATObject to compare. * @param rhs The second GATObject to compare. * @param isequal The pointer, through which the result is to be returned. * * @result An error code. */ GATResult GATObject_Equals(GATObject_const lhs, GATObject_const rhs, GATBool *isequal) { GATResult retval = GAT_INVALID_HANDLE; if (NULL != lhs && NULL != rhs) { if (lhs->__vtable->get_type(lhs) != rhs->__vtable->get_type(rhs)) { if (NULL == isequal) { retval = GAT_INVALID_PARAMETER; } else { *isequal = GATFalse; } } else { retval = lhs->__vtable->equals(lhs, rhs, isequal); } } return retval; } /** int GATObject_Clone(GATObject const object, GATObject *new_object) * @brief Clone a GATObject * * The function GATObject_Clone allows to get a exact copy of an arbitrary * GATObject. If the object to copy is a container object (i.e. GATTable, * GATList or similar), all the contained therein elements are copied too. * * @param object The object to be copied. * @param new_object The pointer, through which the result is to be returned. * * @return An error type. */ GATResult GATObject_Clone(GATObject_const object, GATObject *new_object) { GATResult retval = GAT_INVALID_HANDLE; if (NULL != object) { retval = object->__vtable->clone(object, new_object); } return retval; } /** int GATObject_GetInterface(GATObject_const object, GATInterface iftype, void const **ifp) * @brief Get an interface supported by a GATObject * * The function GATObject_GetInterface allows to get a pointer to an * additional interface supported by this GATObject. * * @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 GATObject_GetInterface(GATObject_const object, GATInterface iftype, void const **ifp) { GATResult retval = GAT_INVALID_HANDLE; if (NULL != object) { if (NULL != object->__vtable->get_interface) { retval = object->__vtable->get_interface(object, iftype, ifp); } else { retval = GAT_NOTIMPL; } } return retval; } /** GATObject_GetCPIInstanceData * @brief Get an the CPI instance dat associated with this CPI object. * * The function GATObject_GetCPIInstanceData allows to get a pointer to the * CPI instance data associated with the give object. Note, that this function * returns meaningful result only for CPI objects. * * @param object The object to be asked for the new interface. * @param data The pointer to a variable, which should receive the reuslting * CPI instance data. * * @return An error type. */ GATResult GATObject_GetCPIInstanceData(GATObject object, void **data) { GATResult retval = GAT_INVALID_HANDLE; if (NULL != object) { if (NULL != object->__vtable->get_instancedata) { retval = object->__vtable->get_instancedata(object, data); } else { retval = GAT_NOTIMPL; // this is no CPI object } } return retval; } /* Helper functions needed for proper generic type conversion */ GATObject GATObject_ToGATObject(GATObject object) { return object; } GATObject_const GATObject_ToGATObject_const(GATObject_const object) { return object; } /* Generic GATSerialise interface definition for GATObject's */ /** int GATSerialisable_Serialise(GATObject object, GATObject stream, GATBool clear_dirty) * @brief Serialise a GATObject object * * The function GATSerialisable_Serialise serialises the given GATObject object into * the given stream in a generic way. * * @param object The GATObject 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. * * @return An error code. */ GATResult GATSerialisable_Serialise(GATObject object, GATObject stream, GATBool clear_dirty) { GATSerialise serialise = NULL; GATResult retval = GATObject_GetInterface(object, GATInterface_ISerialisable, (void const **) &serialise); if (GAT_SUCCESS == retval) { if (NULL != serialise->__vtable->serialise) { /* write the type of the object to the stream */ GATuint32 type = GATObject_GetType(object); retval = GATuint32_Serialise(type, stream); if (GAT_SUCCESS == retval) { /* serialize the object itself */ retval = serialise->__vtable->serialise(object, stream, clear_dirty); } } else { retval = GAT_NOTIMPL; } } return retval; } /** GATObject GATSerialisable_DeSerialise(GATContext context, GATObject stream, GATBool clear_dirty) * @brief De-serialise a GATObject object * * The function GATSerialisable_DeSerialise de-serialises a streamed GATObject * object from the given stream in a generic way. 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 object. */ GATObject GATSerialisable_DeSerialise(GATContext context, GATObject stream, GATResult *result) { /* read back the type of the GATObject to deserialise */ GATObject new_object = NULL; GATuint32 type = GATType_NoType; GATResult retval = GATuint32_DeSerialise(stream, &type); if (GAT_SUCCESS == retval) { /* try to find the serialisation vtable of the given object type */ GATObject_ISerialisable_vtable *vtable = NULL; retval = GATObject_Get_GATSerialisable((GATType)type, &vtable); if (GAT_SUCCESS == retval) { new_object = vtable->deserialise(context, stream, &retval); } } if (GAT_SUCCESS != retval) { GATObject_Destroy(&new_object); } if (NULL != result) { *result = retval; } return new_object; } /** int GATSerialisable_GetIsDirty(GATObject_const object, GATBool *isdirty) * @brief Return the status of the dirty flag of an object * * The function GATSerialisable_GetIsDirty retrieves the status of the dirty flag of * an object in a generic way. * * @param object The GATObject object to ask for its dirty status. * @param isdirty The pointer to a variable, which receives the dirty status. * * @return An error code. */ GATResult GATSerialisable_GetIsDirty(GATObject_const object, GATBool *isdirty) { GATSerialise serialise = NULL; GATResult retval = GATObject_GetInterface(object, GATInterface_ISerialisable, (void const **) &serialise); if (GAT_SUCCESS == retval) { if (NULL != serialise->__vtable->isdirty) { /* ask the object itself */ retval = serialise->__vtable->isdirty(object, isdirty); } else { retval = GAT_NOTIMPL; } } return retval; } /* generic GATStreamable support */ /** int GATStreamable_Read(GATObject object, void *buffer, GATuint32 size, GATuint32 *read_bytes) * @brief Read a given amount of bytes from the given stream * * The function GATStreamable_Read tries to read from the given stream the * given amount of data in a generic way. * * @param object The object, which GATStreamable interface to use to access * the stream * @param buffer The buffer to read the data to. * @param size The size of the buffer (maximum amount of data to read). * @param read_bytes The pointer to a variable, which receives the number of * bytes, actually returned in the buffer. This value is valid only, if * no error occurs (optional, may be zero). * * @return An error code. */ GATResult GATStreamable_Read(GATObject object, void *buffer, GATuint32 size, GATuint32 *read_bytes) { GATStreamable stream = NULL; GATResult retval = GATObject_GetInterface(object, GATInterface_IStreamable, (void const **) &stream); if (GAT_SUCCESS == retval) { if (NULL != stream->__vtable->sread) { /* delegate to the object itself */ retval = stream->__vtable->sread(object, buffer, size, read_bytes); } else { retval = GAT_NOTIMPL; } } return retval; } /** int GATStreamable_Write(GATObject object, void const *buffer, GATuint32 size, GATuint32 *written_bytes) * @brief Writes a given amount of bytes to the given stream * * The function GATStreamable_Write tries to write to the given stream the * given amount of data in a generic way. * * @param object The object, which GATStreamable interface to use to access * the stream * @param buffer The buffer containing the data to write to the stream. * @param size The size of the buffer (amount of data to write). * @param written_bytes The pointer to a variable, which receives the number * of bytes actually written. This value is valid only, if * no error occurs (optional, may be zero). * * @return An error code. */ GATResult GATStreamable_Write(GATObject object, void const *buffer, GATuint32 size, GATuint32 *written_bytes) { GATStreamable stream = NULL; GATResult retval = GATObject_GetInterface(object, GATInterface_IStreamable, (void const **) &stream); if (GAT_SUCCESS == retval) { if (NULL != stream->__vtable->swrite) { /* delegate to the object itself */ retval = stream->__vtable->swrite(object, buffer, size, written_bytes); } else { retval = GAT_NOTIMPL; } } return retval; } /** int GATStreamable_Seek(GATObject object, GATOrigin origin, GATint32 offset, GATuint32 *new_position) * @brief Writes a given amount of bytes to the given stream * * The function GATStreamable_Write tries to write to the given stream the * given amount of data in a generic way. * * @param object The object, which GATStreamable interface to use to access * the stream * @param origin The point inside the stream, relative to which the pointer * positioning is to be done. * @param offset The amount of bytes the logical position inside the stream * is to be moved. * @param new_position The pointer to a variable, which receives the new * logical position inside the stream object (optional, may be zero). * * @return An error code. */ GATResult GATStreamable_Seek(GATObject object, GATOrigin origin, GATint32 offset, GATuint32 *new_position) { GATStreamable stream = NULL; GATResult retval = GATObject_GetInterface(object, GATInterface_IStreamable, (void const **) &stream); if (GAT_SUCCESS == retval) { if (NULL != stream->__vtable->seek) { /* delegate to the object itself */ retval = stream->__vtable->seek(object, origin, offset, new_position); } else { retval = GAT_NOTIMPL; } } return retval; } /* generic GATMonitorable interface */ GATResult GATMonitorable_AddMetricListener(GATObject object, GATMetricListener listener, void *listener_data, GATMetric metric, GATuint32 *cookie) { GATMonitorable monitorable = NULL; GATResult retval = GATObject_GetInterface(object, GATInterface_IMonitorable, (void const **) &monitorable); if (GAT_SUCCESS == retval) { if (NULL != monitorable->__vtable->addlistener) { /* delegate to the object itself */ retval = monitorable->__vtable->addlistener(object, listener, listener_data, metric, cookie); } else { retval = GAT_NOTIMPL; } } return retval; } GATResult GATMonitorable_RegisterPolling(GATObject object, GATMetric metric, GATMetricEvent *event, GATuint32 *cookie) { GATMonitorable monitorable = NULL; GATResult retval = GATObject_GetInterface(object, GATInterface_IMonitorable, (void const **) &monitorable); if (GAT_SUCCESS == retval) { if (NULL != monitorable->__vtable->registerpolling) { /* delegate to the object itself */ retval = monitorable->__vtable->registerpolling(object, metric, event, cookie); } else { retval = GAT_NOTIMPL; } } return retval; } GATResult GATMonitorable_RemoveRegisteredMetric(GATObject object, GATMetric metric, GATuint32 cookie) { GATMonitorable monitorable = NULL; GATResult retval = GATObject_GetInterface(object, GATInterface_IMonitorable, (void const **) &monitorable); if (GAT_SUCCESS == retval) { if (NULL != monitorable->__vtable->removemetric) { /* delegate to the object itself */ retval = monitorable->__vtable->removemetric(object, metric, cookie); } else { retval = GAT_NOTIMPL; } } return retval; } GATResult GATMonitorable_GetMetrics(GATObject_const object, GATList_GATMetric *metrics) { GATMonitorable monitorable = NULL; GATResult retval = GATObject_GetInterface(object, GATInterface_IMonitorable, (void const **) &monitorable); if (GAT_SUCCESS == retval) { if (NULL != monitorable->__vtable->getmetrics) { /* delegate to the object itself */ retval = monitorable->__vtable->getmetrics(object, metrics); } else { retval = GAT_NOTIMPL; } } return retval; } /* generic GATResource access support */ GATResult GATResource_GetResourceDescription(GATObject_const object, GATResourceDescription_const *description) { GATResource resource = NULL; GATResult retval = GATObject_GetInterface(object, GATInterface_IResource, (void const **) &resource); if (GAT_SUCCESS == retval) { if (NULL != resource->__vtable->getresourcedescription) { /* delegate to the object itself */ retval = resource->__vtable->getresourcedescription(object, description); } else { retval = GAT_NOTIMPL; } } return retval; } GATResult GATResource_GetReservation(GATObject_const object, GATReservation_const *reservation) { GATResource resource = NULL; GATResult retval = GATObject_GetInterface(object, GATInterface_IResource, (void const **) &resource); if (GAT_SUCCESS == retval) { if (NULL != resource->__vtable->getreservation) { /* delegate to the object itself */ retval = resource->__vtable->getreservation(object, reservation); } else { retval = GAT_NOTIMPL; } } return retval; } /* Serialize primitive data items */ /** int GATuint32_Serialise(GATuint32 data, GATObject stream) * * The GATuint32_Serialise function serialises a GATuint32 value into the * given stream. * * @param data The GATuint32 data item to serialise (write). * @param stream The stream to use for serialisation. * * @return An error code. */ GATResult GATuint32_Serialise(GATuint32 data, GATObject stream) { GATResult retval = GAT_FAIL; xds_t *xds = NULL; void *xds_buffer = NULL; GATuint32 xds_buffer_size = 0; if (XDS_OK == (retval = xds_init(&xds, XDS_ENCODE)) && XDS_OK == (retval = xds_register(xds, "uint32", &xml_encode_uint32, NULL)) && XDS_OK == (retval = xds_encode(xds, "uint32", data)) && XDS_OK == (retval = xds_getbuffer(xds, XDS_GIFT, &xds_buffer, (size_t *) &xds_buffer_size))) { assert(NULL != xds_buffer); retval = GATStreamable_Write(stream, xds_buffer, xds_buffer_size, 0); } else { retval = XDS_TO_GAT(retval); } xds_destroy(xds); free(xds_buffer); return retval; } /** int GATuint32_DeSerialize(GATuint32 data, GATObject stream) * * The GATuint32_DeSerialize function de-serialises a GATuint32 value into the * given stream. * * @param stream The stream to use for serialisation. * @param data The GATuint32 data item to de-serialise (read). * * @return An error code. */ GATResult GATuint32_DeSerialise(GATObject stream, GATuint32 *data) { char buffer[64]; /* seems to be sufficient for a GATuint32 value */ GATuint32 xds_read_bytes = 0; GATResult retval = GATStreamable_Read(stream, buffer, sizeof(buffer), &xds_read_bytes); if (GAT_SUCCESS == retval) { xds_t *xds = NULL; if (XDS_OK == (retval = xds_init (&xds, XDS_DECODE)) && XDS_OK == (retval = xds_register ( xds, "uint32", &xml_decode_uint32, NULL)) && XDS_OK == (retval = xds_setbuffer ( xds, XDS_LOAN, buffer, sizeof(buffer))) && XDS_OK == (retval = xds_decode ( xds, "uint32", data))) { retval = GATStreamable_Seek (stream, GATOrigin_Current, xds->buffer_len - xds_read_bytes, 0); } else { retval = XDS_TO_GAT(retval); } xds_destroy(xds); } return retval; } /* local functions */