Re: [g-a-devel]leaked objects - basic reference counting tutorial

[Bill Haneman <bill haneman sun com>]

Hi David/all:

> If my call to Accessible_unref reduces the ref count for that object to 
> 0, is it immediately removed from the hash table?

As Micheal says, that's a detail you need not/should not worry about. 
Suffice it to say that you shouldn't attempt to use an object which
you're not holding a reference to (as opposed to just re-using a
"pointer").

The rule of thumb, to restate what Michael alluded to already:

On receipt of an AT-SPI 'Accessible' via an AT-SPI call such as
'Accessible_getParent' or 'AccessibleComponent_getAccessibleAt', etc.,
you get an Accessible reference which you should unref when done.

When you receive an Accessible object as part of an event notification
(i.e. inside the AccessibleEvent structure), you don't get a new
reference, and thus the event->source "Accessible" is only valid for the
duration of the callback.  If you wish to save the Accessible for future
use (including just comparison with later event sources), then you must
explicitly hold a reference to it via Accessible_ref(), and of course
you must call Accessible_unref() when you are, finally, done with the
object.  If however you do not wish to refer to the event source outside
of the event callback, you need not explicitly ref()/unref() the event
source.

The AT-SPI reference docs for the C bindings should indicate which calls
return references to Accessibles; those that have Accessible* as their
return type should all be incrementing the reference count on return,
thus callers of these methods should call Accessible_unref() on the
returned value when they are done with it (and before the client/caller
exits).

-Bill