[cig-commits] r3991 - in long/3D/Gale/trunk/src/StGermain: . Base/Foundation/src

[walter at geodynamics.org]

Author: walter
Date: 2006-07-09 14:36:21 -0700 (Sun, 09 Jul 2006)
New Revision: 3991

Modified:
   long/3D/Gale/trunk/src/StGermain/
   long/3D/Gale/trunk/src/StGermain/Base/Foundation/src/ObjectAdaptor.h
   long/3D/Gale/trunk/src/StGermain/Base/Foundation/src/ObjectList.h
Log:
 r2495 at earth:  boo | 2006-07-09 14:30:55 -0700
  r2490 at earth (orig r3670):  PatrickSunter | 2006-07-06 20:42:25 -0700
  * Added some documentation about what the functions you
    pass in when creating an ObjectAdaptor or doing a 
    Stg_ObjectList_PointerAppend are supposed to do - 
    especially the potentially-confusing
    Stg_ObjectAdaptor_DeletePointerFunction, which it turns
    out should *not* Memory_Free the object itself, only
    sub-memory allocated (Memory_Free'ing the object
    itself turns out to be a responsibility of the
    ObjectAdaptor wrapper).
  
  Lucky for Valgrind else this could have taken a fair
  while to debug, so hopefully others won't fall into
  the same trap now ;)
  
 



Property changes on: long/3D/Gale/trunk/src/StGermain
___________________________________________________________________
Name: svk:merge
   - 1ef209d2-b310-0410-a72d-e20c9eb0015c:/cig:2494
afb6c753-b9d0-0310-b4e7-dbd8d91cdd35:/trunk/StGermain:3669
   + 1ef209d2-b310-0410-a72d-e20c9eb0015c:/cig:2495
afb6c753-b9d0-0310-b4e7-dbd8d91cdd35:/trunk/StGermain:3670

Modified: long/3D/Gale/trunk/src/StGermain/Base/Foundation/src/ObjectAdaptor.h
===================================================================
--- long/3D/Gale/trunk/src/StGermain/Base/Foundation/src/ObjectAdaptor.h	2006-07-09 21:36:17 UTC (rev 3990)
+++ long/3D/Gale/trunk/src/StGermain/Base/Foundation/src/ObjectAdaptor.h	2006-07-09 21:36:21 UTC (rev 3991)
@@ -53,6 +53,8 @@
 #define __Base_Automation_ObjectAdaptor_h__
 	
 	/** Delete/Print/Copy function prototypes for attached pointers (not StGermain classes) */
+	/** *Note*: this function should only delete extra memory allocated by the object, _not
+	the object itself_ - the ObjectAdaptor wrapper takes responsibility for this */
 	typedef void  (Stg_ObjectAdaptor_DeletePointerFunction)	( void* ptr );
 	typedef void  (Stg_ObjectAdaptor_PrintPointerFunction)	( void* ptr, struct Stream* stream );
 	typedef void* (Stg_ObjectAdaptor_CopyPointerFunction)	( 
@@ -90,7 +92,9 @@
 	void Stg_ObjectAdaptor_InitOfClass( Stg_ObjectAdaptor* self, void* objPtr, Name name, Bool iOwn, Bool isGlobal );
 	
 	
-	/** Create a new Stg_ObjectAdaptor, when the the object is not a StGermain object. */ 
+	/** Create a new Stg_ObjectAdaptor, when the the object is not a StGermain object.
+		See note before Stg_ObjectAdaptor_DeletePointerFunction declaration 
+		about what this function has to be responsible for */ 
 	Stg_ObjectAdaptor* Stg_ObjectAdaptor_NewOfPointer( 
 		void*						dataPtr, 
 		Name						name, 
@@ -100,7 +104,9 @@
 		Stg_ObjectAdaptor_PrintPointerFunction*		ptrPrint,
 		Stg_ObjectAdaptor_CopyPointerFunction*		ptrCopy );
 	
-	/** Initialise a Stg_ObjectAdaptor, when the the object is not a StGermain object. */
+	/** Initialise a Stg_ObjectAdaptor, when the the object is not a StGermain object. 
+		See note before Stg_ObjectAdaptor_DeletePointerFunction declaration 
+		about what this function has to be responsible for */ 
 	void Stg_ObjectAdaptor_InitOfPointer( 
 		Stg_ObjectAdaptor* 				self, 
 		void*						dataPtr, 

Modified: long/3D/Gale/trunk/src/StGermain/Base/Foundation/src/ObjectList.h
===================================================================
--- long/3D/Gale/trunk/src/StGermain/Base/Foundation/src/ObjectList.h	2006-07-09 21:36:17 UTC (rev 3990)
+++ long/3D/Gale/trunk/src/StGermain/Base/Foundation/src/ObjectList.h	2006-07-09 21:36:21 UTC (rev 3991)
@@ -176,7 +176,9 @@
 	/** Append Stg_Class instance to list. Returns the index where the new object was inserted (the last element) */
 	Index Stg_ObjectList_ClassAppend( void* objectList, void* objectPtr, Name name );
 	
-	/** Append C pointer to list. Returns the index where the new object was inserted (the last element) */
+	/** Append C pointer to list. Returns the index where the new object was inserted 
+	(the last element). See notes in ObjectAdaptor.h about the responsibilities of the
+	3 function pointers required - especially the DeletePointer function. */
 	Index Stg_ObjectList_PointerAppend( 
 		void*						objectList, 
 		void*						objectPtr,