sequenceDiagram
    participant DC as Deadlock Checker (spinlock_core)
    participant ST as SPINLOCK_TRACKED struct
    participant DF as Datafile (users.spinlock)
    participant JF as Journalfile (data_spinlock)
    participant FL as Flush Thread (rrdengine.c)

    Note over DC,FL: Tracked spinlock flow on contention

    DF->>ST: spinlock_tracked_lock()
    activate ST
    ST->>DC: spinlock_lock_core (tracked=non-NULL)
    activate DC

    loop Spin-acquire loop
        DC->>DC: Test __atomic_try_lock
        alt Lock acquired
            DC->>ST: spinlock_tracked_record_holder()
            ST->>ST: __atomic_store holder_tid, holder_func, holder_since_ut
            DC-->>DF: lock owned
            DF->>DF: (critical section: acquire/release datafile refs)
            DF->>ST: spinlock_tracked_unlock()
            ST->>ST: __atomic_clear holder_tid
            ST->>DC: spinlock_unlock (plain)
            deactivate DC
            deactivate ST
        else Lock busy (contention)
            DC->>DC: spins++
            alt Every SPINS_BEFORE_DEADLOCK_CHECK iteration
                DC->>ST: spinlock_tracked_deadlock_detect()
                activate ST
                alt Timeout exceeded (3600s)
                    DC->>ST: __atomic_load holder_tid, holder_func, holder_since_ut
                    alt holder_tid != 0
                        ST-->>DC: holder identity known
                        DC->>DC: fatal("... holder: tid=%d func='%s' held_for=%"PRIi64"s ...")
                    else holder_tid == 0 (stuck/corrupted)
                        ST-->>DC: no holder recorded
                        DC->>DC: fatal("... holder: NONE - possible corruption/stuck byte ...")
                    end
                else No timeout yet
                    ST-->>DC: continue waiting
                end
                deactivate ST
            end
            DC->>DC: microsleep (exponential backoff)
        end
    end

    Note over JF,DC: Journalfile parallel example (same pattern)

    JF->>ST: spinlock_tracked_lock()
    ST->>DC: spinlock_lock_core (tracked=non-NULL)
    activate DC
    DC-->>JF: lock owned
    JF->>JF: (critical section: mount/unmount v2 data, update metrics)
    JF->>ST: spinlock_tracked_unlock()
    deactivate DC

    Note over FL,DC: Flush-thread update via tracked lock

    FL->>ST: spinlock_tracked_lock()
    ST->>DC: spinlock_lock_core (tracked=non-NULL)
    activate DC
    DC-->>FL: lock owned
    FL->>FL: update last_time_s on journalfile
    FL->>ST: spinlock_tracked_unlock()
    deactivate DC

    Note over ST: Plain SPINLOCK path via spinlock_lock_with_trace<br/>passes tracked=NULL, constant-folded away<br/>— no overhead, no holder stores

sequenceDiagram
    participant DF as datafile.c (users.*)
    participant JF as journalfile.c (data_spinlock)
    participant RE as rrdengine.c (extent_flush)
    participant SL as SPINLOCK (plain)
    participant ST as SPINLOCK_TRACKED
    participant DET as Deadlock Detector

    Note over DF,RE: NEW: SPINLOCK_TRACKED replaces SPINLOCK for these locks

    DF->>ST: spinlock_tracked_lock(&df->users.spinlock)
    ST->>SL: spinlock_lock_core(spinlock, func, tracked)
    alt Lock contested (spinning)
        loop Exponential backoff + deadlock check
            ST->>ST: spins++
            alt spins % SPINS_BEFORE_DEADLOCK_CHECK == 0
                ST->>DET: spinlock_tracked_deadlock_detect()
                DET->>DET: Read holder_tid, holder_func, holder_since_ut
                alt held >= SPINLOCK_DEADLOCK_TIMEOUT_SEC
                    DET-->>ST: fatal("DEADLOCK DETECTED [holder: tid=N func='...' held_for=N]")
                end
            end
            ST->>ST: microsleep(usec), usec *= 2
        end
    end
    ST->>ST: Acquired: __atomic_add_fetch(&locked, 1)
    ST->>ST: spinlock_tracked_record_holder()
    ST-->>DF: lock acquired

    DF->>DF: Critical section (check users.available, lockers, etc.)

    DF->>ST: spinlock_tracked_unlock(&df->users.spinlock)
    ST->>SL: spinlock_unlock(spinlock)
    Note over ST: Holder fields NOT cleared (advisory - overwritten by next acquirer)
    ST-->>DF: lock released

    Note over DF,RE: Same pattern for all call sites in datafile.c/journalfile.c/rrdengine.c

    JF->>ST: spinlock_tracked_lock(&journalfile->data_spinlock)
    ST->>SL: spinlock_lock_core(spinlock, func, tracked)
    alt Contested
        ST->>DET: spinlock_tracked_deadlock_detect()
        DET-->>ST: Holder identity in fatal
    end
    ST->>ST: Record holder
    ST-->>JF: lock acquired

    JF->>JF: Critical section (check JOURNALFILE flags, refcount, mmap)

    JF->>ST: spinlock_tracked_unlock(&journalfile->data_spinlock)
    ST-->>JF: lock released

    RE->>ST: spinlock_tracked_lock(&datafile->journalfile->data_spinlock)
    RE->>RE: Update last_time_s
    RE->>ST: spinlock_tracked_unlock(&datafile->journalfile->data_spinlock)

    alt SPINLOCK_IMPL_WITH_MUTEX build
        Note over ST: Mutex-backed implementation (no spin loop)
        ST->>SL: spinlock_lock(&spinlock->spinlock) (calls netdata_mutex_lock)
        ST->>ST: spinlock_tracked_record_holder()
        ST-->>DF: lock acquired
        DF->>ST: spinlock_tracked_unlock()
        ST->>SL: spinlock_unlock(&spinlock->spinlock) (calls netdata_mutex_unlock)
        Note over ST: holder fields recorded but no deadlock detection
    end