Please explain the meaning of 'stealing' a ref

[Christos TZOTZIOY Georgiou]

On Wed, 05 Nov 2003 20:24:39 GMT, rumours say that Alex Martelli
<aleaxit at yahoo.com> might have written:

>> The missing part IMO is what "owning a reference" means.  I understand
>
>Hmmm... what if the text was transliterated into "Owning a reference
>means you have to dispose of it properly" from the current "When a
>function owns a reference, it has to dispose of it properly"?  The current
>expression and my suggested rewording are meant to convey just the
>same meaning, but perhaps the rewording is more immediately obvious
>to some non-native speakers of English (I'm a non-native speaker myself,
>but sometimes I have trouble gauging what problems others may have).

For other people (if any) that have similar to my questions, all the
information about 'owning', 'borrowing' and 'stealing' references is in
the sections 1.2.1-1.2.2 of the "Python/C API reference", but first have
a good grasp of the tutorial "Extending and Embedding the Python
interpreter", subsections 1.10.1-1.10.4 .


>> This text is obviously clear, and the misconception was my fault: since
>> references are just pointer variables at the C level, and I never had a
>> concept of a function (or a program) 'owning' its variables,
>> automatically my brain converted the word 'reference' to 'reference to
>> python object' to 'python object'.  That's it.
>
>Ah.  So there may be no fix for this -- we can't get any more explicit,
>but if your brain converts this to "we talk of owning python objects,
>never of owning objects" there's really nothing we can do:-(.

You use present tense for 'converts' above, but I assume you meant to
use past tense, since this is what I did in the previous paragraph.
Unusual of you to miss details.  Like I said, the text is clear; it
needs no fix in the case of owning references|objects.

>> The word "exceptions" implies "exception to the previous statement".
>
>Yes, to the statement terminated by the semicolon - the one saying that few 
>functions steal references.
>
>> IIUC "exceptions" should be changed to "examples".
>
>Yes, this is surely a reasonable change, if it clarifies the text for some 
>readers.

Since you agree (and make more specific) that 'exceptions' means
'exception to the statement terminated by the semicolon', and since
neither PyList_SetItem nor PyTuple_SetItem are exceptions to the few
functions that steal references, doesn't that make the choice of the
word 'exceptions' unreasonable (as in exactly the opposite of what was
meant)?  It's not a matter of simple clarification.

Either the word 'exceptions' should be changed, or it should be changed
to 'notable exceptions to <here specify the domain to which the two
abovementioned functions are exceptions, and which domain is not "'few
functions steal references", since the functions do steal references>'

The previous two paragraphs were written only because your 'if it
clarifies the text for some readers' seems to ignore the fact you
yourself stated two paragraphs above in 'Yes, to the statement...'

>> Also, it would be helpful if (possibly as footnotes too) there was the
>> following definition:
>> "stealing a reference": a function that steals a reference takes away
>> from the caller the responsibility of calling Py_DECREF on the
>> referenced object.
>> 
>> If all of the above seem redundant to you, then perhaps it would make
>
>Yes, totally -- and incomplete, because it doesn't really capture the
>_concept_ of ownership.  E.g., if the called didn't own the reference
>but borrowed it, then to pass it to a function that steals it, the caller
>must Py_INCREF it -- now the "takes away the responsibility" can
>be considered a very misleading statement.

Yes, your example is a good one -as usual for a bot :)- to make my
suggestion lacking.
If the python documentation had a terminology dictionary, how would
'stealing', 'borrowing' and 'owning' a reference be defined in a concise
and absolutely clear way?  I seem to not be able to write these
definitions, although I would like to.

Anyway, given time and inspiration, sf.net is just a few blocks down the
street :)
-- 
TZOTZIOY, I speak England very best,
Ils sont fous ces Redmontains! --Harddix