refcount ckpt

Author: remexre

doc/kernel/containers/refcounting.md

@@ -1,3 +1,43 @@
 # Reference counting
 
-Many resources in the ukoOS
+Many resources in the ukoOS kernel have dynamic enough ownership that reference counting is useful to determine if they're still in use and when they should be freed.
+
+We have a helper type, `refcount_t`, to help manage these.
+This is similar to the type with the same name in the Linux kernel, but we provide different helpers.
+
+```c
+#include <refcount.h>
+
+/**
+ * This type is some random example resource. It's always
+ */
+struct foo {
+    /**
+     * This field stores the actual reference count. This is an integral type
+     * that is no wider than usize.
+     */
+    refcount_t refcount;
+
+    /**
+     * A list the value is in.
+     */
+    struct list_head all_foos;
+
+    /**
+     * Another list the value might be in (or the list might be self-linked).
+     */
+    struct list_head bars;
+};
+
+struct list_head all_foos;
+
+void add_foos_not_in_a_bars_to_list(struct list_head *bars) {
+    for (struct list_head *iter = all_foos.next; iter != all_foos;
+            iter = iter->next) {
+        struct foo *foo = container_of(iter, struct foo, all_foos);
+        if (list_is_empty(foo->bars))
+            continue;
+        list_push(bars, &foo->bars);
+    }
+}
+```

src/kernel/include/refcount.h

@@ -0,0 +1,59 @@
+/*
+ * SPDX-FileCopyrightText: 2026 ukoOS Contributors
+ *
+ * SPDX-License-Identifier: GPL-3.0-or-later
+ */
+
+#ifndef UKO_OS_KERNEL__REFCOUNT_H
+#define UKO_OS_KERNEL__REFCOUNT_H 1
+
+#include <container.h>
+#include <panic.h>
+#include <stdatomic.h>
+
+/**
+ * A reference count. This essentially just an `atomic usize` that saturates at
+ * `USIZE_MAX` (and stays there) instead of overflowing.
+ */
+typedef struct {
+  atomic usize _count;
+} refcount_t;
+
+static inline void refcount_init(refcount_t *refcount) { refcount->_count = 1; }
+
+static inline void refcount_incref(refcount_t *refcount) {
+  // TODO: refactor to not need a loop
+  for (;;) {
+    usize count = atomic_load(&refcount->_count);
+    assert(count);
+
+    // If the counter saturated, don't overflow.
+    if (unlikely(count == USIZE_MAX))
+      return;
+
+    if (likely(
+            atomic_compare_exchange_weak(&refcount->_count, &count, count + 1)))
+      return;
+  }
+}
+
+static inline void refcount_decref(refcount_t *refcount,
+                                   void *(*free)(void *ctx), void *ctx) {
+  // TODO: refactor to not need a loop
+  usize count;
+  do {
+    count = atomic_load(&refcount->_count);
+    assert(count);
+
+    // If the counter saturated, don't decref.
+    if (unlikely(count == USIZE_MAX))
+      return;
+  } while (unlikely(
+      !atomic_compare_exchange_weak(&refcount->_count, &count, count - 1)));
+
+  // The refcount is now zero.
+  if (count == 1)
+    free(ctx);
+}
+
+#endif // UKO_OS_KERNEL__REFCOUNT_H