Please explain the meaning of 'stealing' a ref

[Christos TZOTZIOY Georgiou]

On Tue, 04 Nov 2003 14:20:18 GMT, rumours say that Alex Martelli
<aleax at aleax.it> might have written:

I want to clarify that all the questions in my first post and in this
post are intended to help me understand the notions of "stealing a
reference", "borrowing a reference" because I found
api/refcountDetails.html a little unsatisfying.

[snip: my referring to ext/refcountsInPython.html and supposing that an
incref should be issued before calling a function "stealing" a
reference]

>Yes, you have to incref IF you want to keep owning that reference.

So, "owning a reference" means simply that some code did an incref and
is responsible to decref, right?  This is my first request for
clarification, although I understand that so far I was confusing "owning
a reference" and "owning an object".

>> decref afterwards yourself.  What's the reason?  Efficiency for
>
>You'll decref when you don't want to own that reference any more,
>and you incref'd it, but if you do that soon, why bother incref'ing?-)

I'd do that because I did not understand what "stealing a reference"
means; therefore I translated "stealing" = decref, so I presumed that I
should issue an incref in advance in order to make sure the object
passed to the function does not cease to exist before the function
returns.  I assumed based on unclear (to me) terms.

>The typical use case to explain the stealing is in the "Reference
>Count Details" section of the API manual:
>
>PyObject *t;
>
>t = PyTuple_New(3);
>PyTuple_SetItem(t, 0, PyInt_FromLong(1L));
>PyTuple_SetItem(t, 1, PyInt_FromLong(2L));
>PyTuple_SetItem(t, 2, PyString_FromString("three"));
>
>PyTuple_SetItem is very often called with a completely new reference
>as its 3d argument, so it steals it to enable this easy idiom... w/o
>the stealing you'd have to code, e.g.:
>
>PyObject *t;
>PyObject *temp;
>
>t = PyTuple_New(3);
>
>temp = PyInt_FromLong(1L);
>PyTuple_SetItem(t, 0, temp);
>Py_DECREF(temp);
>
>etc -- much less handy.

I understand that.  So, a function "stealing" a reference means the
function takes away from the caller the responsibility for decref'ing
the object, and "stealing a reference" does not translate into some C
code, right?  This is my second request for clarification.

>> simplicity of the function?  If yes, why not enclose the function call
>> in a incref / decref cycle and then export the enclosing function in the
>> API?
>
>I don't know what you're talking about.  Explain please?  E.g. with one
>of the few reference-stealing functions, PyTuple_SetItem ?

You don't know what I'm talking about because neither I was sure what I
was talking about; I now see I should not make assumptions since I was
not sure as to what "stealing a ref" means.  It was confusing to the
readers of my post.

>> Such stuff I wanted to know.
>> 
>> Also, "borrowing" and "stealing" are the same thing?  I just think that
>
>No!  You get a borrowed reference when you get a reference but are not
>transferred the ownership of it.  That's a pretty widespread use regarding
>references that are returned to objects that surely pre-existed.  You
>must then incref in the relatively rare case you want to keep hold of
>that reference for the longer term.

So a function "borrowing" a reference means that the function does not
incref or decref an object which was passed to it, right?  That is the
third request.
I assume that most functions of the python API "borrow" references?

>> "beautifying" terminology at the C level is more confusing than helpful.
>
>What 'beautifying'...?

"Beautifying" in the sense that I thought that both "stealing" and
"borrowing" a reference translate into actual C code, a mistaken
assumption.

Thanks for your time.
-- 
TZOTZIOY, I speak England very best,
Ils sont fous ces Redmontains! --Harddix