General Comment + Consistency updates

24 files changed, 167 insertions, 282 deletions

diff --git a/include/framework/DynamicExtension.h b/include/framework/DynamicExtension.h
index f2bbacc..9129060 100644
--- a/include/framework/DynamicExtension.h
+++ b/include/framework/DynamicExtension.h
@@ -1,7 +1,7 @@
 /*
  * include/framework/DynamicExtension.h
  *
- * Copyright (C) 2023 Douglas Rumbaugh <drumbaugh@psu.edu> 
+ * Copyright (C) 2023 Douglas B. Rumbaugh <drumbaugh@psu.edu> 
  *                    Dong Xie <dongx@psu.edu>
  *
  * All rights reserved. Published under the Modified BSD License.
@@ -107,8 +107,7 @@ public:
     }
 
     size_t get_record_count() {
-        auto epoch = get_active_epoch();
-        epoch->start_job();
+        auto epoch = get_active_epoch_protected();
         auto t =  epoch->get_buffer_view().get_record_count() + epoch->get_structure()->get_record_count();
         epoch->end_job();
 
@@ -116,8 +115,7 @@ public:
     }
 
     size_t get_tombstone_count() {
-        auto epoch = get_active_epoch();
-        epoch->start_job();
+        auto epoch = get_active_epoch_protected();
         auto t = epoch->get_buffer_view().get_tombstone_count() + epoch->get_structure()->get_tombstone_count();
         epoch->end_job();
 
@@ -129,8 +127,7 @@ public:
     }
 
     size_t get_memory_usage() {
-        auto epoch = get_active_epoch();
-        epoch->start_job();
+        auto epoch = get_active_epoch_protected();
         auto t= epoch->get_buffer_view().get_memory_usage() + epoch->get_structure()->get_memory_usage();
         epoch->end_job();
 
@@ -138,8 +135,7 @@ public:
     }
 
     size_t get_aux_memory_usage() {
-        auto epoch = get_active_epoch();
-        epoch->start_job();
+        auto epoch = get_active_epoch_protected();
         auto t = epoch->get_buffer_view().get_aux_memory_usage() + epoch->get_structure()->get_aux_memory_usage();
         epoch->end_job();
 
@@ -151,9 +147,8 @@ public:
     }
     
     Shard *create_static_structure() {
-        auto epoch = get_active_epoch();
+        auto epoch = get_active_epoch_protected();
         auto bv = epoch->get_buffer_view();
-        epoch->start_job();
 
         auto vers = epoch->get_structure();
         std::vector<Shard *> shards;
@@ -219,6 +214,11 @@ private:
         return m_epochs[m_current_epoch.load()];
     }
 
+    _Epoch *get_active_epoch_protected() {
+        m_epochs[m_current_epoch.load()]->start_job();
+        return m_epochs[m_current_epoch.load()];
+    }
+
     void advance_epoch() {
         size_t new_epoch_num = m_current_epoch.load() + 1;
         _Epoch *new_epoch = m_epochs[new_epoch_num];
@@ -241,6 +241,12 @@ private:
      * structure will be a shallow copy of the old one's. 
      */
     _Epoch *create_new_epoch() {
+        /*
+         * This epoch access is _not_ protected under the assumption that
+         * only one merge will be able to trigger at a time. If that condition
+         * is violated, it is possible that this code will clone a retired
+         * epoch.
+         */
         auto new_epoch = get_active_epoch()->clone();
         std::unique_lock<std::mutex> m_struct_lock;
         m_versions.insert(new_epoch->get_structure());
@@ -311,6 +317,8 @@ private:
         MergeArgs<R, S, Q, L> *args = (MergeArgs<R, S, Q, L> *) arguments;
 
         Structure *vers = args->epoch->get_structure();
+        // FIXME: with an improved shard interface, multiple full buffers
+        //        could be merged at once here.
         Buffer *buff = (Buffer *) args->epoch->get_buffers()[0];
 
         for (ssize_t i=args->merges.size() - 1; i>=0; i--) {
@@ -387,24 +395,23 @@ private:
     }
 
     std::future<std::vector<R>> schedule_query(void *query_parms) {
-        auto epoch = get_active_epoch();
-        epoch->start_job();
+        auto epoch = get_active_epoch_protected();
         
         QueryArgs<R, S, Q, L> *args = new QueryArgs<R, S, Q, L>();
         args->epoch = epoch;
         args->query_parms = query_parms;
+        auto result = args->result_set.get_future();
+
         m_sched.schedule_job(async_query, 0, args);
 
-        return args->result_set.get_future();
+        return result;
     }
 
     int internal_append(const R &rec, bool ts) {
         Buffer *buffer = nullptr;
         do {
-            auto epoch = get_active_epoch();
-
-            while (!(buffer = epoch->get_active_buffer()))
-                ;
+            auto epoch = get_active_epoch_protected();
+            buffer = epoch->get_active_buffer();
             
             /* if the buffer is full, schedule a merge and add a new empty buffer */
             if (buffer->is_full()) {
@@ -413,7 +420,8 @@ private:
                 schedule_merge();
                 buffer = add_empty_buffer(epoch);
             }
-
+            // FIXME: not exactly the best spot for this
+            epoch->end_job();
         } while(!buffer->append(rec, ts));
 
         /* internal append should always succeed, eventually */
diff --git a/include/framework/ShardRequirements.h b/include/framework/ShardRequirements.h
index d2d4ff2..55e7199 100644
--- a/include/framework/ShardRequirements.h
+++ b/include/framework/ShardRequirements.h
@@ -1,4 +1,12 @@
 /*
+ * include/framework/ShardRequirements.h
+ *
+ * Copyright (C) 2023 Douglas B. Rumbaugh <drumbaugh@psu.edu> 
+ *
+ * All rights reserved. Published under the Modified BSD License.
+ *
+ * A header file containing the necessary includes for Shard
+ * development.
  *
  */
 #pragma once
diff --git a/include/framework/interface/Query.h b/include/framework/interface/Query.h
index 9b1d2d6..21cadcb 100644
--- a/include/framework/interface/Query.h
+++ b/include/framework/interface/Query.h
@@ -1,7 +1,7 @@
 /*
- * include/framework/QueryInterface.h
+ * include/framework/interface/Query.h
  *
- * Copyright (C) 2023 Douglas Rumbaugh <drumbaugh@psu.edu> 
+ * Copyright (C) 2023 Douglas B. Rumbaugh <drumbaugh@psu.edu> 
  *
  * All rights reserved. Published under the Modified BSD License.
  *
@@ -10,25 +10,29 @@
 
 #include <vector>
 #include <concepts>
+
 #include "util/types.h"
 
+// FIXME: The interface is not completely specified yet, as it is pending
+//        determining a good way to handle additional template arguments 
+//        to get the Shard and Record types into play
 template <typename Q>
 concept QueryInterface = requires(Q q, void *p, std::vector<void*> &s) {
-/*
-    {q.get_query_state(p, p)} -> std::convertible_to<void*>;
-    {q.get_buffer_query_state(p, p)};
-    {q.query(p, p)};
-    {q.buffer_query(p, p)};
-    {q.merge()};
-    {q.delete_query_state(p)};
-*/
-    {Q::EARLY_ABORT} -> std::convertible_to<bool>;
-    {Q::SKIP_DELETE_FILTER} -> std::convertible_to<bool>;
-    //{Q::get_query_state(p, p)} -> std::convertible_to<void*>;
-    //{Q::get_buffer_query_state(p, p)} -> std::convertible_to<void*>;
+
+    /*
+    {Q::get_query_state(p, p)} -> std::convertible_to<void*>;
+    {Q::get_buffer_query_state(p, p)} -> std::convertible_to<void *>;
+    */
     {Q::process_query_states(p, s, s)};
+    /*
+    {Q::query(s, p, p)} -> std::convertible_to<std::vector<Wrapped<R>>>;
+    {Q::buffer_query(p, p)} -> std::convertible_to<std::vector<Wrapped<R>>>;
+    {Q::merge(rv, p)} -> std::convertible_to<std::vector<R>>;
+    */
 
     {Q::delete_query_state(std::declval<void*>())} -> std::same_as<void>;
-    {Q::delete_buffer_query_state(p)};
+    {Q::delete_buffer_query_state(std::declval<void*>())} -> std::same_as<void>;
 
+    {Q::EARLY_ABORT} -> std::convertible_to<bool>;
+    {Q::SKIP_DELETE_FILTER} -> std::convertible_to<bool>;
 };
diff --git a/include/framework/interface/Record.h b/include/framework/interface/Record.h
index 1ef1984..bf495df 100644
--- a/include/framework/interface/Record.h
+++ b/include/framework/interface/Record.h
@@ -1,11 +1,12 @@
 /*
- * include/framework/RecordInterface.h
+ * include/framework/interface/Record.h
  *
  * Copyright (C) 2023 Douglas Rumbaugh <drumbaugh@psu.edu>
- *                    Dong Xie <dongx@psu.edu>
  *
  * All rights reserved. Published under the Modified BSD License.
  *
+ * FIXME: the record implementations could probably be broken out into 
+ *        different files, leaving only the interface here
  */
 #pragma once
 
diff --git a/include/framework/interface/Scheduler.h b/include/framework/interface/Scheduler.h
index e8ffd08..63581d2 100644
--- a/include/framework/interface/Scheduler.h
+++ b/include/framework/interface/Scheduler.h
@@ -1,7 +1,7 @@
 /*
- * include/framework/QueryInterface.h
+ * include/framework/interface/Scheduler.h
  *
- * Copyright (C) 2023 Douglas Rumbaugh <drumbaugh@psu.edu> 
+ * Copyright (C) 2023 Douglas B. Rumbaugh <drumbaugh@psu.edu> 
  *
  * All rights reserved. Published under the Modified BSD License.
  *
diff --git a/include/framework/interface/Shard.h b/include/framework/interface/Shard.h
index ea58b2a..d3a6cf8 100644
--- a/include/framework/interface/Shard.h
+++ b/include/framework/interface/Shard.h
@@ -1,7 +1,7 @@
 /*
- * include/framework/ShardInterface.h
+ * include/framework/interface/Shard.h
  *
- * Copyright (C) 2023 Douglas Rumbaugh <drumbaugh@psu.edu> 
+ * Copyright (C) 2023 Douglas B. Rumbaugh <drumbaugh@psu.edu> 
  *
  * All rights reserved. Published under the Modified BSD License.
  *
@@ -15,12 +15,22 @@
 
 namespace de {
 
-//template <template<typename> typename S, typename R>
+// FIXME: The interface is not completely specified yet, as it is pending
+//        determining a good way to handle additional template arguments 
+//        to get the Record type into play
 template <typename S>
-concept ShardInterface = requires(S s, void *p, bool b) {
-    //{s.point_lookup(r, b) } -> std::same_as<R*>;
+concept ShardInterface = requires(S s, S **spp, void *p, bool b, size_t i) {
+    {S(spp, i)};
+    /*
+    {S(mutable buffer)}
+    {s.point_lookup(r, b) } -> std::convertible_to<void*>
+    */
+    {s.get_data()} -> std::convertible_to<void*>;
+
     {s.get_record_count()} -> std::convertible_to<size_t>;
+    {s.get_tombstone_count()} -> std::convertible_to<size_t>;
     {s.get_memory_usage()} -> std::convertible_to<size_t>;
+    {s.get_aux_memory_usage()} -> std::convertible_to<size_t>;
 };
 
 }
diff --git a/include/framework/scheduling/Epoch.h b/include/framework/scheduling/Epoch.h
index 87463bd..03cbb62 100644
--- a/include/framework/scheduling/Epoch.h
+++ b/include/framework/scheduling/Epoch.h
@@ -2,7 +2,6 @@
  * include/framework/scheduling/Epoch.h
  *
  * Copyright (C) 2023 Douglas B. Rumbaugh <drumbaugh@psu.edu> 
- *                    Dong Xie <dongx@psu.edu>
  *
  * All rights reserved. Published under the Modified BSD License.
  *
diff --git a/include/framework/scheduling/FIFOScheduler.h b/include/framework/scheduling/FIFOScheduler.h
index 7ccab26..5425c4f 100644
--- a/include/framework/scheduling/FIFOScheduler.h
+++ b/include/framework/scheduling/FIFOScheduler.h
@@ -1,8 +1,7 @@
 /*
- * include/framework/Scheduler.h
+ * include/framework/scheduling/FIFOScheduler.h
  *
  * Copyright (C) 2023 Douglas B. Rumbaugh <drumbaugh@psu.edu> 
- *                    Dong Xie <dongx@psu.edu>
  *
  * All rights reserved. Published under the Modified BSD License.
  *
diff --git a/include/framework/scheduling/Scheduler.h b/include/framework/scheduling/Scheduler.h
deleted file mode 100644
index 992cbf9..0000000
--- a/include/framework/scheduling/Scheduler.h
+++ /dev/null
@@ -1,195 +0,0 @@
-/*
- * include/framework/Scheduler.h
- *
- * Copyright (C) 2023 Douglas Rumbaugh <drumbaugh@psu.edu> 
- *                    Dong Xie <dongx@psu.edu>
- *
- * All rights reserved. Published under the Modified BSD License.
- *
- */
-#pragma once
-
-#include <vector>
-#include <memory>
-#include <queue>
-#include <thread>
-#include <condition_variable>
-
-#include "util/types.h"
-#include "framework/interface/Shard.h"
-#include "framework/interface/Query.h"
-#include "framework/interface/Record.h"
-#include "framework/structure/MutableBuffer.h"
-#include "framework/util/Configuration.h"
-#include "framework/structure/ExtensionStructure.h"
-
-namespace de {
-
-template <RecordInterface R, ShardInterface S, QueryInterface Q, LayoutPolicy L>
-class Scheduler {
-    typedef ExtensionStructure<R, S, Q, L> Structure;
-    typedef MutableBuffer<R> Buffer;
-public:
-    /*
-     * Memory budget stated in bytes, with 0 meaning unlimited. Likewise, 0 threads means 
-     * unlimited.
-     */
-    Scheduler(size_t memory_budget, size_t thread_cnt) 
-        : m_memory_budget((memory_budget) ? memory_budget : UINT64_MAX)
-        , m_thread_cnt((thread_cnt) ? thread_cnt : UINT64_MAX)
-        , m_used_memory(0)
-        , m_used_threads(0)
-        , m_shutdown(false)
-    { 
-        m_sched_thrd = std::thread(&Scheduler::run_scheduler, this);
-    }
-
-    ~Scheduler() {
-        m_shutdown = true;
-
-        m_cv.notify_all();
-        m_sched_thrd.join();
-    }
-
-    bool schedule_merge(Structure *version, MutableBuffer<R> *buffer) {
-        /*
-         * temporary hack
-         */
-        pending_version = version;
-        pending_buffer = buffer;
-
-        /*
-         * Get list of individual level reconstructions that are necessary
-         * for completing the overall merge
-         */
-        std::vector<MergeTask> merges = version->get_merge_tasks(buffer->get_record_count());
-
-        /*
-         * Schedule the merge tasks (FIXME: currently this just 
-         * executes them sequentially in a blocking fashion)
-         */
-        for (ssize_t i=0; i<merges.size(); i++) {
-            merges[i].m_timestamp = m_timestamp.fetch_add(1);
-            m_merge_queue_lock.lock();
-            m_merge_queue.push(merges[i]);
-            m_merge_queue_lock.unlock();
-        }
-
-        MergeTask buffer_merge;
-        buffer_merge.m_source_level = -1;
-        buffer_merge.m_target_level = 0;
-        buffer_merge.m_size = buffer->get_record_count() * sizeof(R) * 2;
-        buffer_merge.m_timestamp = m_timestamp.fetch_add(1);
-        m_merge_queue_lock.lock();
-        m_merge_queue.push(buffer_merge);
-        m_merge_queue_lock.unlock();
-
-        m_cv.notify_all();
-        do {
-            std::unique_lock<std::mutex> merge_cv_lock(m_merge_cv_lock);
-            m_merge_cv.wait(merge_cv_lock);
-        } while (m_merge_queue.size() > 0);
-
-        assert(version->get_levels()[version->get_levels().size() - 1]->get_shard(0)->get_tombstone_count() == 0);
-
-        return true;
-    }
-
-private:
-    size_t get_timestamp() {
-        auto ts = m_timestamp.fetch_add(1);
-        return ts;
-    }
-
-    void schedule_next_task() {
-        m_merge_queue_lock.lock();
-        auto task = m_merge_queue.top();
-        m_merge_queue.pop();
-        m_merge_queue_lock.unlock();
-
-        if (task.m_source_level == -1 && task.m_target_level == 0) {
-            run_buffer_merge(pending_buffer, pending_version);
-        } else {
-            run_merge(task, pending_version);
-        }
-
-        if (m_merge_queue.size() == 0) {
-            m_merge_cv.notify_all();
-        }
-    }
-
-
-    void run_merge(MergeTask task, Structure *version) {
-        version->merge_levels(task.m_target_level, task.m_source_level); 
-
-        if (!version->validate_tombstone_proportion(task.m_target_level)) {
-            auto tasks = version->get_merge_tasks(task.m_target_level);    
-            /*
-             * Schedule the merge tasks (FIXME: currently this just 
-             * executes them sequentially in a blocking fashion)
-             */
-            for (ssize_t i=tasks.size()-1; i>=0; i--) {
-                tasks[i].m_timestamp = m_timestamp.fetch_add(1);
-                m_merge_queue_lock.lock();
-                m_merge_queue.push(tasks[i]);
-                m_merge_queue_lock.unlock();
-            }
-        }
-    }
-
-
-    void run_buffer_merge(Buffer *buffer, Structure *version) {
-        version->merge_buffer(buffer);
-        if (!version->validate_tombstone_proportion(0)) {
-            auto tasks = version->get_merge_tasks_from_level(0);
-
-            /*
-             * Schedule the merge tasks (FIXME: currently this just 
-             * executes them sequentially in a blocking fashion)
-             */
-            for (ssize_t i=tasks.size()-1; i>=0; i--) {
-                tasks[i].m_timestamp = m_timestamp.fetch_add(1);
-                m_merge_queue_lock.lock();
-                m_merge_queue.push(tasks[i]);
-                m_merge_queue_lock.unlock();
-            }
-        }
-    }
-
-    void run_scheduler() {
-        do {
-            std::unique_lock<std::mutex> cv_lock(m_cv_lock);
-            m_cv.wait(cv_lock);
-
-            while (m_merge_queue.size() > 0 && m_used_threads.load() < m_thread_cnt) {
-                schedule_next_task();
-            }
-            cv_lock.unlock();
-        } while(!m_shutdown);
-    }
-
-    size_t m_memory_budget;
-    size_t m_thread_cnt;
-
-    Buffer *pending_buffer;
-    Structure *pending_version;
-
-    alignas(64) std::atomic<size_t> m_used_memory;
-    alignas(64) std::atomic<size_t> m_used_threads;
-    alignas(64) std::atomic<size_t> m_timestamp;
-
-    std::priority_queue<MergeTask, std::vector<MergeTask>, std::greater<MergeTask>> m_merge_queue;
-    std::mutex m_merge_queue_lock;
-
-    std::mutex m_cv_lock;
-    std::condition_variable m_cv;
-
-    std::mutex m_merge_cv_lock;
-    std::condition_variable m_merge_cv;
-
-    std::thread m_sched_thrd;
-
-    bool m_shutdown;
-};
-
-}
diff --git a/include/framework/scheduling/Task.h b/include/framework/scheduling/Task.h
index d25c7c0..228665f 100644
--- a/include/framework/scheduling/Task.h
+++ b/include/framework/scheduling/Task.h
@@ -1,9 +1,13 @@
 /*
+ * include/framework/scheduling/Task.h
+ *
+ * Copyright (C) 2023 Douglas B. Rumbaugh <drumbaugh@psu.edu> 
+ *
+ * All rights reserved. Published under the Modified BSD License.
  *
  */
 #pragma once
 
-#include <variant>
 #include <future>
 #include <functional>
 
diff --git a/include/framework/structure/BufferView.h b/include/framework/structure/BufferView.h
index 8dff2ef..ccd3dac 100644
--- a/include/framework/structure/BufferView.h
+++ b/include/framework/structure/BufferView.h
@@ -1,7 +1,7 @@
 /*
  * include/framework/structure/BufferView.h
  *
- * Copyright (C) 2023 Douglas Rumbaugh <drumbaugh@psu.edu> 
+ * Copyright (C) 2023 Douglas B. Rumbaugh <drumbaugh@psu.edu> 
  *
  * All rights reserved. Published under the Modified BSD License.
  *
diff --git a/include/framework/structure/ExtensionStructure.h b/include/framework/structure/ExtensionStructure.h
index de965ae..1f365ae 100644
--- a/include/framework/structure/ExtensionStructure.h
+++ b/include/framework/structure/ExtensionStructure.h
@@ -1,7 +1,7 @@
 /*
- * include/framework/ExtensionStructure.h
+ * include/framework/structure/ExtensionStructure.h
  *
- * Copyright (C) 2023 Douglas Rumbaugh <drumbaugh@psu.edu> 
+ * Copyright (C) 2023 Douglas B. Rumbaugh <drumbaugh@psu.edu> 
  *                    Dong Xie <dongx@psu.edu>
  *
  * All rights reserved. Published under the Modified BSD License.
diff --git a/include/framework/structure/InternalLevel.h b/include/framework/structure/InternalLevel.h
index 342a2c7..7a7b98c 100644
--- a/include/framework/structure/InternalLevel.h
+++ b/include/framework/structure/InternalLevel.h
@@ -1,7 +1,7 @@
 /*
- * include/framework/InternalLevel.h
+ * include/framework/structure/InternalLevel.h
  *
- * Copyright (C) 2023 Douglas Rumbaugh <drumbaugh@psu.edu> 
+ * Copyright (C) 2023 Douglas B. Rumbaugh <drumbaugh@psu.edu> 
  *                    Dong Xie <dongx@psu.edu>
  *
  * All rights reserved. Published under the Modified BSD License.
diff --git a/include/framework/structure/MutableBuffer.h b/include/framework/structure/MutableBuffer.h
index 974dc28..e0a6962 100644
--- a/include/framework/structure/MutableBuffer.h
+++ b/include/framework/structure/MutableBuffer.h
@@ -1,7 +1,7 @@
 /*
- * include/framework/MutableBuffer.h
+ * include/framework/structure/MutableBuffer.h
  *
- * Copyright (C) 2023 Douglas Rumbaugh <drumbaugh@psu.edu> 
+ * Copyright (C) 2023 Douglas B. Rumbaugh <drumbaugh@psu.edu> 
  *                    Dong Xie <dongx@psu.edu>
  *
  * All rights reserved. Published under the Modified BSD License.
diff --git a/include/framework/util/Configuration.h b/include/framework/util/Configuration.h
index 9d8248f..ec4ec3a 100644
--- a/include/framework/util/Configuration.h
+++ b/include/framework/util/Configuration.h
@@ -1,8 +1,7 @@
 /*
- * include/framework/DynamicExtension.h
+ * include/framework/util/Configuration.h
  *
- * Copyright (C) 2023 Douglas Rumbaugh <drumbaugh@psu.edu> 
- *                    Dong Xie <dongx@psu.edu>
+ * Copyright (C) 2023 Douglas B. Rumbaugh <drumbaugh@psu.edu> 
  *
  * All rights reserved. Published under the Modified BSD License.
  *
diff --git a/include/shard/MemISAM.h b/include/shard/MemISAM.h
index f9c621e..8ca5cee 100644
--- a/include/shard/MemISAM.h
+++ b/include/shard/MemISAM.h
@@ -1,7 +1,7 @@
 /*
  * include/shard/MemISAM.h
  *
- * Copyright (C) 2023 Douglas Rumbaugh <drumbaugh@psu.edu> 
+ * Copyright (C) 2023 Douglas B. Rumbaugh <drumbaugh@psu.edu> 
  *                    Dong Xie <dongx@psu.edu>
  *
  * All rights reserved. Published under the Modified BSD License.
@@ -264,6 +264,10 @@ public:
         return m_internal_node_cnt * inmem_isam_node_size + m_alloc_size;
     }
 
+    size_t get_aux_memory_usage() {
+        return 0;
+    }
+
 private:
     size_t get_lower_bound(const K& key) const {
         const InMemISAMNode* now = m_root;
diff --git a/include/shard/PGM.h b/include/shard/PGM.h
index d960e70..6d76376 100644
--- a/include/shard/PGM.h
+++ b/include/shard/PGM.h
@@ -235,6 +235,10 @@ public:
         return m_pgm.size_in_bytes() + m_alloc_size;
     }
 
+    size_t get_aux_memory_usage() {
+        return 0;
+    }
+
     size_t get_lower_bound(const K& key) const {
         auto bound = m_pgm.search(key);
         size_t idx = bound.lo;
diff --git a/include/shard/TrieSpline.h b/include/shard/TrieSpline.h
index 98153c0..a784a38 100644
--- a/include/shard/TrieSpline.h
+++ b/include/shard/TrieSpline.h
@@ -250,6 +250,10 @@ public:
         return m_ts.GetSize() + m_alloc_size;
     }
 
+    size_t get_aux_memory_usage() {
+        return 0;
+    }
+
 private:
 
     size_t get_lower_bound(const K& key) const {
diff --git a/include/shard/VPTree.h b/include/shard/VPTree.h
index 0e998d9..d9a15b1 100644
--- a/include/shard/VPTree.h
+++ b/include/shard/VPTree.h
@@ -1,9 +1,9 @@
 /*
  * include/shard/VPTree.h
  *
- * Copyright (C) 2023 Douglas Rumbaugh <drumbaugh@psu.edu>
+ * Copyright (C) 2023 Douglas B. Rumbaugh <drumbaugh@psu.edu>
  *
- * All outsides reserved. Published under the Modified BSD License.
+ * All rights reserved. Published under the Modified BSD License.
  *
  */
 #pragma once
@@ -240,6 +240,11 @@ public:
         return m_node_cnt * sizeof(vpnode) + m_reccnt * sizeof(R*) + m_alloc_size;
     }
 
+    size_t get_aux_memory_usage() {
+        return 0;
+    }
+
+
 private:
 
     vpnode *build_vptree() {
diff --git a/include/shard/WIRS.h b/include/shard/WIRS.h
index 83573c8..bf29325 100644
--- a/include/shard/WIRS.h
+++ b/include/shard/WIRS.h
@@ -2,7 +2,7 @@
  * include/shard/WIRS.h
  *
  * Copyright (C) 2023 Dong Xie <dongx@psu.edu>
- *                    Douglas Rumbaugh <drumbaugh@psu.edu>
+ *                    Douglas B. Rumbaugh <drumbaugh@psu.edu>
  *
  * All rights reserved. Published under the Modified BSD License.
  *
@@ -260,6 +260,10 @@ public:
         return m_alloc_size + m_node_cnt * sizeof(wirs_node<Wrapped<R>>);
     }
 
+    size_t get_aux_memory_usage() {
+        return 0;
+    }
+
 private:
 
     size_t get_lower_bound(const K& key) const {
diff --git a/include/shard/WSS.h b/include/shard/WSS.h
index 87b016c..4e3a326 100644
--- a/include/shard/WSS.h
+++ b/include/shard/WSS.h
@@ -1,8 +1,8 @@
 /*
  * include/shard/WSS.h
  *
- * Copyright (C) 2023 Dong Xie <dongx@psu.edu>
- *                    Douglas Rumbaugh <drumbaugh@psu.edu>
+ * Copyright (C) 2023 Douglas B. Rumbaugh <drumbaugh@psu.edu>
+ *                    Dong Xie <dongx@psu.edu>
  *
  * All rights reserved. Published under the Modified BSD License.
  *
@@ -243,6 +243,10 @@ public:
         return m_alloc_size;
     }
 
+    size_t get_aux_memory_usage() {
+        return 0;
+    }
+
 private:
 
     size_t get_lower_bound(const K& key) const {
diff --git a/include/util/Cursor.h b/include/util/Cursor.h
index 1cf20e1..00afaab 100644
--- a/include/util/Cursor.h
+++ b/include/util/Cursor.h
@@ -1,11 +1,13 @@
 /*
  * include/util/Cursor.h
  *
- * Copyright (C) 2023 Douglas Rumbaugh <drumbaugh@psu.edu> 
+ * Copyright (C) 2023 Douglas B. Rumbaugh <drumbaugh@psu.edu> 
  *                    Dong Xie <dongx@psu.edu>
  *
  * All rights reserved. Published under the Modified BSD License.
  *
+ * A simple record cursor type with associated methods for help in
+ * merging record sets when constructing shards. 
  */
 #pragma once
 
diff --git a/include/util/bf_config.h b/include/util/bf_config.h
index 2390643..4de465d 100644
--- a/include/util/bf_config.h
+++ b/include/util/bf_config.h
@@ -1,11 +1,17 @@
 /*
  * include/util/bf_config.h
  *
- * Copyright (C) 2023 Douglas Rumbaugh <drumbaugh@psu.edu> 
+ * Copyright (C) 2023 Douglas B. Rumbaugh <drumbaugh@psu.edu> 
  *                    Dong Xie <dongx@psu.edu>
  *
  * All rights reserved. Published under the Modified BSD License.
  *
+ * Global parameters for configuring bloom filters used as auxiliary
+ * structures on shards within the framework. The bloom filters themselves
+ * can be found in
+ *
+ * $PROJECT_ROOT/external/psudb-common/cpp/include/psu-ds/BloomFilter.h
+ *
  */
 #pragma once
 
@@ -13,13 +19,25 @@
 
 namespace de {
 
+/* global variable for specifying bloom filter FPR */
 static double BF_FPR = .01;
+
+/* global variable for specifying number of BF hash functions (k) */
 static size_t BF_HASH_FUNCS = 7;
 
+/*
+ * Adjust the value of BF_FPR. The argument must be on the interval 
+ * (0, 1), or the behavior of bloom filters is undefined.
+ */
 static void BF_SET_FPR(double fpr) {
+
     BF_FPR = fpr;
 }
 
+/*
+ * Adjust the value of BF_HASH_FUNCS. The argument must be on the interval
+ * (0, INT64_MAX], or the behavior of bloom filters is undefined.
+ */
 static void BF_SET_HASHFUNC(size_t func_cnt) {
     BF_HASH_FUNCS = func_cnt;
 }
diff --git a/include/util/types.h b/include/util/types.h
index 3010e78..b7f9607 100644
--- a/include/util/types.h
+++ b/include/util/types.h
@@ -1,11 +1,11 @@
 /*
  * include/util/types.h
  *
- * Copyright (C) 2023 Douglas Rumbaugh <drumbaugh@psu.edu>
+ * Copyright (C) 2023 Douglas B. Rumbaugh <drumbaugh@psu.edu>
  *
  * All rights reserved. Published under the Modified BSD License.
  *
- * A centralized header file for various datatypes used throughout the
+ * A centralized header file for various data types used throughout the
  * code base. There are a few very specific types, such as header formats,
  * that are defined within the header files that make direct use of them,
  * but all generally usable, simple types are defined here.
@@ -22,33 +22,41 @@ namespace de {
 
 using std::byte;
 
-// Represents a page offset within a specific file (physical or virtual)
+/* Represents a page offset within a specific file (physical or virtual) */
 typedef uint32_t PageNum;
 
-// Byte offset within a page. Also used for lengths of records, etc.,
-// within the codebase. size_t isn't necessary, as the maximum offset
-// is only parm::PAGE_SIZE 
+/*
+ * Byte offset within a page. Also used for lengths of records, etc.,
+ * within the codebase. size_t isn't necessary, as the maximum offset
+ * is only parm::PAGE_SIZE 
+ */
 typedef uint16_t PageOffset;
 
-// A unique identifier for a frame within a buffer or cache.
+/* A unique identifier for a frame within a buffer or cache */
 typedef int32_t FrameId;
 
-// A unique timestamp for use in MVCC concurrency control. Currently stored in
-// record headers, but not used by anything.
+/* 
+ * A unique timestamp for use in MVCC concurrency control. Currently stored in
+ * record headers, but not used by anything.
+ */
 typedef uint32_t Timestamp;
 const Timestamp TIMESTAMP_MIN = 0;
 const Timestamp TIMESTAMP_MAX = UINT32_MAX;
 
-// Invalid values for various IDs. Used throughout the code base to indicate
-// uninitialized values and error conditions.
+/* 
+ * Invalid values for various IDs. Used throughout the code base to indicate
+ * uninitialized values and error conditions.
+ */
 const PageNum INVALID_PNUM = 0;
 const FrameId INVALID_FRID = -1;
 
-// An ID for a given shard within the index. The level_idx is the index
-// in the memory_levels and disk_levels vectors corresponding to the
-// shard, and the shard_idx is the index with the level (always 0 in the
-// case of leveling). Note that the two vectors of levels are treated
-// as a contiguous index space.
+/*
+ * An ID for a given shard within the index. The level_idx is the index
+ * in the memory_levels and disk_levels vectors corresponding to the
+ * shard, and the shard_idx is the index with the level (always 0 in the
+ * case of leveling). Note that the two vectors of levels are treated
+ * as a contiguous index space.
+ */
 struct ShardID {
     ssize_t level_idx;
     ssize_t shard_idx;
@@ -58,12 +66,7 @@ struct ShardID {
     }
 };
 
+/* A placeholder for an invalid shard--also used to indicate the mutable buffer */
 const ShardID INVALID_SHID = {-1, -1};
 
-struct SampleRange {
-    ShardID shid;
-    size_t low;
-    size_t high;
-};
-
 }