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

GATTimePeriod.c Go to the documentation of this file. /** @file GATTimePeriod.c * Main file for the GATTimePeriod class. * * An instance of this class represents a time duration, a length * of time with uncertain start point. * * @date $Date: 2004/04/02 12:31:58 $ * * @version $Header: /export/cvs-gridlab/wp-1/Codes/GATEngine/C-reference/src/GATTimePeriod.c,v 1.19 2004/04/02 12:31:58 hartmutkaiser Exp $ * * Copyright (C) Kelly Davis * This file is part of the GAT Engine. * Contributed by Kelly Davis <kdavis@aei.mpg.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/GATTimePeriod.c,v 1.19 2004/04/02 12:31:58 hartmutkaiser Exp $"; /* System Header Files */ #include <string.h> #include <stdlib.h> /* GAT Header Files */ #include "GATErrors.h" #include "GATInternal.h" #include "GATTime.h" #include "GATTimePeriod.h" #include "GATXdsWrapper.h" /* Macros */ /* Structures, unions and enums */ /* define the vtable types */ GATOBJECT_DEFINE_VTABLE(GATTimePeriod); GATSERIALISABLE_DEFINE_VTABLE(GATTimePeriod); /* Declare the converters to/from GATObject */ GATOBJECT_DEFINE_CONVERTERS(GATTimePeriod); struct GATTimePeriod_S { GATTimePeriod_vtable *GATObject__vtable; GATTimePeriod_ISerialisable_vtable *GATSerialisable__vtable; GATdouble64 internalDuration; }; /* Static function prototypes */ static GATResult GATTimePeriod_DeSerialise_Create(GATContext context, GATObject stream, GATdouble64 duration, GATTimePeriod *new_object); /* File scope variables */ static GATTimePeriod_vtable GATTimePeriod__vtable = { GATTimePeriod_GetType, GATTimePeriod_Destroy, GATTimePeriod_Equals, GATTimePeriod_Clone, GATTimePeriod_GetInterface, NULL }; static GATTimePeriod_ISerialisable_vtable GATTimePeriod_ISerialisable__vtable = { GATTimePeriod_Serialise, GATTimePeriod_DeSerialise, GATTimePeriod_GetIsDirty, }; /* External functions */ /** GATTimePeriod_Register_GATSerialisable * The GATTimePeriod_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 GATTimePeriod_Register_GATSerialisable(void) { return GATObject_Register_GATSerialisable(GATType_GATTimePeriod, &GATTimePeriod_ISerialisable__vtable); } /** * * This operation constructs a GATTimePeriod instance * corresponding to the passed duration. * * @param duration Number of seconds this period of * time lasts. * @return A GATTimePeriod instance */ GATTimePeriod GATTimePeriod_Create(GATdouble64 duration) { GATTimePeriod newobject = (GATTimePeriod) malloc(sizeof(struct GATTimePeriod_S)); if(NULL != newobject) { newobject->GATObject__vtable = &GATTimePeriod__vtable; newobject->GATSerialisable__vtable = &GATTimePeriod_ISerialisable__vtable; newobject->internalDuration = duration; } return newobject; } /** GATTimePeriod_Create * @brief Create a new GATTimePeriod object * * The function @c GATTimePeriod_Create constructs a GATTimePeriod instance * corresponding to the passed duration. * * @param start The start time to calculate the time period. * @param end The end time to calculate the time period. * * @return Returns a handle to the newly created GATTimePeriod object. * Returns 0 (zero) if an error occurs. */ GATTimePeriod GATTimePeriod_Create_Difference(GATTime start, GATTime end) { GATTimePeriod newobject = NULL; if (NULL != start && NULL != end) { newobject = (GATTimePeriod) malloc(sizeof(struct GATTimePeriod_S)); if(NULL != newobject) { memset(newobject, 0, sizeof(struct GATTimePeriod_S)); newobject->GATObject__vtable = &GATTimePeriod__vtable; newobject->GATSerialisable__vtable = &GATTimePeriod_ISerialisable__vtable; newobject->internalDuration = GATTime_GetTime(end) - GATTime_GetTime(start); } } return newobject; } /** * * Destroys this GATTimePeriod. * * @param this The GATTimePeriod to destroy */ void GATTimePeriod_Destroy(GATTimePeriod *object) { if( (NULL != object) && (NULL != *object) ) { free(*object); *object = NULL; } } /** * This GATTimePeriod, is deemed equal if it has a * numerically equivalent time duration to the passed * GATTimePeriod instance. * * @param this The first GATTimePeriod to query * @param that The second GATTimePeriod to query * @return 1 on equality 0 otherwise */ GATResult GATTimePeriod_Equals(GATTimePeriod_const lhs, GATTimePeriod_const that, GATBool *isequal) { GATResult retval = GAT_INVALID_HANDLE; if( (NULL != lhs) && (NULL != that) ) { if (NULL != isequal) { (*isequal) = (lhs->internalDuration == that->internalDuration) ? GATTrue : GATFalse; retval = GAT_SUCCESS; } else { retval = GAT_INVALID_PARAMETER; } } return retval; } /** * This fucntion returns the type, a #GATType of the passed #GATTimePeriod_const. * This function will always return #GATType_GATTimePeriod. * * @param this The #GATTimePeriod_const to query * @return The #GATType of the passed @c this */ GATType GATTimePeriod_GetType(GATTimePeriod_const this) { GAT_UNUSED_PARAMETER(this); return GATType_GATTimePeriod; } /** * This function returns a "deep clone" of the passed #GATTimePeriod_const @c this. * This "deep clone" is returned in the variable @c thisClone. Furthermore, * this function returns its completion status, through its return value. * * @param this The #GATTimePeriod_const to clone * @param thisClone The cloned #GATTimePeriod_const * @return The completion status of this function */ GATResult GATTimePeriod_Clone(GATTimePeriod_const object, GATTimePeriod *thisClone) { GATResult retval = GAT_INVALID_HANDLE; if (NULL != object) { GATTimePeriod newGATTimePeriod = (GATTimePeriod) malloc( sizeof(struct GATTimePeriod_S) ); if(NULL != newGATTimePeriod) { memset(newGATTimePeriod, 0, sizeof(struct GATTimePeriod_S)); newGATTimePeriod->GATObject__vtable = object->GATObject__vtable; newGATTimePeriod->GATSerialisable__vtable = &GATTimePeriod_ISerialisable__vtable; newGATTimePeriod->internalDuration = object->internalDuration; if (NULL != thisClone) { (*thisClone) = newGATTimePeriod; retval = GAT_SUCCESS; } else { GATTimePeriod_Destroy(&newGATTimePeriod); retval = GAT_INVALID_PARAMETER; } } else { retval = GAT_MEMORYFAILURE; } } return retval; } /** GATResult GATTimePeriod_GetInterface(GATTimePeriod_const file, GATInterface iftype, void const **ifp) * @brief Get an interface supported by a GATObject * * The function GATTimePeriod_GetInterface allows to get a pointer to an * additional interface supported by this GATTimePeriod. * * @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 GATTimePeriod_GetInterface(GATTimePeriod_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; } /* GATAdvertiseable API */ /** GATResult GATTimePeriod_Serialise(GATTimePeriod object, GATObject stream, GATBool clear_dirty) * @brief Serialise a GATTimePeriod object * * The function GATTimePeriod_Serialise serialises the given GATTimePeriod * object into the given stream. * * @param object The GATTimePeriod 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 GATTimePeriod_Serialise(GATTimePeriod object, GATObject stream, GATBool clear_dirty) { GATResult retval = GAT_INVALID_HANDLE; if (NULL != object) { retval = GATXds_SerialiseObject(GATTimePeriod_ToGATObject(object), stream, clear_dirty, 0, "uint32 double_fmt", GATTIMEPERIOD_VERSION1, "%15.6lf", object->internalDuration); } return retval; } /** GATTimePeriod_VersionCallback * * The function GATTimePeriod_VersionCallback is used as a callback function * during the de-serialisation of a GATTimePeriod. 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 GATTimePeriod_VersionCallback(GATuint32 version) { GATBool retval = GATFalse; if ((version & ~GATTIMEPERIOD_MINOR_MASK) <= GATTIMEPERIOD_LASTVERSION) { retval = GATTrue; } return retval; } /** GATTimePeriod_DeSerialiseCallback * * The function GATTimePeriod_DeSerialiseCallback is used as a callback function * during the de-serialisation of a GATTimePeriod. It should be provided for the * instantiation of the new GATTimePeriod 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 * GATTimePeriod_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 GATTimePeriod_DeSerialiseCallback(GATContext context, GATObject stream, GATObject *new_object, GATuint32 version, va_list args) { /* the version was eaten already */ GATdouble64 *duration = va_arg(args, GATdouble64 *); GATTimePeriod object = NULL; /* construct the new object */ GATResult retval = GATTimePeriod_DeSerialise_Create(context, stream, *duration, &object); GAT_UNUSED_PARAMETER(version); if (GAT_SUCCESS == retval) { if (NULL != object) { *new_object = GATTimePeriod_ToGATObject(object); } else { GATTimePeriod_Destroy(&object); retval = GAT_INVALID_PARAMETER; } } return retval; } /** GATTimePeriod GATTimePeriod_DeSerialise(GATContext context, GATObject stream, GATBool clear_dirty) * @brief De-serialise a GATTimePeriod object * * The function GATTimePeriod_DeSerialise de-serialises a streamed * GATTimePeriod 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 GATTimePeriod object. */ GATTimePeriod GATTimePeriod_DeSerialise(GATContext context, GATObject stream, GATResult *result) { GAT_USES_STATUS(context, "GATTimePeriod_DeSerialise"); GATObject object = NULL; /* the new object will be created here */ /* we must provide all instance data items to be de-serialised for this GATTimePeriod object accordingly to the provided format string */ GATuint32 version = 0; GATdouble64 duration = 0; /* read the data */ GAT_CREATE_STATUS(GATXds_DeSerialiseObject(context, stream, GATTimePeriod_DeSerialiseCallback, GATTimePeriod_VersionCallback, &object, "uint32 double", &version, &duration)); if (NULL != result) { *result = GAT_CURRENT_STATUS(); } else { GAT_STORE_STATUS(); } return GATObject_ToGATTimePeriod(object); } /** GATTimePeriod_GetIsDirty * * The function GATTimePeriod_GetIsDirty retrieves the status of the dirty flag of * this GATTimePeriod object. * * @param file The GATTimePeriod object to inspect for its dirty status. * @param isdirty The pointer to a variable, which receives the dirty status. * * @return An error code. */ GATResult GATTimePeriod_GetIsDirty(GATTimePeriod_const object, GATBool *isdirty) { GATResult retval = GAT_INVALID_HANDLE; if (NULL != object) { if (NULL != isdirty) { *isdirty = GATFalse; /* GATTimePeriod is never dirty */ retval = GAT_SUCCESS; } else { retval = GAT_INVALID_PARAMETER; } } return retval; } /* GATTimePeriod API functions */ /** GATTimePeriod_GetDuration * This operation returns the number of seconds this time * period lasts. * * @param this The GATTimePeriod to query * * @return Number of seconds this time period lasts */ GATdouble64 GATTimePeriod_GetDuration(GATTimePeriod_const object) { GATdouble64 retval = 0.; if (NULL != object) { retval = object->internalDuration; } return retval; } /* Local functions */ /** GATTimePeriod_DeSerialise_Create * * The function GATTimePeriod_DeSerialise_Create creates a new GATTimePeriod object. * * @param context The GAT context to use for creation of the GATTimePeriod object. * @param stream The object from which the adaptor should read the streamed * instance data. * @param duration The time duration to be used for the construction of the * new GATTimePeriod object * @param new_object The pointer to the variable, which should receive the * newly constructed GATTimePeriod object. * * @return An error code. */ static GATResult GATTimePeriod_DeSerialise_Create(GATContext context, GATObject stream, GATdouble64 duration, GATTimePeriod *object) { GAT_USES_STATUS(context, "GATTimePeriod_DeSerialise_Create"); GATTimePeriod new_object = (GATTimePeriod) malloc(sizeof(struct GATTimePeriod_S)); GAT_UNUSED_PARAMETER(stream); if(NULL != new_object) { memset(new_object, 0, sizeof(struct GATTimePeriod_S)); new_object->GATObject__vtable = &GATTimePeriod__vtable; new_object->GATSerialisable__vtable = &GATTimePeriod_ISerialisable__vtable; new_object->internalDuration = duration; } else { GAT_CREATE_STATUS(GAT_MEMORYFAILURE); } if (GAT_SUCCEEDED(GAT_CURRENT_STATUS())) { if (NULL != new_object) { *object = new_object; } else { GATTimePeriod_Destroy(&new_object); GAT_CREATE_STATUS(GAT_INVALID_PARAMETER); } } else { GATTimePeriod_Destroy(&new_object); } return GAT_RETURN_STATUS(); }