C

Author: interma

src/backend/access/heap/heapam.c

@@ -2759,6 +2759,67 @@ xmax_infomask_changed(uint16 new_infomask, uint16 old_infomask)
 	return false;
 }
 
+/**
+关于crosscheck参数：
+经常用Estate结构中的来填入
+	Snapshot	es_crosscheck_snapshot; // crosscheck time qual for RI
+注释中的 RI 是 Referential Integrity（引用完整性）的缩写
+
+在 PostgreSQL 的 `heap_delete` 函数中，`crosscheck` 参数是一个可选的快照（`Snapshot`），用于在删除元组时执行额外的可见性检查。它的主要作用是确保删除操作符合某些特定的约束条件，通常与外键约束或其他复杂的事务逻辑相关。
+
+---
+
+### 1. **`crosscheck` 参数的作用**
+`crosscheck` 参数的主要功能是提供一个额外的快照，用于验证元组是否在该快照中可见。
+如果元组在 `crosscheck` 快照中不可见，则删除操作会被拒绝，并返回 `TM_Updated` 状态。这种机制通常用于确保事务一致性，避免删除操作破坏其他事务的逻辑。
+
+---
+
+### 2. **典型使用场景**
+#### **(1) 外键约束的级联删除**
+在外键约束的级联删除（`ON DELETE CASCADE`）中，`crosscheck` 参数可以用来确保引用的父表元组在删除时仍然符合外键约束的可见性规则。例如：
+- 当删除父表中的一行时，子表中的引用行可能需要被级联删除。
+- 在这种情况下，`crosscheck` 快照可以用来验证父表的元组是否仍然符合外键约束的可见性要求。
+
+#### **(2) 事务隔离级别的验证**
+在某些事务隔离级别（如可重复读或序列化）下，`crosscheck` 参数可以确保删除操作不会破坏其他事务的视图。例如：
+- 如果另一个事务已经修改了目标元组，使其在 `crosscheck` 快照中不可见，则当前事务的删除操作会被拒绝。
+
+#### **(3) 复杂的业务逻辑**
+在某些复杂的业务逻辑中，`crosscheck` 参数可以用来确保删除操作符合特定的业务规则。例如：
+- 在多表联动操作中，`crosscheck` 快照可以用来验证元组是否符合某些特定的条件。
+
+---
+
+### 3. **`crosscheck` 的工作机制**
+在 `heap_delete` 函数中，当 `crosscheck` 参数不为 `InvalidSnapshot` 时，会对目标元组执行额外的可见性检查：
+- 调用 `HeapTupleSatisfiesVisibility` 函数，使用 `crosscheck` 快照验证元组的可见性。
+- 如果元组在 `crosscheck` 快照中不可见，则删除操作会返回 `TM_Updated` 状态，表示元组已被其他事务更新或删除。
+
+代码片段如下：
+```c
+if (crosscheck != InvalidSnapshot && result == TM_Ok)
+{
+    if (!HeapTupleSatisfiesVisibility(&tp, crosscheck, buffer))
+        result = TM_Updated;
+}
+```
+
+---
+
+### 4. **返回值的处理**
+如果 `crosscheck` 检查失败，`heap_delete` 函数会返回 `TM_Updated`，并填充 `TM_FailureData` 结构体，提供有关失败的详细信息：
+- **`ctid`**: 指向元组的链式更新目标。
+- **`xmax`**: 表示删除元组的事务 ID。
+- **`cmax`**: 表示最后修改元组的命令 ID（仅在 `TM_SelfModified` 情况下可用）。
+
+调用者可以根据返回值和失败数据决定如何处理，例如重试操作或回滚事务。
+
+---
+
+### 5. **总结**
+`crosscheck` 参数在 `heap_delete` 中提供了一种灵活的机制，用于在删除元组时执行额外的可见性检查。它的典型应用场景包括外键约束的级联删除、事务隔离级别的验证以及复杂的业务逻辑。通过结合 `crosscheck` 快照，PostgreSQL 能够确保删除操作的正确性和一致性，同时避免破坏其他事务的逻辑。
+ */
 /*
  *	heap_delete - delete a tuple
  *

src/backend/access/heap/heapam_handler.c

@@ -356,6 +356,11 @@ heapam_tuple_update(Relation relation, ItemPointer otid, TupleTableSlot *slot,
 	return result;
 }
 
+/**
+	加行锁（LockTupleMode 4类），场景
+	- 更新或删除操作： 在执行 UPDATE 或 DELETE 操作时，需要对目标行加锁，以防止其他事务同时修改或删除该行。
+	- 显式行锁： 当用户通过 SELECT ... FOR UPDATE 或 SELECT ... FOR SHARE 等语句显式请求行锁时，底层会调用类似 heapam_tuple_lock 的函数来实现加锁。
+ */
 static TM_Result
 heapam_tuple_lock(Relation relation, ItemPointer tid, Snapshot snapshot,
 				  TupleTableSlot *slot, CommandId cid, LockTupleMode mode,

src/backend/catalog/heap.c

@@ -270,7 +270,13 @@ SystemAttributeByName(const char *attname)
  *				XXX END OF UGLY HARD CODED BADNESS XXX
  * ---------------------------------------------------------------- */
 
+/**
+总结
+ - heap_create_with_catalog 是一个高层次的函数，负责创建一个完整的、带有系统目录条目的关系。它会调用 heap_create 来完成物理存储的创建，并在系统目录中注册元数据。
+ - heap_create 是一个底层函数，专注于创建关系的物理存储，不涉及系统目录的操作。
 
+(这里的系统目录指的就是catalog那些系统表)
+ */
 /* ----------------------------------------------------------------
  *		heap_create		- Create an uncataloged heap relation
  *

src/backend/executor/nodeModifyTable.c

@@ -1093,6 +1093,11 @@ ExecInsert(ModifyTableContext *context,
 			 */
 			specToken = SpeculativeInsertionLockAcquire(GetCurrentTransactionId());
 
+			/**
+				推测性插入通常用于实现 INSERT ... ON CONFLICT 的逻辑。
+				在这种情况下，系统需要先尝试插入元组，然后检查是否存在冲突（例如违反唯一性约束）。
+				如果没有冲突，插入操作会被确认；如果有冲突，系统可以选择更新现有元组或放弃插入。
+			 */
 			/* insert the tuple, with the speculative token */
 			table_tuple_insert_speculative(resultRelationDesc, slot,
 										   estate->es_output_cid,

src/include/access/tableam.h

@@ -72,6 +72,10 @@ typedef enum ScanOptions
 	SO_NEED_TUPLES = 1 << 10,
 }			ScanOptions;
 
+/**
+	Result codes for table_{update,delete,lock_tuple}
+	update/delete/lock，它们都很相似，都需要考虑到时间上的绝对因素
+ */
 /*
  * Result codes for table_{update,delete,lock_tuple}, and for visibility
  * routines inside table AMs.
@@ -1276,6 +1280,10 @@ extern bool table_index_fetch_tuple_check(Relation rel,
  */
 
 
+/**
+	根据指定的 tid（元组标识符）从表中获取元组，并将其存储到 slot（元组槽）中
+	一般在modifytable（update操作）中被调用
+ */
 /*
  * Fetch tuple at `tid` into `slot`, after doing a visibility test according to
  * `snapshot`. If a tuple was found and passed the visibility test, returns
@@ -1440,6 +1448,12 @@ table_tuple_complete_speculative(Relation rel, TupleTableSlot *slot,
 												succeeded);
 }
 
+
+/**
+	该函数的主要功能是将多个元组批量插入到指定的表中。
+	通过批量操作，它能够减少对同一页面的多次锁定和解锁操作，同时将多个插入操作的日志（WAL，Write-Ahead Logging）合并为一条记录。
+	这种优化显著提高了插入性能，特别是在需要插入大量数据的场景下(如copy，临时表等)。
+ */
 /*
  * Insert multiple tuples into a table.
  *