netdata · stelfrag · Jan 24, 2026 · Jan 30, 2026 · Jan 30, 2026 · Jan 30, 2026
@@ -9,6 +9,7 @@
 #include "web/mcp/mcp.h"
 
 #include "database/engine/page_test.h"
+#include "database/rrdset-slots.h"
 #include <curl/curl.h>
 
 #ifdef OS_WINDOWS
@@ -154,6 +155,7 @@ int help(int exitcode) {
             "                           size of E MiB, an optional disk space limit\n"
             "                           of F MiB, G libuv workers (default 16) and exit.\n\n"
 #endif
+            "  -W prd-array-stress      Run PRD_ARRAY refcount stress test and exit.\n\n"
             "  -W set section option value\n"
             "                           set netdata.conf option from the command line.\n\n"
             "  -W buildinfo             Print the version, the configure options,\n"
@@ -453,6 +455,10 @@ int netdata_main(int argc, char **argv) {
                             unittest_running = true;
                             return rwlocks_stress_test();
                         }
+                        else if(strcmp(optarg, "prd-array-stress") == 0) {
+                            unittest_running = true;
+                            return prd_array_stress_test();
+                        }
                         else if(strcmp(optarg, "stringtest") == 0)  {
                             unittest_running = true;
                             return string_unittest(10000);

@@ -23,13 +23,29 @@ void rrdhost_pluginsd_send_chart_slots_free(RRDHOST *host) {
 }
 
 void rrdhost_pluginsd_receive_chart_slots_free(RRDHOST *host) {
-    rrd_slot_memory_removed(host->stream.rcv.pluginsd_chart_slots.size * sizeof(uint32_t));
+    rrd_slot_memory_removed(host->stream.rcv.pluginsd_chart_slots.size * sizeof(RRDSET *));
 
     spinlock_lock(&host->stream.rcv.pluginsd_chart_slots.spinlock);
 
     if(host->stream.rcv.pluginsd_chart_slots.array) {
-        for (size_t s = 0; s < host->stream.rcv.pluginsd_chart_slots.size; s++)
-            rrdset_pluginsd_receive_unslot_and_cleanup(host->stream.rcv.pluginsd_chart_slots.array[s]);
+        for (size_t s = 0; s < host->stream.rcv.pluginsd_chart_slots.size; s++) {
+            RRDSET *st = host->stream.rcv.pluginsd_chart_slots.array[s];
+            if(st) {
+                // Clear collector_tid - the collector is already stopped
+                // (stream_receiver_signal_to_stop_and_wait was called before this)
+                // so it's safe to cleanup regardless of the previous collector_tid value
+                __atomic_store_n(&st->pluginsd.collector_tid, 0, __ATOMIC_RELEASE);
+
+                // Pre-clear last_slot so that rrdset_pluginsd_receive_unslot_and_cleanup
+                // won't try to re-acquire the host spinlock we already hold.
+                // This prevents recursive locking on pluginsd_chart_slots.spinlock.
+                // We're freeing the entire host slots array below, so clearing individual
+                // slot entries is unnecessary.
+                st->pluginsd.last_slot = -1;
+
+                rrdset_pluginsd_receive_unslot_and_cleanup(st);
+            }
+        }
 
         freez(host->stream.rcv.pluginsd_chart_slots.array);
         host->stream.rcv.pluginsd_chart_slots.array = NULL;

@@ -0,0 +1,139 @@
+// SPDX-License-Identifier: GPL-3.0-or-later
+
+#ifndef NETDATA_RRDSET_PLUGINSD_ARRAY_H
+#define NETDATA_RRDSET_PLUGINSD_ARRAY_H
+
+// This header must be included AFTER rrddim.h to get the full struct pluginsd_rrddim definition
+
+#include "rrddim.h"
+
+// --------------------------------------------------------------------------------------------------------------------
+// Reference-counted array for pluginsd dimension caching
+//
+// This structure provides thread-safe access to the dimension cache array used by the pluginsd protocol.
+// The reference counting ensures that the array is not freed while any thread is still using it.
+//
+// THREAD SAFETY - LIFECYCLE SEPARATION:
+// -------------------------------------
+// The design relies on collector and cleanup never running concurrently on the same chart:
+//
+// 1. collector_tid: Primary synchronization mechanism
+//    - Collector sets collector_tid BEFORE accessing the array
+//    - Collector clears collector_tid AFTER all operations are complete
+//    - Cleanup code checks collector_tid and SKIPS if non-zero
+//    - This allows the collector to use lock-free operations (get_unsafe, replace, release)
+//
+// 2. spinlock + refcount: Coordinates concurrent cleanup operations
+//    - prd_array_acquire(): Takes spinlock, loads pointer, increments refcount
+//    - Used by cleanup code when collector is NOT active
+//    - Prevents races between multiple cleanup threads
+//
+// 3. Lifecycle guarantee: In production, cleanup only runs when:
+//    - Stream receiver is stopped (collector thread terminated)
+//    - collector_tid is explicitly cleared before cleanup
+//    - Therefore, collector's replace+release never races with cleanup's acquire
+//
+// HOT PATH (collector active, collector_tid set): Lock-free
+// CLEANUP PATH (collector stopped, collector_tid == 0): Uses spinlock
+// --------------------------------------------------------------------------------------------------------------------
+
+typedef struct pluginsd_rrddim_array {
+    int32_t refcount;                    // Reference count (atomic)
+    size_t size;                         // Number of entries in the array
+    struct pluginsd_rrddim entries[];    // Flexible array member
+} PRD_ARRAY;
+
+// --------------------------------------------------------------------------------------------------------------------
+// API Functions
+// --------------------------------------------------------------------------------------------------------------------
+
+// Create a new array with the specified size and refcount=1
+static inline PRD_ARRAY *prd_array_create(size_t size) {
+    PRD_ARRAY *arr = callocz(1, sizeof(PRD_ARRAY) + size * sizeof(struct pluginsd_rrddim));
+    arr->refcount = 1;
+    arr->size = size;
+    rrd_slot_memory_added(sizeof(PRD_ARRAY) + size * sizeof(struct pluginsd_rrddim));
+    return arr;
+}
+
+// Acquire a reference to the array when spinlock is ALREADY HELD
+// Returns NULL if no array exists
+// The caller MUST call prd_array_release() when done
+// Use this when you need to do additional checks (e.g., collector_tid) under the same spinlock
+static inline PRD_ARRAY *prd_array_acquire_locked(PRD_ARRAY **array_ptr) {
+    PRD_ARRAY *arr = *array_ptr;
+    if (arr) {
+        __atomic_fetch_add(&arr->refcount, 1, __ATOMIC_ACQ_REL);
+    }
+    return arr;
+}
+
+// Acquire a reference to the array stored in the atomic pointer location
+// Returns NULL if no array exists
+// The caller MUST call prd_array_release() when done
+//
+// IMPORTANT: Only call this when collector_tid == 0 (collector not active).
+// Uses spinlock to coordinate with other cleanup operations.
+static inline PRD_ARRAY *prd_array_acquire(PRD_ARRAY **array_ptr, SPINLOCK *spinlock) {
+    spinlock_lock(spinlock);
+    PRD_ARRAY *arr = prd_array_acquire_locked(array_ptr);
+    spinlock_unlock(spinlock);
+    return arr;
+}
+
+// Release a reference to the array
+// If this was the last reference (refcount becomes 0), the array is freed
+// Safe to call with NULL
+static inline void prd_array_release(PRD_ARRAY *arr) {
+    if (!arr)
+        return;
+
+    int32_t old_refcount = __atomic_load_n(&arr->refcount, __ATOMIC_ACQUIRE);
+    while(true) {
+        if(unlikely(old_refcount <= 0)) {
+            // Keep the object stable and avoid driving refcount further negative on
+            // repeated misuse. Log in all builds; internal_fatal adds extra checks.
+            nd_log_limit_static_global_var(erl_prd_refcount_underflow, 1, 0);
+            nd_log_limit(&erl_prd_refcount_underflow, NDLS_DAEMON, NDLP_WARNING,
+                         "PRD_ARRAY: refcount underflow (was %d) - double release detected",
+                         old_refcount);
+            internal_fatal(true,
+                           "PRD_ARRAY: refcount underflow (was %d) - double release detected", old_refcount);
+            return;
+        }
+
+        if(__atomic_compare_exchange_n(&arr->refcount, &old_refcount, old_refcount - 1,
+                                       false, __ATOMIC_ACQ_REL, __ATOMIC_ACQUIRE))
+            break;
+    }
+
+    if(old_refcount == 1) {
+        // We were the last reference - free the array
+        // Note: The caller is responsible for releasing any RRDDIM_ACQUIRED references
+        // in the entries before the final release
+        rrd_slot_memory_removed(sizeof(PRD_ARRAY) + arr->size * sizeof(struct pluginsd_rrddim));
+        freez(arr);
+    }
+}
+
+// Atomically replace the array pointer with a new array
+// Returns the old array (caller must release it) or NULL if there was no old array
+// The new_arr can be NULL to clear the array
+//
+// Thread safety depends on context:
+// - Collector (collector_tid set): No spinlock needed - cleanup will skip
+// - Cleanup (collector_tid == 0): Should hold spinlock to coordinate with other cleanup
+static inline PRD_ARRAY *prd_array_replace(PRD_ARRAY **array_ptr, PRD_ARRAY *new_arr) {
+    return __atomic_exchange_n(array_ptr, new_arr, __ATOMIC_ACQ_REL);
+}
+
+// Get the current array without acquiring a reference (for quick NULL checks or
+// when external synchronization guarantees the array won't be freed)
+// WARNING: The returned pointer may become invalid at any time unless:
+// - The caller holds the spinlock, OR
+// - The caller is the collector thread with collector_tid set (preventing cleanup)
+static inline PRD_ARRAY *prd_array_get_unsafe(PRD_ARRAY **array_ptr) {
+    return __atomic_load_n(array_ptr, __ATOMIC_ACQUIRE);
+}
+
+#endif // NETDATA_RRDSET_PLUGINSD_ARRAY_H