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.h Go to the documentation of this file. /** @file GATJob.h * Header 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 Wed Sep 3 2003 * * @version $Header: /export/cvs-gridlab/wp-1/Codes/GATEngine/C-reference/src/GATJob.h,v 1.21 2004/03/24 19:30:58 hartmutkaiser Exp $ * * Copyright (C) Tom Goodale * Copyright (C) Hartmut Kaiser * This file is part of the GAT Engine. * Contributed by * Tom Goodale <goodale@aei.mpg.de> and * 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) */ #if !defined(_GATJOB_H_) #define _GATJOB_H_ /* GAT Header Files */ #include "GAT.h" #include "GATInternal.h" #include "GATMonitorable.h" /* Structures, unions and enums */ #ifdef __cplusplus extern "C" { #endif /* Declare the converters to/from GATObject */ GATOBJECT_DECLARE_CONVERTERS(GATJob); /** 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 thie initialisation of the * new object. * @param preferences The preferences to use wile selecting the adaptor for * the corresponding CPI. * @param jobid The job id of the job to create. * @param initialisation_data Additional initialisation data for the job to + create. * * @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); /** 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); /** 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 location, where the outcome of the * function has to be stored. * * @return An error code. */ GATResult GATJob_Equals(GATJob_const lhs, GATJob_const rhs, GATBool *isequal); /** 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 object, GATJob *new_object); /** 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); /** 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); /* 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 GTAMetricListener 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); /** 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); /** 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 GATMetricListener 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); /** 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); /* GATAdvertiseable API */ #define GATJOB_VERSION1 0x0100 #define GATJOB_LASTVERSION GATJOB_VERSION1 #define GATJOB_MINOR_MASK 0x00ff /** GATResult GATJob_Serialise(GATJob file, GATObject stream, GATBool clear_dirty) * @brief Serialise a GATJob object * * The function GATJob_Serialise serialises the given GATFIle 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); /** 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); /** GATJob_GetIsDirty * * The function GATJob_GetIsDirty retrieves the status of the dirty flag of * this GATJob object. * * @param object 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); /** 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); /** 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); /** 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); /** GATJob_Migrate * * The function GATJob_Migrate provides similar functionality as 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); /** 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); /** 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 pointer to a variable, which should receive the associated * job description. * * @return An error code. */ GATResult GATJob_GetJobDescription(GATJob_const object, GATJobDescription_const *jd); /** 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); /** 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 * the 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); /** 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. * * An exception to this rule is the GATJob object returned from the * GATSelf_GetJob function, which represents the current job. * * @param object The job to get the job id for. * @param jobid The pointer to a variable, which should receive the resulting * GAT job id. * * @return An error code. */ GATResult GATJob_GetJobID(GATJob_const object, GATJobID_const *jobid); /** 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); /** 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); #ifdef __cplusplus } /* extern "C" */ #endif #endif /* !defined(_GATJOB_H_) */