Fast path

If the object is owned by the current thread and is mortal, which is the common case, the code is basically:

uint32_t local = _Py_atomic_load_uint32_relaxed(&op->ob_ref_local);
uint32_t new_local = local + 1;
_Py_atomic_store_uint32_relaxed(&op->ob_ref_local, new_local);

The "relaxed" operations are cheap since there are no synchronization or ordering constraints imposed on other reads or writes, only these operations' atomicity is guaranteed.

Slow path

If the object is not owned by the current thread, a slower code path is used:

_Py_atomic_add_ssize(&op->ob_ref_shared, (1 << _Py_REF_SHARED_SHIFT));

where _Py_atomic_add_ssize() uses the "sequentially consistent" order which is slower than "relaxed" since it implies locking.

See Include/cpython/pyatomic.h header for more information on atomic functions used by CPython and memory order.

_Py_MergeZeroLocalRefcount() function

In Py_DECREF(), if an object is owned by the current thread and its refcount reached 0, _Py_MergeZeroLocalRefcount() is called.

void
_Py_MergeZeroLocalRefcount(PyObject *op)
{
    assert(op->ob_ref_local == 0);

    Py_ssize_t shared = _Py_atomic_load_ssize_acquire(&op->ob_ref_shared);
    if (shared == 0) {
        _Py_Dealloc(op);
        return;
    }

    _Py_atomic_store_uintptr_relaxed(&op->ob_tid, 0);

    Py_ssize_t new_shared;
    do {
        new_shared = (shared & ~_Py_REF_SHARED_FLAG_MASK) | _Py_REF_MERGED;
    } while (!_Py_atomic_compare_exchange_ssize(&op->ob_ref_shared,
                                                &shared, new_shared));

    if (new_shared == _Py_REF_MERGED) {
        _Py_Dealloc(op);
    }
}

If the shared reference count is 0, the function just calls _Py_Dealloc(op).

Otherwise, it sets ob_tid to _Py_UNOWNED_TID (0), and then adds the flag _Py_REF_MERGED to shared reference count. If other threads called Py_DECREF() in parallel and the shared reference count became 0 in the meanwhile, _Py_Dealloc(op) is called. Otherwise, there are still shared references to the object and so it's still alive. The object will be destroyed once the shared reference count reachs 0.

_Py_DecRefShared() function

Py_DECREF() calls _Py_DecRefShared() if the object is not owned by the current thread (and the object is mortal).

static int
_Py_DecRefSharedIsDead(PyObject *o)
{
    // Should we queue the object for the owning thread to merge?
    int should_queue;

    Py_ssize_t new_shared;
    Py_ssize_t shared = _Py_atomic_load_ssize_relaxed(&o->ob_ref_shared);
    do {
        should_queue = (shared == 0 || shared == _Py_REF_MAYBE_WEAKREF);

        if (should_queue) {
            // If the object had refcount zero, not queued, and not merged,
            // then we enqueue the object to be merged by the owning thread.
            // In this case, we don't subtract one from the reference count
            // because the queue holds a reference.
            new_shared = _Py_REF_QUEUED;
        }
        else {
            // Otherwise, subtract one from the reference count. This might
            // be negative!
            new_shared = shared - (1 << _Py_REF_SHARED_SHIFT);
        }
    } while (!_Py_atomic_compare_exchange_ssize(&o->ob_ref_shared,
                                                &shared, new_shared));

    if (should_queue) {
        _Py_brc_queue_object(o);
    }
    else if (new_shared == _Py_REF_MERGED) {
        // refcount is zero AND merged
        return 1;
    }
    return 0;
}

void
_Py_DecRefShared(PyObject *o)
{
    if (_Py_DecRefSharedIsDead(o)) {
        _Py_Dealloc(o);
    }
}

If the shared reference count is 0 and the _Py_REF_MERGED flag is set, call _Py_Dealloc(o).

If the object has a shared reference count of 0, is not queued, and is not merged, then set the _Py_REF_QUEUED flag and calls _Py_brc_queue_object(o) which schedules the object destruction in its owning thread.

Otherwise, decrement the shared reference count.

_Py_REF_MERGED flag

Py_DECREF() sets the _Py_REF_MERGED flag if the object is owned by the current thread and ob_ref_local reached 0.

The _Py_ExplicitMergeRefcount() and GC merge_refcount() explicitly merge ob_ref_local into ob_ref_shared, set ob_tid to _Py_UNOWNED_TID (0), and set the _Py_REF_MERGED flag.

_Py_REF_QUEUED flag

Py_DECREF() sets the _Py_REF_QUEUED flag if the object is not owned by the current thread and the shared reference count reached 0. In this case, _Py_brc_queue_object(o) is called to schedule the object destruction in its owning thread.

_Py_REF_MAYBE_WEAKREF flag

PyUnstable_EnableTryIncRef() enables subsequent uses of PyUnstable_TryIncRef() on obj. It sets the _Py_REF_MAYBE_WEAKREF flag.

_Py_NewRefWithLock() and _Py_XNewRefWithLock() also set the _Py_REF_MAYBE_WEAKREF flag. These functions are similar to Py_NewRef()/Py_XNewRef(), but also optimistically sets _Py_REF_MAYBE_WEAKREF on objects owned by a different thread.