About to refator tools... again

src/util/reflist.h

@@ -0,0 +1,77 @@
+/**
+ * Copyright (c) 2025 Dominic Masters
+ * 
+ * This software is released under the MIT License.
+ * https://opensource.org/licenses/MIT
+ */
+
+#pragma once
+#include "dusk.h"
+
+typedef uint_fast16_t ref_t;
+
+typedef struct reflist_s reflist_t;
+
+typedef struct reflist_s {
+  ref_t *array;
+  uint_fast16_t max;
+  uint_fast16_t count;
+  ref_t refNext;
+
+  void *user;
+
+  void (*onNotEmpty)(reflist_t *list);
+  void (*onFull)(reflist_t *list);
+  void (*onAdd)(reflist_t *list, const ref_t ref);
+  void (*onRemove)(reflist_t *list, const ref_t ref);
+  void (*onEmpty)(reflist_t *list);
+} reflist_t;
+
+/**
+ * Initialize a reference list. Reference lists just hold a list of references
+ * that are "holding on to" a given object/resource.
+ * 
+ * @param list The reference list to initialize.
+ * @param array The array to use as backing storage for the list.
+ * @param max The maximum number of references the list can hold.
+ */
+void refListInit(
+  reflist_t *list,
+  ref_t *array,
+  const uint_fast16_t max
+);
+
+
+/**
+ * Lock a reference in the list. This will return a new reference ID that can be
+ * used to access the locked reference.
+ * 
+ * @param list The reference list to lock a reference in.
+ * @return The locked reference ID, or 0 if the list is full.
+ */
+ref_t refListLock(reflist_t *list);
+
+/**
+ * Unlock a reference in the list. This will free up the reference ID for
+ * reuse.
+ * 
+ * @param list The reference list to unlock a reference in.
+ * @param ref The reference ID to unlock.
+ */
+void refListUnlock(reflist_t *list, const ref_t ref);
+
+/**
+ * Checks if the reference list is full.
+ * 
+ * @param list The reference list to check.
+ * @return true if the list is full, false otherwise.
+ */
+bool_t refListIsFull(const reflist_t *list);
+
+/**
+ * Checks if the reference list is empty.
+ * 
+ * @param list The reference list to check.
+ * @return true if the list is empty, false otherwise.
+ */
+bool_t refListIsEmpty(const reflist_t *list);