Please explain the meaning of 'stealing' a ref

[Christos TZOTZIOY Georgiou]

On Wed, 05 Nov 2003 15:07:08 GMT, rumours say that Alex Martelli
<aleax at aleax.it> might have written:

>Christos TZOTZIOY Georgiou wrote:
>   ...

[snip]

>"Owning a reference" means "I'll dispose of that reference when I'm
>done with it".  As per:
>
>http://www.python.org/doc/current/api/refcountDetails.html
>
>"""
>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
>passing ownership on (usually to its caller) or by calling Py_DECREF() or
>Py_XDECREF(). When a function passes ownership of a reference on to its
>caller, the caller is said to receive a new reference. When no ownership is
>transferred, the caller is said to borrow the reference. Nothing needs to
>be done for a borrowed reference. 
>"""
>
>I really don't know how we could have expressed this any more clearly;
>if you can indicate what is hard for you to understand here, and how
>we could make it easier, I'd be really greateful!

The missing part IMO is what "owning a reference" means.  I understand
that my brain moved in mysterious ways on the false assumption that
"steal"/"borrow" translates to C code, yet I believe a definition of the
term "own" should be inserted somewhere in a way like:

"... objects are always shared!  Every call to Py_INCREF creates a
'reference' to the object (actually, it's a way to make 'official' to
the python memory management system that you've got a pointer pointing
to the object, so the object better stays where it is!) which reference
is considered as 'owned' by the caller.  This reference should be
disposed of properly ..."

I beieve that neither my english nor my brain is fit for documentation
writing, but I also believe you will get the idea.  Perhaps the text in
the parenthesis needs a complete rewriting --or removal.
The definition could be appended as a footnote, to avoid changing the
current text flow.

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

[snip]

>You're welcome!  Now I'd like, if possible, to enhance the docs so
>that other people's future doubts might be similarly helped -- that's
>the reason I'm asking you for advice on this!

I proposed a definition for "owning a reference".

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".
IIUC "exceptions" should be changed to "examples".

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
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>')

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

>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.
-- 
TZOTZIOY, I speak England very best,
Ils sont fous ces Redmontains! --Harddix