Bonobo component reference counting, version 0.1 by Michael Meeks and Mike Fleming * Bonobo Objects A bonobo object is a gtk object that implements an CORBA interface, it also contains a pointer to the BonoboAggregateObject that it is part of. A bonobo object has two reference counts; the first is a GtkObject reference count on the object. This should be 1 at all times except pre-finalization. The main reference count for the aggregate is stored in the typedef struct { int ref_count; GList *objs; } BonoboAggregateObject; structure. Also in this structure is a list of all the objects implementing other interfaces in this aggregate. Clearly an object is always in its own aggregate hence: g_assert (g_list_find (object->priv->ao->objs, object) == object); Is always true. The object->priv->ao dereference is merely a nice way of encapsulating this information inside bonobo-object.c and ensuring that it can't be fiddled with elsewhere. * Ref counting The only ref count to manipulate is that on the aggregate obejct, this is done via the bonobo_object_ref / unref pair, it is also done remotely via the Bonobo_Object_ref / unref CORBA stubs. There is no 'destroy' method, if you want this method you are probably confused about how Gtk+ deals with allocation. Some people try to use gtk_object_ref / unref on BonoboObjects; sadly this will cause very serious grief. This if you gtk_object_unref a bonobo object, then that object will be destroyed without consulting the aggregate ref-count, and without sorting out the aggregate. The net effect of this is that the aggregate is left including a finalized object. This is a very bad move indeed. * Reference leaks Catching reference leaks is evily difficult. The first approach is to re-build bonobo with BONOBO_OBJECT_DEBUG defined in bonobo-object.h. This combined with a call to bonobo_shutdown () before exiting your program should provide a dump of all object references floating in your code. Having re-build bonobo you will need to re-build your application, otherwise you will get link errors moaning about not being able to find 'bonobo_object_ref / unref'. A simpler but less verbose way to get ref count debugging without re-compiling everything is to simply define BONOBO_REF_HOOKS at the top of bonobo-object.c Another good way of catching leaks, having guessed which object is not getting freed is to fire up container and component in gdb, break in eg. bonobo_embeddable_new and insert a hardware watch point on the ref count [ see also debugging.txt ]: (gdb) p &((BonoboObject *)embeddable)->priv->ao->ref_count $N = (int *) 0x80808102 (gdb) watch *0x80808102 (gdb) cont This will result in gdb giving you control each time the ref count is changed. At this point halt the other end of the CORBA link and start logging traces at both ends. By the time the program exits you should have worked out where the reference went astray. * Ref Counting Conventions And now for the important stuff: ** Bonobo Ref Counting The Bonobo ref count convention is as follows. (Mild rewording; same meaning as before) 1. A function returning an object, either as the return value or by-reference, must always add a reference before returning. (Alternately: the callee must create a reference to the returned object that the caller owns) 2. A function that accepts a bonobo object as an in/out parameter must unreference the originally passed object once if the function wishes to change the value of the in/out parameter. (The function must ref() new objects returned via this in/out in accordance with [1]) 3. An object passed into a function needs only be ref()'d if the ifunction wishes to retain a reference to the object beyond the scope of the function call. In addition, there's a consensus that interface designers should be advised against designing methods with in/out parameters. In/out parameters can obscure the lifetime of the passed argument to casual code observers, and thus may cause hidden side-effects. ** CORBA Ref-counting Since the ORB also maintains reference counts per interface handle, should you be returning a reference to an object it is imperative to Bonobo_Unknown_ref (corba_object, ev); return CORBA_Object_duplicate (corba_object, ev); To assist with this there are two functions: Bonobo_Unknown bonobo_object_dup_ref (Bonobo_Unknown object, CORBA_Environment *ev); void bonobo_object_release_unref (Bonobo_Unknown object, CORBA_Environment *ev); So to return an Unknown from a impl you can simply: return bonobo_object_dup_ref (corba_object, ev); Warning; there is a caveat with this approach which is this: If you construct a BonoboObject in an impl_ whose reference you wish to hand back to the caller then the situation is slightly different. In this case you have an object with the following: Bonobo_Unknown: ref 1 BonoboObject: ref 1 You want to hand a CORBA reference to this object to the client, without incrementing the BonoboObject reference. To do this you must do: return CORBA_Object_duplicate (BONOBO_OBJREF (myobject)); The mirror of this is that if you want to hand a ref to an impl you will need to CORBA_Object_duplicate the value before inserting it into a BonoboObjectClient.