GObject in GC implementation Plan

[Chris Shoemaker]

On Wed, Mar 21, 2007 at 12:42:32AM -0600, Daniel Espinosa wrote:
> GOBJECT IN GC IMPLEMENTATION PLAN:
> 
> OBJECTIVE
> 
> Get GObject as the base of GC's objects. With the following advantages:
> 	- Get ref counting
> 	- Get signals events
> 
> 
> 
> STATE OF THE ART
> 
> QOF is the object system used by the GC's objects, it has the
> following features:
> 	- Base class Object construction/destruction
> 	- Signal handling
> 	- Type system based on strings
> 	- Objects Properties like system called Parameters
> 
> GC's objects depends directly from QofInstance, witch actually depends
> directly from QofEntity, both QofInstance and QofEntity, are virtual
> objects that means you can't create an instance of them; then the GC's
> objects when created need to init its base class QofInstance and this
> its own QofEntity.
> 
> QofEntity holds the GUID, the unique id for the object, the type of
> the object as a string and a pointer to the QofCollection where this
> entity is stored.
> 
> QofInstance holds pointer to the book it belongs to, and information
> that allows to know the state of the object related to commit to the
> backend.
> 
> The string type system is hard to change for now, then this will need
> be modified in other work; for now is possible to leave it as is,
> because changing to GType means to alter the way of QofBook stores
> objects, QofParam identifies the parameters types, and QofQuery
> identifies the parameters.
> 
> 
> 
> STEPS TO GET GOBJECT
> 
> In order to get GObject as the base class for the GC's objects and get
> its functionalities, we can go though the following options:
> 
> 
> 
> 
> ******OPTION 1: PORT QofEntity TO USE GObject AS BASE CLASS
> 
> Step 1:
> Setup QofEntity, QofInstance and ALL GC's objects to be GObjects in
> order to have a correct construction/destruction process, this will
> ensure a correct refcounting.
> 
> **ADVANTAGES
> Make all in one step and get GObject from the base QOF system.
> 
> **DISADVANTAGES
> Too many changes to be mergable in Trunk.
> 
> 
> 
> 
> 
> *******OPTION 2: PORT QofInstance TO USE GObject AS BASE CLASS
> 
> Step 1:
> Merge QofInstance and QofEntity. This allow to get a single class used
> as the base for the GC's objects.
> 
> Step 2:
> Setup QofInstance and ALL GC's objects to be GObjects and be sure to
> have a correct construction/destruction process, this will ensure a
> correct refcounting.
> 
> **ADVANTAGES
> Make all in few steps and get GObject from the base QOF system.
> Simplify the object class hierarchy.
> 
> **DISADVANTAGES
> Too many changes to be mergable in Trunk.
> 
> 
> 
> 
> *******OPTION 3: PORT GC's OBJECT TO USE GObject AS BASE CLASS
> 
> Step 1: (this step can be done Object by Object, don't need to work in
> all objects at the same time)
> Make the QofInstance member as a Pointer, and allow to create a
> pointer to a QofInstance when the object is created using
> g_object_new. This means:
> 
> 	- Add a new function in QofInstance to allow create an instance,
> setup it and return a pointer to a QofInstance
> 	- No modification in the current QofInstance implementation
> 	- Will need to change all references (JUST in the currently changing
> object) from 'object->inst.[someQofInstanceMember]' to
> 'object->inst->[someQofInstanceMember]'
> 	- Needs to change the definition of QOF_INSTANCE macro to call a
> functions witch returns the QofInstance pointer member of the GC's
> object
> 
> Step 2:
> Setup the currently working object to be a GObject. This means:
> 	- The base class will be GObject not QofInstance
> 	- Other objects, not currently changing, will use the same
> QofInstance base class and its current construction/destruction
> process
> 
> Step 3:
> Merge QofInstance and QofEntity. This allow to get a single base class.
> 
> Step 4:
> Setup QofInstance to be a GObject and be sure to have a correct
> construction/destruction process, this will ensure a correct
> refcounting.
> 
> Step 5:
> Now we can change the base class from GObject to QofInstance in all
> GC's objects.
> 
> **ADVANTAGES
> Get GObject features directly in GC's objects quickly.
> Allows to delay the required modifications in QOF to later steps.
> Allows to modify QOF WITH OUT modify the GC's objects; even is
> possible to work on QOF with out modify the GC's objects, but this
> delay to get GObject in GC
> Once the process in QOF to GObject is finished we can change the base
> class in GC's objects again to QofInstance
> Simplify the object class hierarchy.
> 
> **DISADVANTAGES
> Require to change the base class of the GC's objects from QofInstance
> to GObject.
> Needs to change the code from direct access to the members in
> QofInstance from '.' to '->'.
> 

Changing all the engine objects to include QofInstance by pointer is
bad, so I think that Option 3 is out.

Let's focus on Option 2.

In particular, let's specify exactly what would and wouldn't have to
be changed outside of qof, during this first round of changes.

WOULD CHANGE
------------
* the internal implementation of allocation method, eg. xaccMallocAccount()
would have to internally call g_object_new.
* what else?

WOULDN'T CHANGE
---------------
* the public API of any engine objects, in particular,
  - the QofIdType can be maintained for now as a string member of QofInstance,
    so that it can still be used for QofBook, QofParam, and QofQuery.
* the number and names of all structure members of engine objects.
* what else?

Go ahead and correct/add to these lists, especially the "would
change".  In general, if you can a) avoid changing the external API of
engine objects, and b) keep internal changes to engine objects
minimally invasive, I think Option 2 is fine.

-chris