P1 F2025 Rewrite (#836)

- Add ARC replacer 
- Change disk scheduler interfaces to take a vector
- Bump page size to 8kb

Author: songwdfu

.github/workflows/cmake.yml

@@ -40,12 +40,6 @@ jobs:
               format: "/opt/homebrew/opt/llvm@15/bin/clang-format",
               tidy: "/opt/homebrew/opt/llvm@15/bin/clang-tidy",
             }
-          - {
-              name: "macOS 15 (Sequoia) AppleClang",
-              os: macos-15,
-              format: "/opt/homebrew/opt/llvm@15/bin/clang-format",
-              tidy: "/opt/homebrew/opt/llvm@15/bin/clang-tidy",
-          }
     steps:
       - uses: actions/checkout@v2
 

CMakeLists.txt

@@ -274,8 +274,8 @@ add_custom_target(submit-p0
 )
 
 set(P1_FILES
-        "src/include/buffer/lru_k_replacer.h"
-        "src/buffer/lru_k_replacer.cpp"
+        "src/include/buffer/arc_replacer.h"
+        "src/buffer/arc_replacer.cpp"
         "src/include/buffer/buffer_pool_manager.h"
         "src/buffer/buffer_pool_manager.cpp"
         "src/include/storage/disk/disk_scheduler.h"

src/buffer/CMakeLists.txt

@@ -2,6 +2,7 @@ add_library(
         bustub_buffer
         OBJECT
         buffer_pool_manager.cpp
+        arc_replacer.cpp
         clock_replacer.cpp
         lru_replacer.cpp
         lru_k_replacer.cpp)

src/buffer/arc_replacer.cpp

@@ -0,0 +1,126 @@
+// :bustub-keep-private:
+//===----------------------------------------------------------------------===//
+//
+//                         BusTub
+//
+// arc_replacer.cpp
+//
+// Identification: src/buffer/arc_replacer.cpp
+//
+// Copyright (c) 2015-2025, Carnegie Mellon University Database Group
+//
+//===----------------------------------------------------------------------===//
+
+#include "buffer/arc_replacer.h"
+#include <optional>
+#include "common/config.h"
+
+namespace bustub {
+
+/**
+ *
+ * TODO(P1): Add implementation
+ *
+ * @brief a new ArcReplacer, with lists initialized to be empty and target size to 0
+ * @param num_frames the maximum number of frames the ArcReplacer will be required to cache
+ */
+ArcReplacer::ArcReplacer(size_t num_frames) : replacer_size_(num_frames) {}
+
+/**
+ * TODO(P1): Add implementation
+ *
+ * @brief Performs the Replace operation as described by the writeup
+ * that evicts from either mfu_ or mru_ into its corresponding ghost list
+ * according to balancing policy.
+ *
+ * If you wish to refer to the original ARC paper, please note that there are
+ * two changes in our implementation:
+ * 1. When the size of mru_ equals the target size, we don't check
+ * the last access as the paper did when deciding which list to evict from.
+ * This is fine since the original decision is stated to be arbitrary.
+ * 2. Entries that are not evictable are skipped. If all entries from the desired side
+ * (mru_ / mfu_) are pinned, we instead try victimize the other side (mfu_ / mru_),
+ * and move it to its corresponding ghost list (mfu_ghost_ / mru_ghost_).
+ *
+ * @return frame id of the evicted frame, or std::nullopt if cannot evict
+ */
+auto ArcReplacer::Evict() -> std::optional<frame_id_t> { return std::nullopt; }
+
+/**
+ * TODO(P1): Add implementation
+ *
+ * @brief Record access to a frame, adjusting ARC bookkeeping accordingly
+ * by bring the accessed page to the front of mfu_ if it exists in any of the lists
+ * or the front of mru_ if it does not.
+ *
+ * Performs the operations EXCEPT REPLACE described in original paper, which is
+ * handled by `Evict()`.
+ *
+ * Consider the following four cases, handle accordingly:
+ * 1. Access hits mru_ or mfu_
+ * 2/3. Access hits mru_ghost_ / mfu_ghost_
+ * 4. Access misses all the lists
+ *
+ * This routine performs all changes to the four lists as preperation
+ * for `Evict()` to simply find and evict a victim into ghost lists.
+ *
+ * Note that frame_id is used as identifier for alive pages and
+ * page_id is used as identifier for the ghost pages, since page_id is
+ * the unique identifier to the page after it's dead.
+ * Using page_id for alive pages should be the same since it's one to one mapping,
+ * but using frame_id is slightly more intuitive.
+ *
+ * @param frame_id id of frame that received a new access.
+ * @param page_id id of page that is mapped to the frame.
+ * @param access_type type of access that was received. This parameter is only needed for
+ * leaderboard tests.
+ */
+void ArcReplacer::RecordAccess(frame_id_t frame_id, page_id_t page_id, [[maybe_unused]] AccessType access_type) {}
+
+/**
+ * TODO(P1): Add implementation
+ *
+ * @brief Toggle whether a frame is evictable or non-evictable. This function also
+ * controls replacer's size. Note that size is equal to number of evictable entries.
+ *
+ * If a frame was previously evictable and is to be set to non-evictable, then size should
+ * decrement. If a frame was previously non-evictable and is to be set to evictable,
+ * then size should increment.
+ *
+ * If frame id is invalid, throw an exception or abort the process.
+ *
+ * For other scenarios, this function should terminate without modifying anything.
+ *
+ * @param frame_id id of frame whose 'evictable' status will be modified
+ * @param set_evictable whether the given frame is evictable or not
+ */
+void ArcReplacer::SetEvictable(frame_id_t frame_id, bool set_evictable) {}
+
+/**
+ * TODO(P1): Add implementation
+ *
+ * @brief Remove an evictable frame from replacer.
+ * This function should also decrement replacer's size if removal is successful.
+ *
+ * Note that this is different from evicting a frame, which always remove the frame
+ * decided by the ARC algorithm.
+ *
+ * If Remove is called on a non-evictable frame, throw an exception or abort the
+ * process.
+ *
+ * If specified frame is not found, directly return from this function.
+ *
+ * @param frame_id id of frame to be removed
+ */
+void ArcReplacer::Remove(frame_id_t frame_id) {}
+
+/**
+ * TODO(P1): Add implementation
+ *
+ * @brief Return replacer's size, which tracks the number of evictable frames.
+ *
+ * @return size_t
+ */
+auto ArcReplacer::Size() -> size_t { return 0; }
+
+}  // namespace bustub

src/buffer/buffer_pool_manager.cpp

@@ -11,6 +11,9 @@
 //===----------------------------------------------------------------------===//
 
 #include "buffer/buffer_pool_manager.h"
+#include "buffer/arc_replacer.h"
+#include "common/config.h"
+#include "common/macros.h"
 
 namespace bustub {
 
@@ -63,15 +66,13 @@ void FrameHeader::Reset() {
  *
  * @param num_frames The size of the buffer pool.
  * @param disk_manager The disk manager.
- * @param k_dist The backward k-distance for the LRU-K replacer.
  * @param log_manager The log manager. Please ignore this for P1.
  */
-BufferPoolManager::BufferPoolManager(size_t num_frames, DiskManager *disk_manager, size_t k_dist,
-                                     LogManager *log_manager)
+BufferPoolManager::BufferPoolManager(size_t num_frames, DiskManager *disk_manager, LogManager *log_manager)
     : num_frames_(num_frames),
       next_page_id_(0),
       bpm_latch_(std::make_shared<std::mutex>()),
-      replacer_(std::make_shared<LRUKReplacer>(num_frames, k_dist)),
+      replacer_(std::make_shared<ArcReplacer>(num_frames)),
       disk_scheduler_(std::make_shared<DiskScheduler>(disk_manager)),
       log_manager_(log_manager) {
   // Not strictly necessary...
@@ -342,11 +343,13 @@ void BufferPoolManager::FlushAllPages() { UNIMPLEMENTED("TODO(P1): Add implement
  * # Implementation
  *
  * We will use this function to test if your buffer pool manager is managing pin counts correctly. Since the
- * `pin_count_` field in `FrameHeader` is an [atomic type](https://en.cppreference.com/w/cpp/atomic/atomic),
- * you do not need to take the latch on the frame that holds the
+ * `pin_count_` field in `FrameHeader` is an atomic type, you do not need to take the latch on the frame that holds the
  * page we want to look at. Instead, you can simply use an atomic `load` to safely load the value stored. You will still
  * need to take the buffer pool latch, however.
  *
+ * Again, if you are unfamiliar with atomic types, see the official C++ docs
+ * [here](https://en.cppreference.com/w/cpp/atomic/atomic).
+ *
  * TODO(P1): Add implementation
  *
  * @param page_id The page ID of the page we want to get the pin count of.

src/common/bustub_instance.cpp

@@ -74,8 +74,7 @@ BusTubInstance::BusTubInstance(const std::filesystem::path &db_file_name, size_t
   // We need more frames for GenerateTestTable to work. Therefore, we use 128 instead of the default
   // buffer pool size specified in `config.h`.
   try {
-    buffer_pool_manager_ =
-        std::make_unique<BufferPoolManager>(bpm_size, disk_manager_.get(), LRUK_REPLACER_K, log_manager_.get());
+    buffer_pool_manager_ = std::make_unique<BufferPoolManager>(bpm_size, disk_manager_.get(), log_manager_.get());
   } catch (NotImplementedException &e) {
     std::cerr << "BufferPoolManager is not implemented, only mock tables are supported." << std::endl;
     buffer_pool_manager_ = nullptr;
@@ -127,8 +126,7 @@ BusTubInstance::BusTubInstance(size_t bpm_size) {
   // We need more frames for GenerateTestTable to work. Therefore, we use 128 instead of the default
   // buffer pool size specified in `config.h`.
   try {
-    buffer_pool_manager_ =
-        std::make_unique<BufferPoolManager>(bpm_size, disk_manager_.get(), LRUK_REPLACER_K, log_manager_.get());
+    buffer_pool_manager_ = std::make_unique<BufferPoolManager>(bpm_size, disk_manager_.get(), log_manager_.get());
   } catch (NotImplementedException &e) {
     std::cerr << "BufferPoolManager is not implemented, only mock tables are supported." << std::endl;
     buffer_pool_manager_ = nullptr;

src/include/buffer/arc_replacer.h

@@ -0,0 +1,90 @@
+
+//===----------------------------------------------------------------------===//
+//
+//                         BusTub
+//
+// arc_replacer.h
+//
+// Identification: src/include/buffer/arc_replacer.h
+//
+// Copyright (c) 2015-2025, Carnegie Mellon University Database Group
+//
+//===----------------------------------------------------------------------===//
+
+#pragma once
+
+#include <list>
+#include <memory>
+#include <mutex>  // NOLINT
+#include <optional>
+#include <unordered_map>
+
+#include "common/config.h"
+#include "common/macros.h"
+
+namespace bustub {
+
+enum class AccessType { Unknown = 0, Lookup, Scan, Index };
+
+enum class ArcStatus { MRU, MFU, MRU_GHOST, MFU_GHOST };
+
+// TODO(student): You can modify or remove this struct as you like.
+struct FrameStatus {
+  page_id_t page_id_;
+  frame_id_t frame_id_;
+  bool evictable_;
+  ArcStatus arc_status_;
+  FrameStatus(page_id_t pid, frame_id_t fid, bool ev, ArcStatus st)
+      : page_id_(pid), frame_id_(fid), evictable_(ev), arc_status_(st) {}
+};
+
+/**
+ * ArcReplacer implements the ARC replacement policy.
+ */
+class ArcReplacer {
+ public:
+  explicit ArcReplacer(size_t num_frames);
+
+  DISALLOW_COPY_AND_MOVE(ArcReplacer);
+
+  /**
+   * TODO(P1): Add implementation
+   *
+   * @brief Destroys the LRUReplacer.
+   */
+  ~ArcReplacer() = default;
+
+  auto Evict() -> std::optional<frame_id_t>;
+  void RecordAccess(frame_id_t frame_id, page_id_t page_id, AccessType access_type = AccessType::Unknown);
+  void SetEvictable(frame_id_t frame_id, bool set_evictable);
+  void Remove(frame_id_t frame_id);
+  auto Size() -> size_t;
+
+ private:
+  // TODO(student): implement me! You can replace or remove these member variables as you like.
+  std::list<frame_id_t> mru_;
+  std::list<frame_id_t> mfu_;
+  std::list<page_id_t> mru_ghost_;
+  std::list<page_id_t> mfu_ghost_;
+
+  /* record entries in mru_ and mfu_
+   * this uses frame_id_t to guarantee no duplicate records for the same
+   * frame when they are alive */
+  std::unordered_map<frame_id_t, std::shared_ptr<FrameStatus>> alive_map_;
+  /* record entries in mru_ghost_ and mfu_ghost_
+   * this uses page_id_t but not frame_id_t because page_id is the unique
+   * identifier in ghost lists */
+  std::unordered_map<page_id_t, std::shared_ptr<FrameStatus>> ghost_map_;
+
+  /* alive, evictable entries count */
+  [[maybe_unused]] size_t curr_size_{0};
+  /* p as in original paper */
+  [[maybe_unused]] size_t mru_target_size_{0};
+  /* c as in original paper */
+  [[maybe_unused]] size_t replacer_size_;
+  std::mutex latch_;
+
+  // TODO(student): You can add member variables / functions as you like.
+};
+
+}  // namespace bustub

src/include/buffer/buffer_pool_manager.h

@@ -18,7 +18,7 @@
 #include <unordered_map>
 #include <vector>
 
-#include "buffer/lru_k_replacer.h"
+#include "buffer/arc_replacer.h"
 #include "common/config.h"
 #include "recovery/log_manager.h"
 #include "storage/disk/disk_scheduler.h"
@@ -105,12 +105,11 @@ class FrameHeader {
  * faster access, and evicting unused or cold pages back out to storage.
  *
  * Make sure you read the writeup in its entirety before attempting to implement the buffer pool manager. You also need
- * to have completed the implementation of both the `LRUKReplacer` and `DiskManager` classes.
+ * to have completed the implementation of both the `ArcReplacer` and `DiskManager` classes.
  */
 class BufferPoolManager {
  public:
-  BufferPoolManager(size_t num_frames, DiskManager *disk_manager, size_t k_dist = LRUK_REPLACER_K,
-                    LogManager *log_manager = nullptr);
+  BufferPoolManager(size_t num_frames, DiskManager *disk_manager, LogManager *log_manager = nullptr);
   ~BufferPoolManager();
 
   auto Size() const -> size_t;
@@ -151,7 +150,7 @@ class BufferPoolManager {
   std::list<frame_id_t> free_frames_;
 
   /** @brief The replacer to find unpinned / candidate pages for eviction. */
-  std::shared_ptr<LRUKReplacer> replacer_;
+  std::shared_ptr<ArcReplacer> replacer_;
 
   /** @brief A pointer to the disk scheduler. Shared with the page guards for flushing. */
   std::shared_ptr<DiskScheduler> disk_scheduler_;

src/include/buffer/lru_k_replacer.h

@@ -19,13 +19,12 @@
 #include <unordered_map>
 #include <vector>
 
+#include "buffer/arc_replacer.h"
 #include "common/config.h"
 #include "common/macros.h"
 
 namespace bustub {
 
-enum class AccessType { Unknown = 0, Lookup, Scan, Index };
-
 class LRUKNode {
  private:
   /** History of last seen K timestamps of this page. Least recent timestamp stored in front. */

src/include/common/config.h

@@ -35,7 +35,7 @@ static constexpr int INVALID_PAGE_ID = -1;   // invalid page id
 static constexpr int INVALID_TXN_ID = -1;    // invalid transaction id
 static constexpr int INVALID_LSN = -1;       // invalid log sequence number
 
-static constexpr int BUSTUB_PAGE_SIZE = 4096;                                        // size of a data page in byte
+static constexpr int BUSTUB_PAGE_SIZE = 8192;                                        // size of a data page in byte
 static constexpr int BUFFER_POOL_SIZE = 128;                                         // size of buffer pool
 static constexpr int DEFAULT_DB_IO_SIZE = 16;                                        // starting size of file on disk
 static constexpr int LOG_BUFFER_SIZE = ((BUFFER_POOL_SIZE + 1) * BUSTUB_PAGE_SIZE);  // size of a log buffer in byte