feat: define new extendible hash table pages specification (#611)

Signed-off-by: Yuchen Liang <[email protected]>

Author: yliang412

src/include/storage/page/extendible_htable_bucket_page.h

@@ -0,0 +1,120 @@
+//===----------------------------------------------------------------------===//
+//
+//                         BusTub
+//
+// extendible_htable_bucket_page.h
+//
+// Identification: src/include/storage/page/extendible_htable_bucket_page.h
+//
+// Copyright (c) 2015-2023, Carnegie Mellon University Database Group
+//
+//===----------------------------------------------------------------------===//
+
+/**
+ * Bucket page format:
+ *  ----------------------------------------------------------------------------
+ * | METADATA | KEY(1) + VALUE(1) | KEY(2) + VALUE(2) | ... | KEY(n) + VALUE(n)
+ *  ----------------------------------------------------------------------------
+ *
+ * Metadata format (size in byte, 8 bytes in total):
+ *  --------------------------------
+ * | CurrentSize (4) | MaxSize (4)
+ *  --------------------------------
+ */
+#pragma once
+
+#include <utility>
+#include <vector>
+
+#include "common/config.h"
+#include "common/macros.h"
+#include "storage/index/int_comparator.h"
+#include "storage/page/b_plus_tree_page.h"
+#include "storage/page/hash_table_page_defs.h"
+
+namespace bustub {
+
+static constexpr uint64_t HTABLE_BUCKET_PAGE_METADATA_SIZE = sizeof(uint32_t) * 2;
+
+constexpr auto HTableBucketArraySize(uint64_t mapping_type_size) -> uint64_t {
+  return (BUSTUB_PAGE_SIZE - HTABLE_BUCKET_PAGE_METADATA_SIZE) / mapping_type_size;
+};
+
+/**
+ * Bucket page for extendible hash table.
+ */
+template <typename KeyType, typename ValueType, typename KeyComparator>
+class ExtendibleHTableBucketPage {
+ public:
+  // Delete all constructor / destructor to ensure memory safety
+  ExtendibleHTableBucketPage() = delete;
+  DISALLOW_COPY_AND_MOVE(ExtendibleHTableBucketPage);
+
+  /**
+   * After creating a new bucket page from buffer pool, must call initialize
+   * method to set default values
+   * @param max_size Max size of the bucket array
+   */
+  void Init(int max_size = HTableBucketArraySize(sizeof(MappingType)));
+
+  auto Lookup(const KeyType &key, ValueType &value, const KeyComparator &cmp) const -> bool;
+
+  /**
+   * Attempts to insert a key and value in the bucket.
+   *
+   * @param key key to insert
+   * @param value value to insert
+   * @return true if inserted, false if duplicate KV pair or bucket is full
+   */
+  auto Insert(KeyType key, ValueType value, const KeyComparator &cmp) -> bool;
+
+  /**
+   * Removes a key and value.
+   *
+   * @return true if removed, false if not found
+   */
+  auto Remove(KeyType key, ValueType value, const KeyComparator &cmp) -> bool;
+
+  /**
+   * Gets the key at an index in the bucket.
+   *
+   * @param bucket_idx the index in the bucket to get the key at
+   * @return key at index bucket_idx of the bucket
+   */
+  auto KeyAt(uint32_t bucket_idx) const -> KeyType;
+
+  /**
+   * Gets the value at an index in the bucket.
+   *
+   * @param bucket_idx the index in the bucket to get the value at
+   * @return value at index bucket_idx of the bucket
+   */
+  auto ValueAt(uint32_t bucket_idx) const -> ValueType;
+
+  /**
+   * Remove the KV pair at bucket_idx
+   */
+  void RemoveAt(uint32_t bucket_idx);
+
+  /**
+   * @return whether the bucket is full
+   */
+  auto IsFull() -> bool;
+
+  /**
+   * @return whether the bucket is empty
+   */
+  auto IsEmpty() -> bool;
+
+  /**
+   * Prints the bucket's occupancy information
+   */
+  void PrintBucket();
+
+ private:
+  uint32_t size_;
+  uint32_t max_size_;
+  MappingType array_[HTableBucketArraySize(sizeof(MappingType))];
+};
+
+}  // namespace bustub

src/include/storage/page/extendible_htable_directory_page.h

@@ -0,0 +1,212 @@
+//===----------------------------------------------------------------------===//
+//
+//                         BusTub
+//
+// extendible_htable_directory_page.h
+//
+// Identification: src/include/storage/page/extendible_htable_directory_page.h
+//
+// Copyright (c) 2015-2023, Carnegie Mellon University Database Group
+//
+//===----------------------------------------------------------------------===//
+
+/**
+ * Directory page format:
+ *  --------------------------------------------------------------------------------------
+ * | MaxSize (4) | GlobalDepth (4) | LocalDepths (512) | BucketPageIds(2048) | Free(1528)
+ *  --------------------------------------------------------------------------------------
+ */
+
+#pragma once
+
+#include <cassert>
+#include <climits>
+#include <cstdlib>
+#include <string>
+
+#include "common/config.h"
+#include "storage/index/generic_key.h"
+#include "storage/page/hash_table_page_defs.h"
+
+namespace bustub {
+
+static constexpr uint64_t HTABLE_DIRECTORY_PAGE_METADATA_SIZE = sizeof(uint32_t) * 2;
+
+/**
+ * HTABLE_DIRECTORY_ARRAY_SIZE is the number of page_ids that can fit in the directory page of an extendible hash index.
+ * This is 512 because the directory array must grow in powers of 2, and 1024 page_ids leaves zero room for
+ * storage of the other member variables: page_id_, lsn_, global_depth_, and the array local_depths_.
+ * 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;
+
+/**
+ * Directory Page for extendible hash table.
+ */
+class ExtendibleHTableDirectoryPage {
+ public:
+  // Delete all constructor / destructor to ensure memory safety
+  ExtendibleHTableDirectoryPage() = delete;
+  DISALLOW_COPY_AND_MOVE(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
+   */
+  void Init(int max_size = HTABLE_DIRECTORY_ARRAY_SIZE);
+
+  /**
+   * Get the bucket page id that the key is hashed to
+   *
+   * @param hash the hash of the key
+   * @return bucket page_id current key is hashed to
+   */
+  auto HashToBucketPageId(uint32_t hash) -> page_id_t;
+
+  /**
+   * Lookup a bucket page using a directory index
+   *
+   * @param bucket_idx the index in the directory to lookup
+   * @return bucket page_id corresponding to bucket_idx
+   */
+  auto GetBucketPageId(uint32_t bucket_idx) -> page_id_t;
+
+  /**
+   * Updates the directory index using a bucket index and page_id
+   *
+   * @param bucket_idx directory index at which to insert page_id
+   * @param bucket_page_id page_id to insert
+   */
+  void SetBucketPageId(uint32_t bucket_idx, page_id_t bucket_page_id);
+
+  /**
+   * Gets the split image of an index
+   *
+   * @param bucket_idx the directory index for which to find the split image
+   * @return the directory index of the split image
+   **/
+  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
+   *
+   * @return the global depth of the directory
+   */
+  auto GetGlobalDepth() -> uint32_t;
+
+  /**
+   * Increment the global depth of the directory
+   */
+  void IncrGlobalDepth();
+
+  /**
+   * Decrement the global depth of the directory
+   */
+  void DecrGlobalDepth();
+
+  /**
+   * @return true if the directory can be shrunk
+   */
+  auto CanShrink() -> bool;
+
+  /**
+   * @return the current directory size
+   */
+  auto Size() -> uint32_t;
+
+  /**
+   * Gets the local depth of the bucket at bucket_idx
+   *
+   * @param bucket_idx the bucket index to lookup
+   * @return the local depth of the bucket at bucket_idx
+   */
+  auto GetLocalDepth(uint32_t bucket_idx) -> uint32_t;
+
+  /**
+   * Set the local depth of the bucket at bucket_idx to local_depth
+   *
+   * @param bucket_idx bucket index to update
+   * @param local_depth new local depth
+   */
+  void SetLocalDepth(uint32_t bucket_idx, uint8_t local_depth);
+
+  /**
+   * Increment the local depth of the bucket at bucket_idx
+   * @param bucket_idx bucket index to increment
+   */
+  void IncrLocalDepth(uint32_t bucket_idx);
+
+  /**
+   * Decrement the local depth of the bucket at bucket_idx
+   * @param bucket_idx bucket index to decrement
+   */
+  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
+   *
+   * Verify the following invariants:
+   * (1) All LD <= GD.
+   * (2) Each bucket has precisely 2^(GD - LD) pointers pointing to it.
+   * (3) The LD is the same at each index with the same bucket_page_id
+   */
+  void VerifyIntegrity();
+
+  /**
+   * Prints the current directory
+   */
+  void PrintDirectory();
+
+ private:
+  uint32_t max_size_;
+  uint32_t global_depth_;
+  uint8_t local_depths_[HTABLE_DIRECTORY_ARRAY_SIZE];
+  page_id_t bucket_page_ids_[HTABLE_DIRECTORY_ARRAY_SIZE];
+};
+
+static_assert(sizeof(page_id_t) == 4);
+
+static_assert(sizeof(ExtendibleHTableDirectoryPage) == HTABLE_DIRECTORY_PAGE_METADATA_SIZE +
+                                                           HTABLE_DIRECTORY_ARRAY_SIZE +
+                                                           sizeof(page_id_t) * HTABLE_DIRECTORY_ARRAY_SIZE);
+
+static_assert(sizeof(ExtendibleHTableDirectoryPage) <= BUSTUB_PAGE_SIZE);
+
+}  // namespace bustub

src/include/storage/page/extendible_htable_header_page.h

@@ -0,0 +1,64 @@
+//===----------------------------------------------------------------------===//
+//
+//                         BusTub
+//
+// extendible_htable_header_page.h
+//
+// Identification: src/include/storage/page/extendible_htable_header_page.h
+//
+// Copyright (c) 2015-2023, Carnegie Mellon University Database Group
+//
+//===----------------------------------------------------------------------===//
+
+/**
+ * Header page format:
+ *  ---------------------------------------------------
+ * | DirectoryPageIds(2048) | MaxSize (4) | Free(2044)
+ *  ---------------------------------------------------
+ */
+
+#pragma once
+
+#include <cstdlib>
+#include "common/config.h"
+#include "common/macros.h"
+#include "storage/page/hash_table_page_defs.h"
+
+namespace bustub {
+
+static constexpr uint64_t HTABLE_HEADER_PAGE_METADATA_SIZE = sizeof(uint32_t);
+static constexpr uint64_t HTABLE_HEADER_ARRAY_SIZE = 512;
+
+class ExtendibleHTableHeaderPage {
+ public:
+  // Delete all constructor / destructor to ensure memory safety
+  ExtendibleHTableHeaderPage() = delete;
+  DISALLOW_COPY_AND_MOVE(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
+   */
+  void Init(int max_size = HTABLE_HEADER_ARRAY_SIZE);
+
+  auto HashToDirectoryPageId(uint32_t hash) -> page_id_t;
+
+  /**
+   * Prints the header's occupancy information
+   */
+  void PrintHeader();
+
+ private:
+  page_id_t directory_page_ids_[HTABLE_HEADER_ARRAY_SIZE];
+  uint32_t max_size_;
+};
+
+static_assert(sizeof(page_id_t) == 4);
+
+static_assert(sizeof(ExtendibleHTableHeaderPage) ==
+              sizeof(page_id_t) * HTABLE_HEADER_ARRAY_SIZE + HTABLE_HEADER_PAGE_METADATA_SIZE);
+
+static_assert(sizeof(ExtendibleHTableHeaderPage) <= BUSTUB_PAGE_SIZE);
+
+}  // namespace bustub