feat: implement extendible htable header and directory page helpers (#613)

Signed-off-by: Yuchen Liang <yuchenl3@andrew.cmu.edu>

Author: yliang412

src/include/storage/page/extendible_htable_directory_page.h

@@ -13,7 +13,7 @@
 /**
  * Directory page format:
  *  --------------------------------------------------------------------------------------
- * | MaxSize (4) | GlobalDepth (4) | LocalDepths (512) | BucketPageIds(2048) | Free(1528)
+ * | MaxDepth (4) | GlobalDepth (4) | LocalDepths (512) | BucketPageIds(2048) | Free(1528)
  *  --------------------------------------------------------------------------------------
  */
 
@@ -39,7 +39,8 @@ static constexpr uint64_t HTABLE_DIRECTORY_PAGE_METADATA_SIZE = sizeof(uint32_t)
  * Extending the directory implementation to span multiple pages would be a meaningful improvement to the
  * implementation.
  */
-static constexpr uint64_t HTABLE_DIRECTORY_ARRAY_SIZE = 512;
+static constexpr uint64_t HTABLE_DIRECTORY_MAX_DEPTH = 9;
+static constexpr uint64_t HTABLE_DIRECTORY_ARRAY_SIZE = 1 << HTABLE_DIRECTORY_MAX_DEPTH;
 
 /**
  * Directory Page for extendible hash table.
@@ -53,17 +54,17 @@ class ExtendibleHTableDirectoryPage {
   /**
    * After creating a new directory page from buffer pool, must call initialize
    * method to set default values
-   * @param max_size Max size of the array in the directory page
+   * @param max_depth Max depth in the directory page
    */
-  void Init(int max_size = HTABLE_DIRECTORY_ARRAY_SIZE);
+  void Init(uint32_t max_depth = HTABLE_DIRECTORY_MAX_DEPTH);
 
   /**
-   * Get the bucket page id that the key is hashed to
+   * Get the bucket index that the key is hashed to
    *
    * @param hash the hash of the key
-   * @return bucket page_id current key is hashed to
+   * @return bucket index current key is hashed to
    */
-  auto HashToBucketPageId(uint32_t hash) -> page_id_t;
+  auto HashToBucketIndex(uint32_t hash) -> uint32_t;
 
   /**
    * Lookup a bucket page using a directory index
@@ -89,31 +90,6 @@ class ExtendibleHTableDirectoryPage {
    **/
   auto GetSplitImageIndex(uint32_t bucket_idx) -> uint32_t;
 
-  /**
-   * GetGlobalDepthMask - returns a mask of global_depth 1's and the rest 0's.
-   *
-   * In Extendible Hashing we map a key to a directory index
-   * using the following hash + mask function.
-   *
-   * DirectoryIndex = Hash(key) & GLOBAL_DEPTH_MASK
-   *
-   * where GLOBAL_DEPTH_MASK is a mask with exactly GLOBAL_DEPTH 1's from LSB
-   * upwards.  For example, global depth 3 corresponds to 0x00000007 in a 32-bit
-   * representation.
-   *
-   * @return mask of global_depth 1's and the rest 0's (with 1's from LSB upwards)
-   */
-  auto GetGlobalDepthMask() -> uint32_t;
-
-  /**
-   * GetLocalDepthMask - same as global depth mask, except it
-   * uses the local depth of the bucket located at bucket_idx
-   *
-   * @param bucket_idx the index to use for looking up local depth
-   * @return mask of local 1's and the rest 0's (with 1's from LSB upwards)
-   */
-  auto GetLocalDepthMask(uint32_t bucket_idx) -> uint32_t;
-
   /**
    * Get the global depth of the hash table directory
    *
@@ -169,16 +145,6 @@ class ExtendibleHTableDirectoryPage {
    */
   void DecrLocalDepth(uint32_t bucket_idx);
 
-  /**
-   * Gets the high bit corresponding to the bucket's local depth.
-   * This is not the same as the bucket index itself.  This method
-   * is helpful for finding the pair, or "split image", of a bucket.
-   *
-   * @param bucket_idx bucket index to lookup
-   * @return the high bit corresponding to the bucket's local depth
-   */
-  auto GetLocalHighBit(uint32_t bucket_idx) -> uint32_t;
-
   /**
    * VerifyIntegrity
    *
@@ -195,7 +161,7 @@ class ExtendibleHTableDirectoryPage {
   void PrintDirectory();
 
  private:
-  uint32_t max_size_;
+  uint32_t max_depth_ __attribute__((__unused__));
   uint32_t global_depth_;
   uint8_t local_depths_[HTABLE_DIRECTORY_ARRAY_SIZE];
   page_id_t bucket_page_ids_[HTABLE_DIRECTORY_ARRAY_SIZE];

src/include/storage/page/extendible_htable_header_page.h

@@ -13,7 +13,7 @@
 /**
  * Header page format:
  *  ---------------------------------------------------
- * | DirectoryPageIds(2048) | MaxSize (4) | Free(2044)
+ * | DirectoryPageIds(2048) | MaxDepth (4) | Free(2044)
  *  ---------------------------------------------------
  */
 
@@ -27,7 +27,8 @@
 namespace bustub {
 
 static constexpr uint64_t HTABLE_HEADER_PAGE_METADATA_SIZE = sizeof(uint32_t);
-static constexpr uint64_t HTABLE_HEADER_ARRAY_SIZE = 512;
+static constexpr uint64_t HTABLE_HEADER_MAX_DEPTH = 9;
+static constexpr uint64_t HTABLE_HEADER_ARRAY_SIZE = 1 << HTABLE_HEADER_MAX_DEPTH;
 
 class ExtendibleHTableHeaderPage {
  public:
@@ -38,20 +39,42 @@ class ExtendibleHTableHeaderPage {
   /**
    * After creating a new header page from buffer pool, must call initialize
    * method to set default values
-   * @param max_size Max size of the array in the header page
+   * @param max_depth Max depth in the header page
    */
-  void Init(int max_size = HTABLE_HEADER_ARRAY_SIZE);
+  void Init(uint32_t max_depth = HTABLE_HEADER_MAX_DEPTH);
 
-  auto HashToDirectoryPageId(uint32_t hash) -> page_id_t;
+  /**
+   * Get the directory index that the key is hashed to
+   *
+   * @param hash the hash of the key
+   * @return directory index the key is hashed to
+   */
+  auto HashToDirectoryIndex(uint32_t hash) const -> uint32_t;
+
+  /**
+   * Get the directory page id at an index
+   *
+   * @param directory_idx index in the directory page id array
+   * @return directory page_id at index
+   */
+  auto GetDirectoryPageId(uint32_t directory_idx) const -> uint32_t;
+
+  /**
+   * @brief Set the directory page id at an index
+   *
+   * @param directory_idx index in the directory page id array
+   * @param directory_page_id page id of the directory
+   */
+  void SetDirectoryPageId(uint32_t directory_idx, page_id_t directory_page_id);
 
   /**
    * Prints the header's occupancy information
    */
-  void PrintHeader();
+  void PrintHeader() const;
 
  private:
   page_id_t directory_page_ids_[HTABLE_HEADER_ARRAY_SIZE];
-  uint32_t max_size_;
+  uint32_t max_depth_;
 };
 
 static_assert(sizeof(page_id_t) == 4);

src/storage/page/extendible_htable_directory_page.cpp

@@ -0,0 +1,79 @@
+//===----------------------------------------------------------------------===//
+//
+//                         BusTub
+//
+// extendible_htable_directory_page.cpp
+//
+// Identification: src/storage/page/extendible_htable_directory_page.cpp
+//
+// Copyright (c) 2015-2023, Carnegie Mellon University Database Group
+//
+//===----------------------------------------------------------------------===//
+
+#include "storage/page/extendible_htable_directory_page.h"
+
+#include <algorithm>
+#include <unordered_map>
+
+#include "common/config.h"
+#include "common/logger.h"
+
+namespace bustub {
+
+void ExtendibleHTableDirectoryPage::Init(uint32_t max_depth) {
+  throw NotImplementedException("ExtendibleHTableDirectoryPage is not implemented");
+}
+
+auto ExtendibleHTableDirectoryPage::HashToBucketIndex(uint32_t hash) -> uint32_t { return 0; }
+
+auto ExtendibleHTableDirectoryPage::GetBucketPageId(uint32_t bucket_idx) -> page_id_t { return INVALID_PAGE_ID; }
+
+void ExtendibleHTableDirectoryPage::SetBucketPageId(uint32_t bucket_idx, page_id_t bucket_page_id) {
+  throw NotImplementedException("ExtendibleHTableDirectoryPage is not implemented");
+}
+
+auto ExtendibleHTableDirectoryPage::GetSplitImageIndex(uint32_t bucket_idx) -> uint32_t { return 0; }
+
+auto ExtendibleHTableDirectoryPage::GetGlobalDepth() -> uint32_t { return 0; }
+
+void ExtendibleHTableDirectoryPage::IncrGlobalDepth() {
+  throw NotImplementedException("ExtendibleHTableDirectoryPage is not implemented");
+}
+
+void ExtendibleHTableDirectoryPage::DecrGlobalDepth() {
+  throw NotImplementedException("ExtendibleHTableDirectoryPage is not implemented");
+}
+
+auto ExtendibleHTableDirectoryPage::CanShrink() -> bool { return false; }
+
+auto ExtendibleHTableDirectoryPage::Size() -> uint32_t { return 0; }
+
+auto ExtendibleHTableDirectoryPage::GetLocalDepth(uint32_t bucket_idx) -> uint32_t { return 0; }
+
+void ExtendibleHTableDirectoryPage::SetLocalDepth(uint32_t bucket_idx, uint8_t local_depth) {
+  throw NotImplementedException("ExtendibleHTableDirectoryPage is not implemented");
+}
+
+void ExtendibleHTableDirectoryPage::IncrLocalDepth(uint32_t bucket_idx) {
+  throw NotImplementedException("ExtendibleHTableDirectoryPage is not implemented");
+}
+
+void ExtendibleHTableDirectoryPage::DecrLocalDepth(uint32_t bucket_idx) {
+  throw NotImplementedException("ExtendibleHTableDirectoryPage is not implemented");
+}
+
+void ExtendibleHTableDirectoryPage::VerifyIntegrity() {
+  // write your own verification function.
+  throw NotImplementedException("ExtendibleHTableDirectoryPage is not implemented");
+}
+
+void ExtendibleHTableDirectoryPage::PrintDirectory() {
+  LOG_DEBUG("======== DIRECTORY (global_depth_: %u) ========", global_depth_);
+  LOG_DEBUG("| bucket_idx | page_id | local_depth |");
+  for (uint32_t idx = 0; idx < static_cast<uint32_t>(0x1 << global_depth_); idx++) {
+    LOG_DEBUG("|    %u    |    %u    |    %u    |", idx, bucket_page_ids_[idx], local_depths_[idx]);
+  }
+  LOG_DEBUG("================ END DIRECTORY ================");
+}
+
+}  // namespace bustub

src/storage/page/extendible_htable_header_page.cpp

@@ -0,0 +1,41 @@
+//===----------------------------------------------------------------------===//
+//
+//                         BusTub
+//
+// extendible_htable_header_page.cpp
+//
+// Identification: src/storage/page/extendible_htable_header_page.cpp
+//
+// Copyright (c) 2015-2023, Carnegie Mellon University Database Group
+//
+//===----------------------------------------------------------------------===//
+
+#include "storage/page/extendible_htable_header_page.h"
+
+#include "common/exception.h"
+#include "common/logger.h"
+
+namespace bustub {
+
+void ExtendibleHTableHeaderPage::Init(uint32_t max_depth) {
+  throw NotImplementedException("ExtendibleHTableHeaderPage is not implemented");
+}
+
+auto ExtendibleHTableHeaderPage::HashToDirectoryIndex(uint32_t hash) const -> uint32_t { return 0; }
+
+auto ExtendibleHTableHeaderPage::GetDirectoryPageId(uint32_t directory_idx) const -> uint32_t { return 0; }
+
+void ExtendibleHTableHeaderPage::SetDirectoryPageId(uint32_t directory_idx, page_id_t directory_page_id) {
+  throw NotImplementedException("ExtendibleHTableHeaderPage is not implemented");
+}
+
+void ExtendibleHTableHeaderPage::PrintHeader() const {
+  LOG_DEBUG("======== HEADER (max_depth_: %u) ========", max_depth_);
+  LOG_DEBUG("| directory_idx | page_id |");
+  for (uint32_t idx = 0; idx < static_cast<uint32_t>(1 << max_depth_); idx++) {
+    LOG_DEBUG("|    %u    |    %u    |", idx, directory_page_ids_[idx]);
+  }
+  LOG_DEBUG("======== END HEADER ========");
+}
+
+}  // namespace bustub