lecture 15 digging into the gat api · october, 24th 2005 digging into the gat api 5 object...

Digging into the GAT APIComparing C, C++ and Python API‘s

Hartmut [email protected]

http://www.cct.lsu.edu/~gallen/Teaching

October, 24th 2005 Digging into the GAT API 2

Digging into the GAT API• Design Principles

– Object orientation• Derivation, Interfaces, Genericity

– Memory Management• Object lifetime, Instance tracking, Allocation

responsibilities– Const Correctness– Error Handling


Object Orientation - C• GAT Specification is object oriented• What’s an ‘Object’

– Some data and a set of related functions• Representation in C

– Internalstruct GATFile_S { /*…*/ };

– Externaltypedef struct GATFile_S *GATFile;

– Constructor/DestructorGATFile_Create(), GATFile_Destroy()

– Naming conventionGATResult GATFile_Copy(GATFile, /*…*/);


Object Orientation – C++• Separate namespaces: GAT (GAT::Adaptors)• Defines reference counted wrappers on top

of the C API• Natural representation

– Create new GAT objectGAT::File file(name); // constructor, destructor

– Wrap existing C objects (handles)GAT::File file = GAT::MakeFile(c_file);

• Naming convention:GATResult GATFile_Copy(GATFile, /*…*/);GAT::Result GAT::File::Copy(/*…*/);


Object Orientation – Python• Separate namespaces (modules): GAT

(GAT.Adaptors)• Defines Python classes on top of the C API• Representation is natural

– Create new GAT objectfile = GAT.File(name) // constructor, destructor

– Wrapping not necessary, done by the PyGATruntime (which is written in C/C++)

• Naming convention:GATResult GATFile_Copy(GATFile, /*…*/);GAT.Result GAT.File.Copy(/*…*/)


Interfaces - C• Certain GAT object types have to implement

different interfaces (GATObject, GATStreamable,GATMonitorable)

• What’s an interface– A set of related functions, which may be called even not

knowing the type of the object• Representation in C

– Emulation of virtual functions. Every object has a table offunction pointers, one table for each interface

– GetInterface(): helper function to get at the differentfunction pointer tables


GATFile Memory Layout

GATFile _Destroy

GATFile _Clone

GATFile _Equals

GATFile _GetInterface

GATFile _GetType

Code

GetType _ptr

GetInterface _ptr

Equals _ptr

Clone_ptr

Destroy _ptr

GATFile Object vtbl

Serialise _ptr

Deserialise _ptr

GetIsDirty _ptr

GATFile Serialisable vtbl

GATFile _GetIsDirty

GATFile _Deserialise

GATFile _Serialise

GATObject vtbl ptr

GATSerialisable vtbl ptr

...

GATFile data

GATFile Instance data

GATFile file = …;

GAT Engine


Interfaces – C++• Implemented through static polymorphism

and multiple inheritance from different baseclass templates (GAT::Streamable<>,GAT::Serialisable<>, GAT::Monitorable<> etc.)


Interfaces – Python• All classes simply have interface functions

available, no derivation needed (althoughinternally used for the implementation)

• Integration of serialisation into the Pythonlanguage (pickling).


Derivation - C• Every GAT object type has to be derived from the

GATObject• What’s ‘Derivation’

– Reuse of common functionality– Conversion from and to GATObject should be possible

• Representation in C– Every GAT object type has a common set of functions with

an identical signature

GATType GATFile_GetType(GATFile_const);GATResult GATFile_Destroy(GATFile *);GATResult GATFile_Clone(GATFile_const, GATFile *);GATResult GATFile_GetInterface(GATFile_const, void **);GATResult GATFile_Equals(GATFile_const, GATFile_const, GATBool *);


Derivation - C• Conversion from any GAT type to GATObject should

be possible, since all these ‘derived’ from GATObject.• Conversion from GATObject to the corresponding

GAT type should be possible as well.• Representation in C

– For every GAT type the following functions exist:• Succeeds always:

GATObject GATFile_ToGATObject(GATFile);GATObject_const GATFile_ToGATObject_const(GATFile_const);

• Succeeds only, if type matches:

GATFile GATObject_ToGATFile(GATObject);GATFile_const GATObject_ToGATFile_const(GATObject_const);


Derivation – C++• Representation in C++

– Every GAT++ object type is derived from theGAT::Object<Derived> template:

GAT::Type GAT::Object<Derived>::GetType(Derived const);

GAT::Object<Derived>::Object(Derived const);bool GAT::Object<Derived>::operator==(Derived const);

– Conversion is handled automatically by derivation


Derivation - Python• Representaion in Python

– Every GAT.<Object> has a similar set of functionsimplemented:

GAT.File.GetType()GAT.File.Clone()GAT.File.__cmp__()

– Typeless language, no conversion problems, handledby PyGAT wrapper runtime


Genericity - C• Possibility to call a function for an arbitrary

GAT type not knowing the concrete type• Representation in C

– For every interface function exists• Concrete function implementation for every GAT type,

which realises this interfaceGATResultGATFile_Serialise(GATFile file, GATObject stream, GATBool cleardirty);

• Generic function allowing to call the type specificfunctionGATResultGATSerialisable_Serialise(GATObject object, GATObject stream, GATBool

cleardirty);


Genericity – C++

• Representation in C++– Works based on the inheritance scheme


Genericity – Python• No special support needed for that (Python is

typeless)


Memory Management - C• All GAT object types have a …_Create() function,

which returns a new instance of this type.• All GAT object types have a …_Destroy function,

which frees all associated memory.• You are responsible to call …_Destroy!

– for all objects you’ve createdGATFile file = GATFile_Create(location);… /* do something useful with ‘file’ */GATFile_Destroy(&file);

– for all non const objects you get back from the engine

GATPipe pipe = NULL;GATEndpoint_Connect(endpoint, &pipe);… /* do something useful with ‘pipe’ */GATPipe_Destroy(&pipe);


Memory Management - C• The GAT objects returned from the engine are

handles! (well actually pointers, but …)typedef struct GATFile_S * GATFile;

• You’re free to copy around those ‘objects’ withoutperformance harm.

• But watch out! Don’t free any of these objects whileyou’re holding copies of it, which you still want to use.

• Never free a GATObject with free().• If you are using casting functions (as

GATObject_ToGATFile) please note, that the resultrefers to the same object, so don’t free twice.


Memory Management – C++• The GAT++ objects handle all memory

management issues (reference counted)• You’re free to copy around those objects

without performance harm.GAT::File file1(...); // creates C ‚object‘GAT::File file2 = file;

• Underlying C handle get‘s free‘d only afterfile1 and file2 are destructed

• No need for explicit destruction, language(compiler) keeps track of that


Memory Management – Python• The PyGAT objects handle all memory management

issues (Python is reference counted/garbagecollected)

• You’re free to copy around those objects withoutperformance harm.

file1 = GAT.File(...); // creates C ‚object‘file2 = file;

• Underlying C handle get‘s free‘d only after file1 andfile2 are out of scope and got garbage collected

• Runtime keeps track of not needed instances


Const correctness - C• Const correctness introduced wherever possible• Helps to enforce semantics, especially for memory management

– You’ll have to free by yourself all objects and memory blocks givenback from the engine, which are not const

– Objects and memory blocks which are const are controlled by theGAT engine, you don’t want to free these

• Representation in C– First temptation to have: GATFile and GATFile const but this

doesn’t give, what we want:

typedef struct GATFile_S * GATFile;

so ‚GATFile‘ const would be ‚GATFile_S * const‘ --- wrong!

– As a result we’ve got:

typedef struct GATFile_S * GATFile;typedef struct GATFile_S const * GATFile_const;


Const correctness – C++• Const correctness introduced wherever

possible, allows compiler to catch errors early• Natural representation in C++

GAT::File, GAT::File const


Const correctness - Python• Const correctness not an issue (not supported

by the language)


Error Handling• Every method (except constructor, destructor and

certain simple accessors) return a GATResult value– Is a structured 32 bit unsigned int:

• Every CPI based object has additional error trackinginside the associated GAT Context:– Allows to print an error trace back of the full error history

GATContext_GetCurrentStatus(context, &status);GATStatus_ErrorTrace(status);

7 015 81631 27282930

Seve

rity

Clie

nt

Res

erv

ed

Faci

l ity

Err

or

Code


Error Handling (Explicit) - C#include <GAT.h>GATResultRemoteFile_GetFile (GATContext context, char const *source_url, char const *target_url){ GATResult rc = GAT_FAIL; GATStatus status = NULL; GATLocation source = GATLocation_Create (source_url); GATLocation target = GATLocation_Create (target_url); GATFile file = GATFile_Create (context, source, NULL); if (NULL == source || NULL == target || NULL == file) { GATCreateStatus(“RemoteFile_GetFile”, &status, GAT_MEMORYFAILURE, context,

__FILE__, __LINE__); return GATContext_SetCurrentStatus (context, &status); } rc = GATFile_Copy(file, target, GATFileMode_Overwrite); if (GAT_FAILED(rc)) { GATCreateStatus(“RemoteFile_GetFile”, &status, rc, context, __FILE__, __LINE__); return GATContext_SetCurrentStatus (context, &status); } GATFile_Destroy (&file); GATLocation_Destroy (&target); GATLocation_Destroy (&source); return GAT_SUCCEEDED;}


Error Handling (macros) - C#include <GAT.h>GATResultRemoteFile_GetFile (GATContext context, char const *source_url, char const *target_url){ GAT_USES_STATUS(context, “RemoteFile_GetFile”);

GATLocation source = GATLocation_Create (source_url); GATLocation target = GATLocation_Create (target_url); GATFile file = GATFile_Create (context, source, NULL);

if (NULL == source || NULL == target || NULL == file) { GAT_CREATE_STATUS(GAT_MEMRORYFAILURE); } else { GAT_CREATE_STATUS(GATFile_Copy(file, target, GATFileMode_Overwrite)); }

GATFile_Destroy (&file); GATLocation_Destroy (&target); GATLocation_Destroy (&source);

return GAT_RETURN_STATUS();}


Error Handling – C++#include <GAT.hpp>GAT::ResultRemoteFile_GetFile (GAT::Context context, char const *source_url,

char const *target_url){ try { GAT::Location source (source_url); GAT::Location target (target_url); GAT::File file (context, source);

file.Copy(target); } catch (GAT::Exception const &e) { std::cout << e.what() << std::endl; return e.GetResult(); } return GAT_SUCCEEDED;}


Error Handling – Pythonimport GATdef RemoteFile_GetFile (context, source_url, target_url): try: source = GAT.Location(source_url); target = GAT.Location(target_url); file = GAT.File(context, source);

file.Copy(target);

except GAT.Status, err: print err.args[0].message print err.args[0].traceback return err.args[0].errcode

return GAT.SUCCEEDED;


Demo• File Transfer Application

– Using different languages (C, C++, Python)

lecture 15 digging into the gat api · october, 24th 2005 digging into the gat api 5 object...

Documents