Added documentation

Author: poojanilangekar

src/catalog/catalog.cpp

@@ -353,7 +353,8 @@ ResultType Catalog::CreateTable(const std::string &database_name,
   bool adapt_table = false;
   auto table = storage::TableFactory::GetDataTable(
       database_object->GetDatabaseOid(), table_oid, schema.release(),
-      table_name, tuples_per_tilegroup, own_schema, adapt_table, is_catalog, layout_type);
+      table_name, tuples_per_tilegroup, own_schema, adapt_table, is_catalog,
+      layout_type);
   database->AddTable(table, is_catalog);
   // put data table object into rw_object_set
   txn->RecordCreate(database_object->GetDatabaseOid(), table_oid, INVALID_OID);

src/catalog/layout_catalog.cpp

@@ -22,13 +22,9 @@
 namespace peloton {
 namespace catalog {
 
-LayoutCatalog *LayoutCatalog::GetInstance(storage::Database *pg_catalog,
-                                          type::AbstractPool *pool,
-                                          concurrency::TransactionContext *txn) {
-  static LayoutCatalog layout_catalog{pg_catalog, pool, txn};
-  return &layout_catalog;
-}
-
+/** @brief   Constructor invoked by the SystemsCatalog constructor.
+ *  @param   pg_catalog  The database to which this pg_layout belongs.
+ */
 LayoutCatalog::LayoutCatalog(
         storage::Database *pg_catalog,
         UNUSED_ATTRIBUTE type::AbstractPool *pool,
@@ -42,9 +38,12 @@ LayoutCatalog::LayoutCatalog(
   AddIndex({ColumnId::TABLE_OID}, LAYOUT_CATALOG_SKEY0_OID,
            LAYOUT_CATALOG_NAME "_skey0", IndexConstraintType::DEFAULT);
 }
-
+/** @brief   Destructor. Do nothing. Layouts will be dropped by DropTable. */
 LayoutCatalog::~LayoutCatalog() {}
 
+/** @brief   Initilailizes the schema for the pg_layout table.
+ *  @return  unique_ptr of the schema for pg_layout.
+ */
 std::unique_ptr<catalog::Schema> LayoutCatalog::InitializeSchema() {
   const std::string primary_key_constraint_name = "primary_key";
   const std::string not_null_constraint_name = "not_null";
@@ -83,6 +82,13 @@ std::unique_ptr<catalog::Schema> LayoutCatalog::InitializeSchema() {
   return column_catalog_schema;
 }
 
+/** @brief      Insert a layout into the pg_layout table.
+ *  @param      table_oid  oid of the table to which the new layout belongs.
+ *  @param      layout  layout to be added to the pg_layout table.
+ *  @param      pool to allocate memory for the column_map column.
+ *  @param      txn TransactionContext for adding the layout.
+ *  @return     true on success.
+ */
 bool LayoutCatalog::InsertLayout(oid_t table_oid,
                                  std::shared_ptr<const storage::Layout> layout,
                                  type::AbstractPool *pool,
@@ -106,26 +112,37 @@ bool LayoutCatalog::InsertLayout(oid_t table_oid,
   return InsertTuple(std::move(tuple), txn);
 }
 
-bool LayoutCatalog::DeleteLayout(oid_t table_oid, oid_t layout_id,
+/** @brief      Delete a layout from the pg_layout table.
+ *  @param      table_oid  oid of the table to which the old layout belongs.
+ *  @param      layout_oid  oid of the layout to be deleted.
+ *  @param      txn TransactionContext for deleting the layout.
+ *  @return     true on success.
+ */
+bool LayoutCatalog::DeleteLayout(oid_t table_oid, oid_t layout_oid,
                                  concurrency::TransactionContext *txn) {
   oid_t index_offset =
           IndexId::PRIMARY_KEY;  // Index of table_oid & layout_oid
 
   std::vector<type::Value> values;
   values.push_back(type::ValueFactory::GetIntegerValue(table_oid).Copy());
-  values.push_back(type::ValueFactory::GetIntegerValue(layout_id).Copy());
+  values.push_back(type::ValueFactory::GetIntegerValue(layout_oid).Copy());
 
   auto pg_table = Catalog::GetInstance()
           ->GetSystemCatalogs(database_oid)
           ->GetTableCatalog();
 
   // delete column from cache
   auto table_object = pg_table->GetTableObject(table_oid, txn);
-  table_object->EvictLayout(layout_id);
+  table_object->EvictLayout(layout_oid);
 
   return DeleteWithIndexScan(index_offset, values, txn);
 }
 
+/** @brief      Delete all layouts correponding to a table from the pg_layout.
+ *  @param      table_oid  oid of the table to delete all layouts.
+ *  @param      txn TransactionContext for deleting the layouts.
+ *  @return     true on success.
+ */
 bool LayoutCatalog::DeleteLayouts(oid_t table_oid,
                                   concurrency::TransactionContext *txn) {
   oid_t index_offset = IndexId::SKEY_TABLE_OID;  // Index of table_oid
@@ -142,6 +159,11 @@ bool LayoutCatalog::DeleteLayouts(oid_t table_oid,
   return DeleteWithIndexScan(index_offset, values, txn);
 }
 
+/** @brief      Get all layouts correponding to a table from the pg_layout.
+ *  @param      table_oid  oid of the table to fetch all layouts.
+ *  @param      txn TransactionContext for getting the layouts.
+ *  @return     unordered_map containing a layout_oid -> layout mapping.
+ */
 const std::unordered_map<oid_t, std::shared_ptr<const storage::Layout>>
 LayoutCatalog::GetLayouts(oid_t table_oid,
                           concurrency::TransactionContext *txn) {
@@ -165,37 +187,35 @@ LayoutCatalog::GetLayouts(oid_t table_oid,
   auto result_tiles =
           GetResultWithIndexScan(column_ids, index_offset, values, txn);
 
-  // result_tiles should contain only 1 LogicalTile per table
-  auto result_size = (*result_tiles).size();
-  PELOTON_ASSERT(result_size <= 1);
-  if (result_size == 0) {
-    LOG_DEBUG("No entry for table %u in pg_layout", table_oid);
-    return table_object->GetLayouts();
-  }
-
-  // Get the LogicalTile
-  auto tile = (*result_tiles)[0].get();
-  auto tuple_count = tile->GetTupleCount();
-  for (oid_t tuple_id = 0; tuple_id < tuple_count; tuple_id++) {
-    oid_t layout_oid =
-            tile->GetValue(tuple_id, LayoutCatalog::ColumnId::LAYOUT_OID)
-                    .GetAs<oid_t>();
-    oid_t num_columns =
-            tile->GetValue(tuple_id, LayoutCatalog::ColumnId::NUM_COLUMNS)
-                    .GetAs<oid_t>();
-    std::string column_map_str =
-            tile->GetValue(tuple_id, LayoutCatalog::ColumnId::COLUMN_MAP)
-                    .ToString();
-    auto column_map = storage::Layout::DeserializeColumnMap(num_columns,
-                                                            column_map_str);
-    auto layout_object =
-            std::make_shared<const storage::Layout>(column_map, layout_oid);
-    table_object->InsertLayout(layout_object);
+  for (auto &tile : (*result_tiles)) { // Iterate through the result_tiles
+    for (auto tuple_id : *tile) {
+      oid_t layout_oid =
+              tile->GetValue(tuple_id, LayoutCatalog::ColumnId::LAYOUT_OID)
+                      .GetAs<oid_t>();
+      oid_t num_columns =
+              tile->GetValue(tuple_id, LayoutCatalog::ColumnId::NUM_COLUMNS)
+                      .GetAs<oid_t>();
+      std::string column_map_str =
+              tile->GetValue(tuple_id, LayoutCatalog::ColumnId::COLUMN_MAP)
+                      .ToString();
+      auto column_map = storage::Layout::DeserializeColumnMap(num_columns,
+                                                              column_map_str);
+      auto layout_object =
+              std::make_shared<const storage::Layout>(column_map, layout_oid);
+      table_object->InsertLayout(layout_object);
+    }
   }
 
   return table_object->GetLayouts();
 }
 
+/** @brief      Get the layout by layout_oid from the pg_layout.
+ *  @param      table_oid  oid of the table to fetch the layout.
+ *  @param      layout_oid  oid of the layout being queried.
+ *  @param      txn TransactionContext for getting the layout.
+ *  @return     shared_ptr corresponding to the layout_oid if found.
+ *              nullptr otherwise.
+ */
 std::shared_ptr<const storage::Layout>
 LayoutCatalog::GetLayoutWithOid(oid_t table_oid, oid_t layout_oid,
                  concurrency::TransactionContext *txn) {

src/catalog/table_catalog.cpp

@@ -331,9 +331,9 @@ TableCatalog::TableCatalog(
            IndexConstraintType::DEFAULT);
 }
 
-/* @brief   Insert layout object into the cache.
- * @param   layout  Layout object to be inserted
- * @return  false if layout already exists in cache
+/** @brief   Insert layout object into the cache.
+ *  @param   layout  Layout object to be inserted
+ *  @return  false if layout already exists in cache
  */
 bool TableCatalogObject::InsertLayout(std::shared_ptr<const storage::Layout> layout) {
 
@@ -354,33 +354,34 @@ bool TableCatalogObject::InsertLayout(std::shared_ptr<const storage::Layout> lay
   return true;
 }
 
-/*
- * @brief   evict all layout objects from cache
- */
+/** @brief   evict all layout objects from cache. */
 void TableCatalogObject::EvictAllLayouts() {
   layout_objects_.clear();
   valid_layout_objects_ = false;
 }
 
-/* @brief   Get all layout objects of this table.
- *          Add it to the cache if necessary.
- * @param   cached_only If set to true, don't fetch the layout objects.
- * @return  Map from layout_oid to cached layout object.
+/** @brief   Get all layout objects of this table.
+ *           Add it to the cache if necessary.
+ *  @param   cached_only If set to true, don't fetch the layout objects.
+ *  @return  Map from layout_oid to cached layout object.
  */
 std::unordered_map<oid_t, std::shared_ptr<const storage::Layout>>
 TableCatalogObject::GetLayouts(bool cached_only) {
   if (!valid_layout_objects_ && !cached_only) {
-    // get column catalog objects from pg_column
-    LayoutCatalog::GetInstance()->GetLayouts(table_oid, txn);
+    // get layout catalog objects from pg_layout
+    auto pg_layout = Catalog::GetInstance()
+            ->GetSystemCatalogs(database_oid)
+            ->GetLayoutCatalog();
+    pg_layout->GetLayouts(table_oid, txn);
     valid_column_objects = true;
   }
   return layout_objects_;
 }
 
-/* @brief   get the layout object of the given layout_id.
- * @param   layout_id The id of the layout to be fetched.
- * @param   cached_only If set to true, don't fetch the layout objects.
- * @return  Layout object of corresponding to the layout_id if present.
+/** @brief   Get the layout object of the given layout_id.
+ *  @param   layout_id The id of the layout to be fetched.
+ *  @param   cached_only If set to true, don't fetch the layout objects.
+ *  @return  Layout object of corresponding to the layout_id if present.
  */
 std::shared_ptr<const storage::Layout>
 TableCatalogObject::GetLayout(oid_t layout_id, bool cached_entry) {
@@ -393,9 +394,9 @@ TableCatalogObject::GetLayout(oid_t layout_id, bool cached_entry) {
   return nullptr;
 }
 
-/* @brief   Evict layout from the cache.
- * @param   layout_id Id of the layout to be deleted.
- * @return  true if layout_id is found and evicted; false if not found.
+/** @brief   Evict layout from the cache.
+ *  @param   layout_id Id of the layout to be deleted.
+ *  @return  true if layout_id is found and evicted; false if not found.
  */
 bool TableCatalogObject::EvictLayout(oid_t layout_id) {
   if (!valid_layout_objects_) return false;

src/include/catalog/layout_catalog.h

@@ -58,7 +58,7 @@ class LayoutCatalog : public AbstractCatalog {
                     type::AbstractPool *pool,
                     concurrency::TransactionContext *txn);
 
-  bool DeleteLayout(oid_t table_oid, oid_t layout_id,
+  bool DeleteLayout(oid_t table_oid, oid_t layout_oid,
                     concurrency::TransactionContext *txn);
 
   bool DeleteLayouts(oid_t table_oid, concurrency::TransactionContext *txn);

src/include/storage/layout.h

@@ -17,8 +17,11 @@
 #include "common/internal_types.h"
 #include "common/printable.h"
 
+//@{
+/** @brief  Pre-defined OIDs for ROW and COLUMN store.  */
 #define ROW_STORE_OID 0
 #define COLUMN_STORE_OID 1
+//@}
 
 namespace peloton {
 
@@ -28,64 +31,105 @@ class Schema;
 
 namespace storage {
 
+/**
+ * @brief   Class to store the physical layout of a TileGroup.
+ */
 class Layout : public Printable {
  public:
 
+  /**
+   * @brief   Constructor for predefined layout types.
+   * @param   num_columns Number of columns in the layouts.
+   * @param   layout_type Has to be LayoutType::ROW or LayoutType::COLUMN.
+   */
   Layout (const oid_t num_columns, LayoutType layout_type = LayoutType::ROW);
 
+  /**
+   * @brief   Constructor for arbitrary column_maps.
+   *          If the column_map is of type LayoutType::HYBRID,
+   *          the layout_oid_ is set to INVALID_OID. For all other
+   *          layouts, the pre-defined OIDs are used. Should be used
+   *          only for testing & TempTables, the layout isn't persistent.
+   * @param   column_map Column map of the layout to be constructed
+   *
+   */
   Layout(const column_map_type& column_map);
 
-  Layout(const column_map_type& column_map, oid_t layout_id);
+  /**
+   * @brief   Constructor for arbitrary column_maps.
+   * @param   column_map Column map of the layout to be constructed.
+   * @param   layout_oid Per-table unique OID. Generted by DataTable.
+   */
+  Layout(const column_map_type& column_map, oid_t layout_oid);
 
-  // Check whether the Layout is a RowStore.
+  /** @brief  Check whether this layout is a row store. */
   inline bool IsRowStore() const { return (layout_type_ == LayoutType::ROW); }
 
-  // Check whether the Layout is ColumnStore.
+  /** @brief  Check whether this layout is a column store. */
   inline bool IsColumnStore() const { return (layout_type_ == LayoutType::COLUMN); }
 
+  /** @brief  Return the layout_oid_ of this object. */
   oid_t  GetOid() const { return layout_oid_; }
 
-  // Sets the tile id and column id w.r.t that tile corresponding to
-  // the specified tile group column id.
+  /** @brief  Sets the tile id and column id w.r.t. of the tile corresponding
+   *          to the specified tile group column id.
+   */
   void LocateTileAndColumn(oid_t column_offset, oid_t &tile_offset,
                            oid_t &tile_column_offset) const;
 
+  /** @brief    Returns the layout difference w.r.t. the other Layout.
+   *  @double   The delta between the layouts. Used by LayoutTuner class.
+   */
   double GetLayoutDifference(const storage::Layout &other) const;
 
+  /** @brief  Returns the tile_id of the given column_id. */
   oid_t GetTileIdFromColumnId(oid_t column_id) const;
 
-  oid_t GetTileColumnId(oid_t column_id) const;
+  /** @brief  Returns the column offset of the column_id. */
+  oid_t GetTileColumnOffset(oid_t column_id) const;
 
+  /** @brief  Returns the number of columns in the layout. */
   oid_t GetColumnCount() const { return num_columns_;}
 
+  /** @brief  Constructs the schema for the given layout.  Thid function
+   *          is used only in TempTables and LogicalTiles.
+   */
   std::vector<catalog::Schema> GetLayoutSchemas(catalog::Schema* const schema) const;
 
+  /** @brief  Returns the layout statistics used by the LayoutTuner. */
   std::map<oid_t, oid_t> GetLayoutStats() const;
 
+  /** @brief  Serialzies the column_map to be added to pg_layout. */
   std::string SerializeColumnMap() const;
 
+  /** @brief  Deserializes the string that has been read from pg_layout. */
   static column_map_type DeserializeColumnMap(oid_t num_columns,
                                               std::string column_map_str);
 
+  /** @brief  Returns a string containing the column_map of this layout. */
   std::string GetColumnMapInfo() const;
 
-  // Get a string representation for debugging
+  /** @brief  Returns a string representation for debugging function. */
   const std::string GetInfo() const;
 
+  //@{
+  /** @brief  Operators for checking equality of two layouts. */
   friend bool operator==(const Layout& lhs, const Layout& rhs);
   friend bool operator!=(const Layout& lhs, const Layout& rhs);
+  //@}
 
  private:
 
-  // Layout Id of the tile
+  /** @brief  Layout Oid of the layout object. */
   oid_t layout_oid_;
 
-  // Number of columns in the layout 
+  /** @brief  Number of columns in the layout. */
   oid_t num_columns_; 
 
-  // Layout of the columns.
+  /** @brief  column_map of the layout. */
   column_map_type column_layout_;
 
+  /** @brief  Layout type is always (ROW, COLUMN or HYBRID). */
   LayoutType layout_type_;
 
 };

src/include/storage/tile_group.h

@@ -161,6 +161,7 @@ class TileGroup : public Printable {
   // Sync the contents
   void Sync();
 
+  // Get the layout of the TileGroup. Used to locate columns. 
   const storage::Layout& GetLayout() const { return *tile_group_layout_; }
 
  protected:

src/storage/layout.cpp

@@ -146,7 +146,7 @@ oid_t Layout::GetTileIdFromColumnId(oid_t column_id) const {
   return tile_offset;
 }
 
-oid_t Layout::GetTileColumnId(oid_t column_id) const {
+oid_t Layout::GetTileColumnOffset(oid_t column_id) const {
   oid_t tile_column_id, tile_offset;
   LocateTileAndColumn(column_id, tile_offset, tile_column_id);
   return tile_column_id;