Add BDD memory management via preserve and sweep operations

Implemented commands for preserving, unpreserving, and sweeping Binary Decision Diagrams (BDDs). Enhanced the interpreter, parser, lexer, and documentation to support these features, and added comprehensive tests for validation.

Author: BrandonTang89

.idea/dictionaries/project.xml

@@ -71,6 +71,7 @@ add_executable(${PROJECT_NAME}
         src/walker_bdd_manip.cpp
         src/token.h
         src/walker_bdd_substitute.cpp
+        src/walker_sweep.cpp
 )
 target_link_libraries(${PROJECT_NAME} abseil::abseil)
 
@@ -90,6 +91,7 @@ add_executable(tests
         src/token.h
         tests/test_lexer.cpp
         src/walker_bdd_substitute.cpp
+        src/walker_sweep.cpp
 )
 target_link_libraries(tests PRIVATE Catch2::Catch2WithMain abseil::abseil)
 add_test(NAME bdd_engine_tests COMMAND tests)

CMakeLists.txt

@@ -5,13 +5,6 @@
 C++ Implementation of Reduced Ordered [Binary Decision Diagrams](https://en.wikipedia.org/wiki/Binary_decision_diagram)
 for Propositional Formulae Manipulation.
 
-## Todo
-
-*Meta Features*
-
-- Implement garbage sweeping of unreachable BDD nodes
-- Web GUI using WASM
-
 # Language
 
 ## Grammar
@@ -27,16 +20,21 @@ statements:
 statement: 
     | "bvar" IDENTIFIER* ";"
     | "set" IDENTIFIER "=" expression ";"
-    | function_name expression* ";"
+    | function_call ";"
     | expression ";"
 
-function_name
-    | "display_tree" 
-    | "display_graph"
-    | "is_sat"
-    | "source"
+function_call
+    | "display_tree" expression
+    | "display_graph" expression
+    | "is_sat" expression
+    | "source" FILENAME
     | "clear_cache"
-
+    | "preserve" IDENTIFIER*;
+    | "preserve_all";
+    | "unpreserve" IDENTIFIER*;
+    | "unpreserve_all";
+    | "sweep";
+    
 expression:
     | "sub" "{" (IDENTIFIER ":" expression ("," IDENTIFIER ":" expression)*)? "}" expression
     | equality
@@ -91,12 +89,12 @@ execution will not continue after the error.
 
 ## Statements
 
-A statement is either
+Statements are used to
 
-- a BDD variable declaration
-- an assignment
-- a function call
-- an expression statement
+- Declare symbolic variables
+- Do assignments
+- Call functions for BDD queries or memory management
+- Evaluate expressions
 
 ### Symbolic Variable Declaration
 
@@ -110,6 +108,9 @@ This will create two symbolic variables `x` and `y`.
 
 The order in which symbolic variables are declared is important as this is their order within the BDDs.
 
+The BDD order cannot be changed without restarting the REPL or reloading the script since that would invalidate existing
+BDDs.
+
 ### Assignments
 
 We can assign BDDs to any non-symbolic variables using the `set` keyword.
@@ -120,7 +121,7 @@ set b = !x | y;
 set c = a & b;
 ```
 
-### Built-in Functions
+### BDD Query Functions
 
 We have a few built-in functions to query about the BDDs:
 
@@ -155,6 +156,8 @@ satisfiable or not.
 
 This reachability check is done with breath-first search (BFS)
 
+### Loading and Running Scripts
+
 #### Run a script file
 
 ```
@@ -170,7 +173,9 @@ The filename should only consist of the following characters:
 - Underscore (`_`)
 - Dot (`.`)
 
-### Clearing Caches
+### Memory Management and Garbage Collection
+
+#### clear_cache
 
 The interpreter has caches for:
 
@@ -190,6 +195,76 @@ clear_cache;
 
 Will clear all of these caches.
 
+#### preserve
+
+Marks one or more BDDs as protected from garbage collection. When you preserve a BDD, it will not be deleted during a
+sweep operation, even if there are no other references to it.
+
+```
+set a = x & y;    // Create a BDD
+preserve a;       // Mark 'a' as preserved
+sweep;            // 'a' will be kept in memory
+```
+
+You can preserve multiple BDDs by listing them:
+
+```
+preserve a b c;   // Preserve BDDs named 'a', 'b', and 'c'
+```
+
+#### preserve_all
+
+Marks all currently existing BDDs as preserved. This is useful when you want to ensure that your entire working set is
+protected from garbage collection.
+
+```
+set a = x & y;
+set b = x | z;
+preserve_all;     // Both 'a' and 'b' are now preserved
+sweep;            // Nothing will be deleted
+```
+
+#### unpreserve
+
+Removes the preservation mark from one or more BDDs, making them eligible for garbage collection during the next sweep.
+
+```
+preserve_all;     // Preserve all BDDs
+unpreserve b;     // Make 'b' eligible for deletion
+sweep;            // 'b' will be deleted
+```
+
+#### unpreserve_all
+
+Removes the preservation mark from all BDDs, making all of them eligible for garbage collection.
+
+```
+preserve_all;
+unpreserve_all;   // No BDDs are preserved anymore
+sweep;            // All unpreserved BDDs will be deleted
+```
+
+#### sweep
+
+Performs garbage collection, removing all non-preserved BDDs from memory. This helps manage memory usage by cleaning up
+BDDs that are no longer needed.
+
+Sweep automatically calls `clear_cache` to ensure the caches are valid.
+
+```
+set a = x & y;
+set b = a | z;
+preserve a;
+sweep;            // 'b' will be deleted, but 'a' remains
+```
+
+#### Notes
+
+- The garbage collector always preserves the TRUE and FALSE nodes (BDD IDs 0 and 1)
+- When sweeping, all intermediate BDD nodes that are only referenced by deleted BDDs will also be removed
+- Attempting to preserve a non-existent BDD or a symbolic variable will result in an error message
+- Preserving a BDD preserves all nodes in its structure, including shared nodes used by other BDDs
+
 ### Expression Statements
 
 An expression statement is simply an expression that is evaluated.
@@ -355,6 +430,7 @@ The project is a tree-walk interpreter, so it has three internal parts:
     - `walker_bdd_substitute.cpp` implements the run-time substitution of variables in BDDs
     - `walker_bdd_manip.cpp` implements the run-time construction and manipulation of BDDs
     - `walker_bdd_view.cpp` implements queries about the BDDs, such as satisfiability and display functions
+    - `walker_sweep.cpp` implements memory management operations such as sweeping and cache clearing
 
 The REPL and overall application are implemented by the following
 

README.md

@@ -55,8 +55,10 @@ std::string stmt_repr(const stmt& statement) {
                 for (const auto& arg : s.arguments) {
                     result += expr_repr(*arg) + ", ";
                 }
-                result.pop_back();  // Remove last space
-                result.pop_back();  // Remove last comma
+                if (!s.arguments.empty()) {
+                    result.pop_back();  // Remove last space
+                    result.pop_back();  // Remove last comma
+                }
                 result += "))";
                 return result;
             } else if constexpr (std::is_same_v<T, decl_stmt>) {

src/ast.cpp

@@ -6,4 +6,5 @@ constexpr bool print_tokens = false;  // Set to true to print tokens
 constexpr bool print_ast = false;     // Set to true to print AST
 constexpr auto warning_level = absl::LogSeverity::kWarning;
 
-constexpr bool use_colours = true;  // Set to true to enable coloured parser errors
+// Set to true to enable coloured parser errors
+constexpr bool use_colours = true;

src/config.h

@@ -11,10 +11,15 @@ const std::unordered_map<std::string, token::Type> keyword_map = {
     {"display_graph", token::Type::GRAPH_DISPLAY},
     {"is_sat", token::Type::IS_SAT},
     {"source", token::Type::SOURCE},
-    {"clear_cache", token::Type::CLEAR_CACHE},
+    {"sub", token::Type::SUBSTITUTE},
     {"exists", token::Type::EXISTS},
     {"forall", token::Type::FORALL},
-    {"sub", token::Type::SUBSTITUTE},
+    {"clear_cache", token::Type::CLEAR_CACHE},
+    {"preserve", token::Type::PRESERVE},
+    {"preserve_all", token::Type::PRESERVE_ALL},
+    {"unpreserve", token::Type::UNPRESERVE},
+    {"unpreserve_all", token::Type::UNPRESERVE_ALL},
+    {"sweep", token::Type::SWEEP},
 };
 
 constexpr bool is_lexeme_char(const char c) {
@@ -108,7 +113,7 @@ lex_result_t scan_to_tokens(const std::string& source) {
                     tokens.emplace_back(token::Type::ID, std::to_string(number),
                                         number);
                 } else {
-                    return std::unexpected<LexerException>(LexerException(
+                    return std::unexpected(LexerException(
                         "Unexpected character: " + std::string(1, c),
                         __func__));
                 }

src/lexer.cpp

@@ -47,6 +47,11 @@ stmt parse_statement(const_span& sp) {
         case token::Type::IS_SAT:
         case token::Type::SOURCE:
         case token::Type::CLEAR_CACHE:
+        case token::Type::PRESERVE:
+        case token::Type::PRESERVE_ALL:
+        case token::Type::UNPRESERVE:
+        case token::Type::UNPRESERVE_ALL:
+        case token::Type::SWEEP:
             return parse_func_call(sp);
         default:  // assume expr statement
             return parse_expr_stmt(sp);

src/parser.cpp

@@ -41,16 +41,22 @@ struct token {
         GRAPH_DISPLAY,
         IS_SAT,
         SOURCE,
-        CLEAR_CACHE,
 
         // Special Keywords for quantifiers
         EXISTS,
         FORALL,
 
+        // Special Keywords for memory management
+        CLEAR_CACHE,
+        PRESERVE,
+        UNPRESERVE,
+        PRESERVE_ALL,
+        UNPRESERVE_ALL,
+        SWEEP,
     };
 
     Type type;
-    std::string lexeme;               // the text of the token
+    std::string lexeme;                     // the text of the token
     std::optional<uint32_t> token_value{};  // optional value for number tokens
 
     token(const Type type, const std::string& lexeme,
@@ -62,7 +68,9 @@ struct token {
     std::string repr() const {
         return "Token(" + std::to_string(static_cast<int>(type)) + ", " +
                lexeme +
-               (token_value.has_value() ? ", " + std::to_string(token_value.value()) : "") +
+               (token_value.has_value()
+                    ? ", " + std::to_string(token_value.value())
+                    : "") +
                ")";
     }
 };

src/token.h

@@ -181,7 +181,7 @@ void Walker::walk_func_call_stmt(const func_call_stmt& statement) {
             auto filename =
                 std::get<identifier>(*statement.arguments[0]).name.lexeme;
 
-            // Read all of the file into the buffer
+            // Read all the file into the buffer
             std::string buffer;
             std::ifstream f(filename);
             if (!f.is_open()) {
@@ -225,6 +225,69 @@ void Walker::walk_func_call_stmt(const func_call_stmt& statement) {
             out << "Cleared all caches" << '\n';
             break;
         }
+        case token::Type::PRESERVE: {
+            for (const auto& arg : statement.arguments) {
+                if (!std::holds_alternative<identifier>(*arg)) {
+                    throw ExecutionException(
+                        "Invalid argument type for preserve", __func__);
+                }
+                if (const auto& id = std::get<identifier>(*arg).name.lexeme;
+                    globals.contains(id)) {
+                    if (std::holds_alternative<Bdd_ptype>(globals[id])) {
+                        std::get<Bdd_ptype>(globals[id]).preserved = true;
+                        out << "Preserved BDD: " << id << '\n';
+                    } else {
+                        out << "Variable is not a BDD: " << id << '\n';
+                    }
+                } else {
+                    out << "Variable not found: " << id << '\n';
+                }
+            }
+            break;
+        }
+        case token::Type::PRESERVE_ALL: {
+            for (auto& [name, value] : globals) {
+                if (std::holds_alternative<Bdd_ptype>(value)) {
+                    std::get<Bdd_ptype>(value).preserved = true;
+                    out << "Preserved BDD: " << name << '\n';
+                }
+            }
+            break;
+        }
+        case token::Type::UNPRESERVE: {
+            for (const auto& arg : statement.arguments) {
+                if (!std::holds_alternative<identifier>(*arg)) {
+                    throw ExecutionException(
+                        "Invalid argument type for unpreserve", __func__);
+                }
+                if (const auto& id = std::get<identifier>(*arg).name.lexeme;
+                    globals.contains(id)) {
+                    if (std::holds_alternative<Bdd_ptype>(globals[id])) {
+                        std::get<Bdd_ptype>(globals[id]).preserved = false;
+                        out << "Unpreserved BDD: " << id << '\n';
+                    } else {
+                        out << "Variable is not a BDD: " << id << '\n';
+                    }
+                } else {
+                    out << "Variable not found: " << id << '\n';
+                }
+            }
+            break;
+        }
+        case token::Type::UNPRESERVE_ALL: {
+            for (auto& [name, value] : globals) {
+                if (std::holds_alternative<Bdd_ptype>(value)) {
+                    std::get<Bdd_ptype>(value).preserved = false;
+                    out << "Unpreserved BDD: " << name << '\n';
+                }
+            }
+            break;
+        }
+        case token::Type::SWEEP: {
+            sweep();
+            out << "Swept all non-preserved BDDs" << '\n';
+            break;
+        }
         default:
             throw ExecutionException("Unknown function call", __func__);
     }