C2 on xlog

Author: interma

src/backend/access/heap/heapam.c

@@ -2229,6 +2229,12 @@ heap_insert(Relation relation, HeapTuple tup, CommandId cid,
 		XLogRegisterBuffer(0, buffer, REGBUF_STANDARD | bufflags);
 		XLogRegisterBufData(0, (char *) &xlhdr, SizeOfHeapHeader);
 		/* PG73FORMAT: write bitmap [+ padding] [+ oid] + data */
+		/**
+3. 为什么跳过头部
+堆元组的头部（HeapTupleHeader）包含元组的元信息，例如事务状态、行号等。
+这些信息通常已经通过其他方式（如缓冲区的全页面镜像）记录到 WAL 中，
+因此这里只需要记录实际的数据部分，减少 WAL 日志的大小。
+		 */
 		XLogRegisterBufData(0,
 							(char *) heaptup->t_data + SizeofHeapTupleHeader,
 							heaptup->t_len - SizeofHeapTupleHeader);
@@ -9693,6 +9699,8 @@ heap_xlog_delete(XLogReaderState *record)
 		UnlockReleaseBuffer(buffer);
 }
 
+// 用于处理堆表（heap table）插入操作的 WAL（Write-Ahead Logging）重放函数
+// 非常好的示例
 static void
 heap_xlog_insert(XLogReaderState *record)
 {

src/backend/access/transam/xloginsert.c

@@ -271,6 +271,8 @@ XLogRegisterBuffer(uint8 block_id, Buffer buffer, uint8 flags)
 	regbuf = &registered_buffers[block_id];
 
 	BufferGetTag(buffer, &regbuf->rlocator, &regbuf->forkno, &regbuf->block);
+	// 这里只是保存page指针，而不是记录整个页面到xlog中
+	// 具体的记录逻辑在XLogRecordAssemble()中
 	regbuf->page = BufferGetPage(buffer);
 	regbuf->flags = flags;
 	regbuf->rdata_tail = (XLogRecData *) &regbuf->rdata_head;

src/backend/access/transam/xlogutils.c

@@ -347,6 +347,13 @@ XLogInitBufferForRedo(XLogReaderState *record, uint8 block_id)
  * If 'get_cleanup_lock' is true, a "cleanup lock" is acquired on the buffer
  * using LockBufferForCleanup(), instead of a regular exclusive lock.
  */
+/**
+函数返回一个 XLogRedoAction 枚举值，指示页面的处理结果：
+	BLK_RESTORED: 页面通过全页面镜像恢复。
+	BLK_DONE: 页面已经包含最新的修改，无需进一步操作。
+	BLK_NEEDS_REDO: 页面需要应用 WAL 记录中的修改。
+	BLK_NOTFOUND: 页面不存在。
+ */
 XLogRedoAction
 XLogReadBufferForRedoExtended(XLogReaderState *record,
 							  uint8 block_id,
@@ -382,6 +389,7 @@ XLogReadBufferForRedoExtended(XLogReaderState *record,
 		elog(PANIC, "block to be initialized in redo routine must be marked with WILL_INIT flag in the WAL record");
 
 	/* If it has a full-page image and it should be restored, do it. */
+	/* FPI routine */
 	if (XLogRecBlockImageApply(record, block_id))
 	{
 		Assert(XLogRecHasBlockImage(record, block_id));
@@ -414,20 +422,28 @@ XLogReadBufferForRedoExtended(XLogReaderState *record,
 		if (forknum == INIT_FORKNUM)
 			FlushOneBuffer(*buf);
 
-		return BLK_RESTORED;
+		return BLK_RESTORED;	// 页面通过全页面镜像FPI恢复。
 	}
 	else
 	{
 		*buf = XLogReadBufferExtended(rlocator, forknum, blkno, mode, prefetch_buffer);
 		if (BufferIsValid(*buf))
 		{
+			/**
+				- 普通独占锁（Exclusive Lock）: 使用 LockBuffer 函数获取，
+					允许对页面进行修改，但不允许其他进程同时访问该页面。
+				- 清理锁（Cleanup Lock）: 使用 LockBufferForCleanup 函数获取，
+					通常用于清理页面中的死元组或进行更高级别的操作。
+					清理锁是独占锁的一种扩展，具有更高的权限。
+			 */
 			if (mode != RBM_ZERO_AND_LOCK && mode != RBM_ZERO_AND_CLEANUP_LOCK)
 			{
 				if (get_cleanup_lock)
 					LockBufferForCleanup(*buf);
 				else
 					LockBuffer(*buf, BUFFER_LOCK_EXCLUSIVE);
 			}
+			// 如果页面的 LSN 大于或等于 WAL 记录的 LSN，说明页面已经包含了最新的修改，返回 BLK_DONE。
 			if (lsn <= PageGetLSN(BufferGetPage(*buf)))
 				return BLK_DONE;
 			else
@@ -438,6 +454,16 @@ XLogReadBufferForRedoExtended(XLogReaderState *record,
 	}
 }
 
+/**
+XLogReadBufferExtended:
+	专门用于 WAL 重放（XLOG replay）期间读取页面。
+	主要在崩溃恢复或主备复制的 WAL 日志重放过程中使用。
+	适配了 WAL 重放的特殊需求，例如处理页面不存在的情况或全零页面。
+	
+ReadBufferExtended:
+	用于正常系统操作期间读取页面。
+	适用于普通的表操作（如查询、插入、更新、删除）中访问页面。
+ */
 /*
  * XLogReadBufferExtended
  *		Read a page during XLOG replay

src/backend/commands/sequence.c

@@ -621,6 +621,12 @@ DeleteSequenceTuple(Oid relid)
  * entry, but we keep it around to ease porting of C code that may have
  * called the function directly.
  */
+/**
+在 hot-standby 模式下不可以调用 nextval，
+因为它是写操作，会抛出类似以下的错误：
+	transaction
+	ERROR:  cannot execute nextval() in a read-only transactio
+ */
 Datum
 nextval(PG_FUNCTION_ARGS)
 {
@@ -735,6 +741,13 @@ elm->last 表示上一次返回的序列值，而 elm->cached 表示当前缓存
 	这里给buffer加了独占锁（同时也pin了buffer）：
 	read_seq_tuple 函数通过调用 ReadBuffer：它对缓冲区也进行了pin操作
 	 */
+	/**
+	 * 另外留意这里没通过mvcc机制来读tuple:
+	 * - xmin 通常被设置为 FrozenTransactionId，以确保该元组始终可见
+	 * - xmax 通常被设置为 InvalidTransactionId，表示该元组不会被删除或更新
+	 * 
+	 * 因此导致了一些很trick的机制(hot-standy)，见笔记
+	 */
 	seq = read_seq_tuple(seqrel, &buf, &seqdatatuple);
 
 	page = BufferGetPage(buf);
@@ -886,6 +899,7 @@ elm->last 表示上一次返回的序列值，而 elm->cached 表示当前缓存
 		 * sequence values if we crash.
 		 */
 		XLogBeginInsert();
+		// REGBUF_WILL_INIT: 这是一个标志，表示缓冲区将被完全重新初始化，因此不需要记录其当前内容
 		XLogRegisterBuffer(0, buf, REGBUF_WILL_INIT);
 
 		/* set values that will be saved in xlog */
@@ -894,7 +908,8 @@ elm->last 表示上一次返回的序列值，而 elm->cached 表示当前缓存
 		seq->log_cnt = 0;
 
 		xlrec.locator = seqrel->rd_locator;
-
+		
+		// 只通过maindata部分记录数据就足够了，不需要blockdata（其中永远只有一条tuple）
 		XLogRegisterData((char *) &xlrec, sizeof(xl_seq_rec));
 		XLogRegisterData((char *) seqdatatuple.t_data, seqdatatuple.t_len);
 
@@ -1903,6 +1918,7 @@ seq_redo(XLogReaderState *record)
 	if (info != XLOG_SEQ_LOG)
 		elog(PANIC, "seq_redo: unknown op code %u", info);
 
+	// 每次都重新初始化一个新的buffer
 	buffer = XLogInitBufferForRedo(record, 0);
 	page = (Page) BufferGetPage(buffer);
 
@@ -1915,6 +1931,7 @@ seq_redo(XLogReaderState *record)
 	 * are supposed to change will change, even transiently. We must palloc
 	 * the local page for alignment reasons.
 	 */
+	// NB：热备模式下的一个corner case，需要构建localpage来解决，见gpt详解
 	localpage = (Page) palloc(BufferGetPageSize(buffer));
 
 	PageInit(localpage, BufferGetPageSize(buffer), sizeof(sequence_magic));
@@ -1930,6 +1947,8 @@ seq_redo(XLogReaderState *record)
 
 	PageSetLSN(localpage, lsn);
 
+	// 虽然 memcpy 不是原子操作，但它的使用场景是安全的：
+	// 锁的保护: 在 memcpy 操作期间，缓冲区的独占锁确保了没有其他进程可以访问该缓冲区。
 	memcpy(page, localpage, BufferGetPageSize(buffer));
 	// 让bgwriter待会儿把这个buffer写到磁盘上
 	MarkBufferDirty(buffer);

src/backend/replication/logical/decode.c

@@ -884,6 +884,14 @@ DecodeAbort(LogicalDecodingContext *ctx, XLogRecordBuffer *buf,
 	UpdateDecodingStats(ctx);
 }
 
+/**
+4. 示例场景
+假设有一个表 users，执行了SQL 插入操作，对应的 WAL 日志记录会被 DecodeInsert 函数解析为以下逻辑变更事件：
+	表名: users
+	操作类型: 插入
+	插入的元组: {id: 1, name: 'Alice'}
+这些信息会被传递给逻辑复制的输出插件，用于生成逻辑复制流。
+ */
 /*
  * Parse XLOG_HEAP_INSERT (not MULTI_INSERT!) records into tuplebufs.
  *

src/include/access/heapam_xlog.h

@@ -70,6 +70,13 @@
 /* PD_ALL_VISIBLE was cleared */
 #define XLH_INSERT_ALL_VISIBLE_CLEARED			(1<<0)
 #define XLH_INSERT_LAST_IN_MULTI				(1<<1)
+/**
+XLH_INSERT_IS_SPECULATIVE 表示插入操作是“试探性插入”（speculative insertion）。
+试探性插入是一种特殊的插入模式，通常用于支持唯一约束（unique constraint）或排他性约束（exclusion constraint）的并发检查。
+
+在试探性插入中，元组（tuple）会被暂时插入到堆表中，但其状态是未决的（pending）。
+只有在约束检查通过后，插入才会被正式确认；否则，插入会被回滚。
+ */
 #define XLH_INSERT_IS_SPECULATIVE				(1<<2)
 #define XLH_INSERT_CONTAINS_NEW_TUPLE			(1<<3)
 #define XLH_INSERT_ON_TOAST_RELATION			(1<<4)

src/include/access/xlog_internal.h

@@ -354,10 +354,26 @@ typedef struct RmgrData
 	const char *(*rm_identify) (uint8 info);
 	void		(*rm_startup) (void);
 	void		(*rm_cleanup) (void);
+/**
+void (*rm_mask)(char *pagedata, BlockNumber blkno): 掩码函数，
+	用于屏蔽页面中不需要进行一致性检查的部分。这在启用了 wal_consistency_checking 时非常重要。
+void (*rm_decode)(struct LogicalDecodingContext *ctx, struct XLogRecordBuffer *buf): 解码函数，
+	用于逻辑解码场景，将 WAL日志记录转换为逻辑变更事件。
+ */
 	void		(*rm_mask) (char *pagedata, BlockNumber blkno);
 	void		(*rm_decode) (struct LogicalDecodingContext *ctx,
 							  struct XLogRecordBuffer *buf);
 } RmgrData;
+/**
+2. 掩码函数的作用
+掩码函数的主要作用是屏蔽页面中某些动态变化但不影响逻辑一致性的部分。这些部分可能在页面修改后发生变化，但不会影响页面的逻辑内容。例如：
+- 事务状态信息: 页面中的事务状态（如 xmin、xmax）可能会随着事务的提交或回滚而变化，但这些变化不影响页面的逻辑一致性。
+- 空闲空间指针: 页面中的空闲空间指针可能会随着插入或删除操作而变化，但这些变化不影响页面的逻辑内容。
+- 填充字节: 页面中用于对齐的填充字节可能会发生变化，但这些字节对页面的逻辑内容没有影响。
+
+通过屏蔽这些部分，掩码函数确保了 wal_consistency_checking 只关注页面的逻辑一致性，而忽略无关的物理变化。
+ */
+
 
 extern PGDLLIMPORT RmgrData RmgrTable[];
 extern void RmgrStartup(void);