Please explain the meaning of 'stealing' a ref

[Alex Martelli]

KefX wrote:

>> what exactly is the meaning of a function
>>"stealing a reference"?
> 
> It decrements the reference count. 

*NO*!  It _takes over ownersip_: it DOESN'T decrement the
refcount at that point; rather, it takes over the future
responsibility for decrementing it at some point in time,
i.e., the abstract "ownership" of the reference.  See my
other post in this thread for the classic example from Python's
online API docs ... if PyTuple_SetItem _decremented the
reference_ to the newly created PyObject* it's passed, how
WOULD it fill the tuple's item?-)

> If you still need the reference,
> Py_INCREF() it beforehand.

If you still need to OWN the reference, yes.  If you just
need to USE it for a while during which you're sure the
tuple that's now "owning" it isn't going away, no need to
incref-then-decref.


Alex