Digging into the GAT API

Transcription

1 Digging into the GAT API Comparing C, C++ and Python API s Hartmut Kaiser hkaiser@cct.lsu.edu

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 October, 24th 2005 Digging into the GAT API 2

3 Object Orientation - C GAT Specification is object oriented What s an Object Some data and a set of related functions Representation in C Internal struct GATFile_S { /* */ }; External typedef struct GATFile_S *GATFile; Constructor/Destructor GATFile_Create(), GATFile_Destroy() Naming convention GATResult GATFile_Copy(GATFile, /* */); October, 24th 2005 Digging into the GAT API 3

4 Object Orientation C++ Separate namespaces: GAT (GAT::Adaptors) Defines reference counted wrappers on top of the C API Natural representation Create new GAT object GAT::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(/* */); October, 24th 2005 Digging into the GAT API 4

5 Object Orientation Python Separate namespaces (modules): GAT (GAT.Adaptors) Defines Python classes on top of the C API Representation is natural Create new GAT object file = GAT.File(name) // constructor, destructor Wrapping not necessary, done by the PyGAT runtime (which is written in C/C++) Naming convention: GATResult GATFile_Copy(GATFile, /* */); GAT.Result GAT.File.Copy(/* */) October, 24th 2005 Digging into the GAT API 5

6 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 of function pointers, one table for each interface GetInterface(): helper function to get at the different function pointer tables October, 24th 2005 Digging into the GAT API 6

7 GATFile Memory Layout GATFile file = ; GAT Engine Code GATFile Instance data GATObject vtbl ptr GATSerialisable vtbl ptr... GATFile data GATFile Object vtbl GetType _ptr GetInterface _ptr Equals _ptr Clone_ptr Destroy _ptr GATFile Serialisable vtbl Serialise _ptr Deserialise _ptr GetIsDirty _ptr GATFile _GetType GATFile _GetInterface GATFile _Equals GATFile _Clone GATFile _Destroy GATFile _Serialise GATFile _Deserialise GATFile _GetIsDirty October, 24th 2005 Digging into the GAT API 7

8 Interfaces C++ Implemented through static polymorphism and multiple inheritance from different base class templates (GAT::Streamable<>, GAT::Serialisable<>, GAT::Monitorable<> etc.) October, 24th 2005 Digging into the GAT API 8

9 Interfaces Python All classes simply have interface functions available, no derivation needed (although internally used for the implementation) Integration of serialisation into the Python language (pickling). October, 24th 2005 Digging into the GAT API 9

10 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 *); October, 24th 2005 Digging into the GAT API 10

11 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 GATObject_const GATFile_ToGATObject(GATFile); GATFile_ToGATObject_const(GATFile_const); Succeeds only, if type matches: GATFile GATObject_ToGATFile(GATObject); GATFile_const GATObject_ToGATFile_const(GATObject_const); October, 24th 2005 Digging into the GAT API 11

12 Derivation C++ Representation in C++ Every GAT++ object type is derived from the GAT::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 October, 24th 2005 Digging into the GAT API 12

13 Derivation - Python Representaion in Python Every GAT.<Object> has a similar set of functions implemented: GAT.File.GetType() GAT.File.Clone() GAT.File. cmp () Typeless language, no conversion problems, handled by PyGAT wrapper runtime October, 24th 2005 Digging into the GAT API 13

14 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 interface GATResult GATFile_Serialise(GATFile file, GATObject stream, GATBool cleardirty); Generic function allowing to call the type specific function GATResult GATSerialisable_Serialise(GATObject object, GATObject stream, GATBool cleardirty); October, 24th 2005 Digging into the GAT API 14

15 Genericity C++ Representation in C++ Works based on the inheritance scheme October, 24th 2005 Digging into the GAT API 15

16 Genericity Python No special support needed for that (Python is typeless) October, 24th 2005 Digging into the GAT API 16

17 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 created GATFile 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); October, 24th 2005 Digging into the GAT API 17

18 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 without performance harm. But watch out! Don t free any of these objects while you 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 result refers to the same object, so don t free twice. October, 24th 2005 Digging into the GAT API 18

19 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(...); GAT::File file2 = file; // creates C object Underlying C handle get s free d only after file1 and file2 are destructed No need for explicit destruction, language (compiler) keeps track of that October, 24th 2005 Digging into the GAT API 19

20 Memory Management Python The PyGAT objects handle all memory management issues (Python is reference counted/garbage collected) You re free to copy around those objects without performance harm. file1 = GAT.File(...); file2 = file; // creates C object Underlying C handle get s free d only after file1 and file2 are out of scope and got garbage collected Runtime keeps track of not needed instances October, 24th 2005 Digging into the GAT API 20

21 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 given back from the engine, which are not const Objects and memory blocks which are const are controlled by the GAT 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; October, 24th 2005 Digging into the GAT API 21

22 Const correctness C++ Const correctness introduced wherever possible, allows compiler to catch errors early Natural representation in C++ GAT::File, GAT::File const October, 24th 2005 Digging into the GAT API 22

23 Const correctness - Python Const correctness not an issue (not supported by the language) October, 24th 2005 Digging into the GAT API 23

24 Error Handling Every method (except constructor, destructor and certain simple accessors) return a GATResult value Is a structured 32 bit unsigned int: Severity Client Reserved Facility Error Code Every CPI based object has additional error tracking inside the associated GAT Context: Allows to print an error trace back of the full error history GATContext_GetCurrentStatus(context, &status); GATStatus_ErrorTrace(status); October, 24th 2005 Digging into the GAT API 24

25 Error Handling (Explicit) - C #include <GAT.h> GATResult RemoteFile_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; } October, 24th 2005 Digging into the GAT API 25

26 Error Handling (macros) - C #include <GAT.h> GATResult RemoteFile_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(); } October, 24th 2005 Digging into the GAT API 26

27 Error Handling C++ #include <GAT.hpp> GAT::Result RemoteFile_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; October, 24th 2005 Digging into the GAT API 27

28 Error Handling Python import GAT def 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; October, 24th 2005 Digging into the GAT API 28

29 Demo File Transfer Application Using different languages (C, C++, Python) October, 24th 2005 Digging into the GAT API 29