Please explain the meaning of 'stealing' a ref

[Alex Martelli]

Christos TZOTZIOY Georgiou wrote:
   ...
>>The reference count behavior of functions in the Python/C API is best
>>explained in terms of ownership of references. Note that we talk of owning
>>references, never of owning objects; objects are always shared! When a
>>function owns a reference, it has to dispose of it properly -- either by
   ...
>>I really don't know how we could have expressed this any more clearly;
   ...
> 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).


>>> clarification, although I understand that so far I was confusing "owning
>>> a reference" and "owning an object".
>>
>>Ditto: I don't know how we could try to dispell this common doubt
>>any more clearly than by saying "we talk of owning references, never
>>of owning objects; objects are always shared!".
> 
> 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:-(.


> A slight clarification in the following text:
> """Few functions steal references; the two notable exceptions are
> PyList_SetItem()and PyTuple_SetItem()"""
> 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.


> 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.

> life easier for future readers adding a link to ext/ownershipRules.html
> at the end of the first sentence of api/refcountDetails.html .  (as in
> HTML lingo 'see also <A href="/ext/ownershipRules.html">Ownership
> Rules</A>')

Yes, this can't hurt.  I don't know how to set cross-book references in
the Latex source for the docs, but I'm sure their official czar, Fred Drake,
does know, so I'll ask him.


> Borrowing and reference ownership are explained in 'Ownership Rules',
> which is in the Extending and Embedding tutorial; one tends to think
> that a reference manual should not depend on definitions in a
> tutorial...

It doesn't depend on the definitions, but it does depend on the knowledge
imparted by that tutorial having been absorbed already.  If "reference 
ownership" is still a totally alien concept when one starts on the 
reference manual, the latter's in trouble.  Some pointers back to the 
tutorial presumably can't hurt, though.


>>If you could spend some time to visit safari.oreilly.com -- subscribe
>>and be sure to cancel before 2 weeks so you don't have to pay! -- and
>>check the penultimate chapter of Python in a Nutshell, where I've
>>tried an alternate "concise mixed reference/tutorial" tack to the
>>whole issue of extending Python, I'd be particularly grateful of any
>>feedback about that, too... thanks!
> 
> Thanks for the hint, I'll try that sometime.

Thanks -- and remember I'll appreciate the feedback.


Alex