From 97f01ca9407bebc24fc4ce2440b47af08ecac596 Mon Sep 17 00:00:00 2001
From: zhouzc <522022330108@smail.nju.edu.cn>
Date: Thu, 5 Oct 2023 15:44:04 +0800
Subject: [PATCH] uheap insert commentary

---
 .../storage/access/ustore/knl_uheap.cpp       | 30 +++++++++++++++----
 .../storage/access/ustore/knl_upage.cpp       |  7 +++++
 2 files changed, 32 insertions(+), 5 deletions(-)

diff --git a/src/gausskernel/storage/access/ustore/knl_uheap.cpp b/src/gausskernel/storage/access/ustore/knl_uheap.cpp
index 955face7b..df463a3ad 100644
--- a/src/gausskernel/storage/access/ustore/knl_uheap.cpp
+++ b/src/gausskernel/storage/access/ustore/knl_uheap.cpp
@@ -489,6 +489,19 @@ static ShortTransactionId UHeapTupleSetModifiedXid(Relation relation,
     return tupleXid;
 }
 
+/*
+ * UHeapInsert - insert a heap tuple in the table
+ * 
+ * Params:
+ * @param[IN] rel: the uheap relation
+ * @param[IN] utuple: the uheap tuple that will be inserted
+ * @param[IN] cid: CID of the inserting transaction
+ * @param[IN] bistate: state for bulk inserts. 
+ * @param[IN] isToast: is toast or not.
+ * 
+ * For most cases, the returned value is InvalidOid, for we successfully insert a tuple 
+ * into the relation table.
+ */
 Oid UHeapInsert(RelationData *rel, UHeapTupleData *utuple, CommandId cid, BulkInsertState bistate, bool isToast)
 {
     Page page;
@@ -511,9 +524,13 @@ Oid UHeapInsert(RelationData *rel, UHeapTupleData *utuple, CommandId cid, BulkIn
         ereport(ERROR, (errcode(ERRCODE_INVALID_PARAMETER_VALUE), errmsg("The insert tuple is NULL")));
     }
     Assert(utuple->tupTableType == UHEAP_TUPLE);
-    TransactionId fxid = GetTopTransactionId();
+    TransactionId fxid = GetTopTransactionId();             // get the xid of the main transaction
 
-    /* Prepare the tuple for insertion */
+    /* 
+     * Prepare the tuple for insertion
+     * Here we should notice that "tuple" and "utuple" point to the same place in memory.
+     * We fill in some basic information based on the rel into the tuple.
+     */
     tuple = UHeapPrepareInsert(rel, utuple, 0);
 
     /* Prepare Undo record before buffer lock since undo record length is fixed */
@@ -603,6 +620,7 @@ reacquire_buffer:
     /* Put utuple into buffer page */
     RelationPutUTuple(rel, buffer, tuple);
 
+    // update potential free space of the page
     UHeapRecordPotentialFreeSpace(buffer, -1 * SHORTALIGN(tuple->disk_tuple_size));
 
     /* Update the UndoRecord now that we know where the tuple is located on the Page */
@@ -747,16 +765,18 @@ TransactionId UHeapFetchInsertXid(UHeapTuple uhtup, Buffer buffer)
     return result;
 }
 
-
+/* Put utuple into a page */
 void RelationPutUTuple(Relation relation, Buffer buffer, UHeapTupleData *tuple)
 {
     OffsetNumber offNum = InvalidOffsetNumber;
     UHeapBufferPage bufpage = {buffer, NULL};
 
+    // UPageAddItem: put the tuple into the buffer page
     offNum =
         UPageAddItem(relation, &bufpage, (Item)tuple->disk_tuple, tuple->disk_tuple_size, InvalidOffsetNumber, false);
     if (offNum == InvalidOffsetNumber)
         elog(PANIC, "failed to add tuple to page");
+    // set item pointer of the tuple->ctid
     ItemPointerSet(&(tuple->ctid), BufferGetBlockNumber(buffer), offNum);
 }
 
@@ -767,7 +787,7 @@ UHeapTuple UHeapPrepareInsert(Relation rel, UHeapTupleData *tuple, int options)
     tuple->disk_tuple->flag &= ~UHEAP_VIS_STATUS_MASK;
     tuple->disk_tuple->td_id = UHEAPTUP_SLOT_FROZEN;
     tuple->disk_tuple->locker_td_id = UHEAPTUP_SLOT_FROZEN;
-    tuple->table_oid = RelationGetRelid(rel);
+    tuple->table_oid = RelationGetRelid(rel);       // Here, get the relid of the relation
     tuple->t_bucketId = InvalidBktId;
 
     if (rel->rd_rel->relkind != RELKIND_RELATION) {
@@ -1688,7 +1708,7 @@ bool TableFetchAndStore(Relation scanRelation, Snapshot snapshot, Tuple tuple, B
  * @param[IN] allowDeleteSelf: use in UHeapTupleSatisfiesUpdate for checking.
  * 
  * For most cases, the returned value is TM_Ok, for we successfully delete a tuple 
- * form the relation. The old tuple will be placed into te undo zone.
+ * from the relation. The old tuple will be placed into te undo zone.
  */
 TM_Result UHeapDelete(Relation relation, ItemPointer tid, CommandId cid, Snapshot crosscheck, Snapshot snapshot,
     bool wait, TupleTableSlot** oldslot, TM_FailureData *tmfd, bool changingPart, bool allowDeleteSelf)
diff --git a/src/gausskernel/storage/access/ustore/knl_upage.cpp b/src/gausskernel/storage/access/ustore/knl_upage.cpp
index 56f723be7..6cc3ab6b3 100644
--- a/src/gausskernel/storage/access/ustore/knl_upage.cpp
+++ b/src/gausskernel/storage/access/ustore/knl_upage.cpp
@@ -187,6 +187,11 @@ static void FindNextFreeSlot(const UHeapBufferPage *bufpage, Page input_page, Of
     }
 }
 
+/*
+ * Do the actual insert of the item into the page
+ * Put the item data on the back or the page and update the page's lower 
+ * and upper pointers.
+ */
 static bool CalculateLowerUpperPointers(Page page, OffsetNumber offsetNumber, Item item, Size size, bool needshuffle)
 {
     int             lower;
@@ -290,6 +295,7 @@ OffsetNumber UPageAddItem(Relation rel, UHeapBufferPage *bufpage, Item item, Siz
             return InvalidOffsetNumber;
         }
     } else {
+        // Find free slot in the page
         FindNextFreeSlot(bufpage, input_page, &offsetNumber);
     }
 
@@ -307,6 +313,7 @@ OffsetNumber UPageAddItem(Relation rel, UHeapBufferPage *bufpage, Item item, Siz
         return InvalidOffsetNumber;
     }
 
+    // do the actual insert of the item
     if (!CalculateLowerUpperPointers(page, offsetNumber, item, size, needshuffle)) {
         return InvalidOffsetNumber;
     }