stos: ob: Add object cache groundwork

Signed-off-by: Chloe M. <chloe@mensia.org>

paw/stos/head/ob/cache.h

@@ -0,0 +1,57 @@
+/*
+ * Copyright (c) 2026, Chloe M.
+ * Provided under the BSD-3 clause.
+ *
+ * Description:  Object manager cache
+ * Author:       Chloe M.
+ */
+
+#ifndef _OB_CACHE_H_
+#define _OB_CACHE_H_ 1
+
+#include <stdef.h>
+#include <ob/object.h>
+
+/*
+ * An object cache allows deallocated objects to be recycled without
+ * the overhead of true deallocation and reallocation.
+ *
+ * @First:      First cache entry
+ * @Last:       Last cache entry
+ * @EntryCount: Number of entires in the cache
+ */
+typedef struct {
+    ST_OBJECT *First;
+    ST_OBJECT *Last;
+    USIZE EntryCount;
+} OBJECT_CACHE;
+
+extern OBJECT_CACHE gObCache;
+
+/*
+ * Initialize object cache
+ *
+ * @Cache: Object cache to initialize
+ */
+VOID ObInitCache(OBJECT_CACHE *Cache);
+
+/*
+ * Reclaim object to cache if the reference count is
+ * zero.
+ *
+ * @Cache:  Cache to reclaim to
+ * @Object: Object to reclaim
+ */
+VOID ObReclaimToCache(OBJECT_CACHE *Cache, ST_OBJECT *Object);
+
+/*
+ * Pop an entry for a zeroed object from the cache
+ *
+ * @Cache:  Cache to pop from
+ *
+ * Returns an entry on success, otherwise NULL on
+ * failure
+ */
+ST_OBJECT *ObPopFromCache(OBJECT_CACHE *Cache);
+
+#endif  /* !_OB_CACHE_H_ */

paw/stos/head/ob/object.h

@@ -34,12 +34,14 @@ typedef enum {
  * @RefCount:   Object reference count
  * @Type:       Object type
  * @Data:       Object data
+ * @CacheNext:  Used when reclaiming object
  */
-typedef struct {
+typedef struct _ST_OBJECT {
     CHAR Name[OBJECT_NAMESZ];
     ULONG RefCount;
     OBJECT_TYPE Type;
     VOID *Data;
+    struct _ST_OBJECT *CacheNext;
 } ST_OBJECT;
 
 /*
@@ -82,4 +84,12 @@ ST_STATUS ObCreateObject(
  */
 VOID ObInitManager(VOID);
 
+/*
+ * Reclaim an object after use, if its reference count is > 1, simply
+ * bump it down. Once it hits zero, the object is returned to the cache.
+ *
+ * @Object: Object to reclaim
+ */
+VOID ObReclaimObject(ST_OBJECT *Object);
+
 #endif  /* !_OB_OBJECT_H_ */