(no subject)

[Joseph J. S. <jo...@st...>]

Hi gang,

Please check my text on reference counting (below)... I want to make 
sure I don't lead anyone astray.

-----
Reference counted objects

  Most objects in Quesa are reference-counted. That means that Quesa 
keeps track of how many references there are to an object, and 
doesn't delete the object until the object is no longer in use (i.e., 
its reference count is zero).

  Not all libraries treat reference-counting the same way. The Quesa 
rules for it are as follows:

	1. The reference count of an object is incremented before 
returning it from a function.

	2. The reference count of an object is not incremented before 
passing it in as a parameter to some other function.

  So, if you call a Quesa function that returns an object (such as 
Q3Box_New or  Q3Group_GetPositionObject), you have gained a reference 
to that object. As long as you keep that reference in your data, 
everything is fine. When that reference is about to disappear -- for 
example, because it's in a local variable that is about to go out of 
scope or be assigned a different value, or in an object that is being 
destroyed -- then you must call Q3Object_Dispose to let Quesa know 
that there is one less reference to that object.

  If your own code causes another reference to an object to be created 
-- for example, because you're returning an object from a function 
but also keeping your own reference to it -- then you should call 
Q3Shared_GetReference to increment its reference count.
-----

Assuming this is all correct, the reader will be wondering: Why do 
Dispose a Q3Object, but I can only GetReference to a Q3SharedObject? 
It doesn't seem very parallel.  And, is it safe to call 
Q3SharedObject on something that is not, in fact, a Q3SharedObject 
(and what's an example of a Q3Object like that)?

I don't have good answers to these questions, so I'm hoping you do!

Thanks,
- Joe

-- 
,------------------------------------------------------------------.
|    Joseph J. Strout         Check out the Mac Web Directory:     |
|    jo...@st...           http://www.macwebdir.com/            |
`------------------------------------------------------------------'