From 352bf7a3d981243bc47e9681381b7297aaf48939 Mon Sep 17 00:00:00 2001
From: Tomas Vondra <tomas@2ndquadrant.com>
Date: Fri, 5 Apr 2024 19:49:55 +0200
Subject: [PATCH v20240405 1/3] Prefetch blocks read by
 write_reconstructed_file

When write_reconstructed_file() reconstructs file from incremental
backups, it reads data from multiple files. In most cases the access
is fairly sequential and the kernel read-ahead does a good job, but
the pattern may easily be too random due to skipping many blocks in
each backup. Also, some read-ahead may not work that well in some
filesystems (e.g. ZFS).

This adds a --prefetch option to force explicit prefetching. When
used, the system prefetches the next 128 blocks (1MB). This value
is mostly arbitrary, but not entirely - it needs to be high enough
to cover the 1MB chunks used in one of the following patches.

XXX It would be possible to allow specifying a custom value, so it
would be "--prefetch N" where N would be 0-1024 or something like
that. But it seems unnecessary, so perhaps future improvement.
---
 doc/src/sgml/ref/pg_combinebackup.sgml      |  11 ++
 src/bin/pg_combinebackup/pg_combinebackup.c |   9 ++
 src/bin/pg_combinebackup/reconstruct.c      | 132 +++++++++++++++++++-
 src/bin/pg_combinebackup/reconstruct.h      |   1 +
 4 files changed, 152 insertions(+), 1 deletion(-)

diff --git a/doc/src/sgml/ref/pg_combinebackup.sgml b/doc/src/sgml/ref/pg_combinebackup.sgml
index 658e9a759c8..76eb88e3044 100644
--- a/doc/src/sgml/ref/pg_combinebackup.sgml
+++ b/doc/src/sgml/ref/pg_combinebackup.sgml
@@ -230,6 +230,17 @@ PostgreSQL documentation
       </listitem>
      </varlistentry>
 
+     <varlistentry>
+      <term><option>--prefetch</option></term>
+      <listitem>
+       <para>
+        Enable asynchronous prefetching of blocks. If this option is not
+        specified, it's up to the operating system to prefetch data based
+        on access pattern.
+       </para>
+      </listitem>
+     </varlistentry>
+
      <varlistentry>
        <term><option>-V</option></term>
        <term><option>--version</option></term>
diff --git a/src/bin/pg_combinebackup/pg_combinebackup.c b/src/bin/pg_combinebackup/pg_combinebackup.c
index 1b07ca3fb64..15e7e711482 100644
--- a/src/bin/pg_combinebackup/pg_combinebackup.c
+++ b/src/bin/pg_combinebackup/pg_combinebackup.c
@@ -35,6 +35,9 @@
 #define INCREMENTAL_PREFIX			"INCREMENTAL."
 #define INCREMENTAL_PREFIX_LENGTH	(sizeof(INCREMENTAL_PREFIX) - 1)
 
+/* Default prefetch target 1MB (for 8K blocks). */
+#define	PREFETCH_TARGET	128
+
 /*
  * Tracking for directories that need to be removed, or have their contents
  * removed, if the operation fails.
@@ -68,6 +71,7 @@ typedef struct cb_options
 	cb_tablespace_mapping *tsmappings;
 	pg_checksum_type manifest_checksums;
 	bool		no_manifest;
+	int			prefetch_target;
 	DataDirSyncMethod sync_method;
 	CopyMethod	copy_method;
 } cb_options;
@@ -132,6 +136,7 @@ main(int argc, char *argv[])
 		{"sync-method", required_argument, NULL, 3},
 		{"clone", no_argument, NULL, 4},
 		{"copy-file-range", no_argument, NULL, 5},
+		{"prefetch", no_argument, NULL, 6},
 		{NULL, 0, NULL, 0}
 	};
 
@@ -202,6 +207,9 @@ main(int argc, char *argv[])
 			case 5:
 				opt.copy_method = COPY_METHOD_COPY_FILE_RANGE;
 				break;
+			case 6:
+				opt.prefetch_target = PREFETCH_TARGET;
+				break;
 			default:
 				/* getopt_long already emitted a complaint */
 				pg_log_error_hint("Try \"%s --help\" for more information.", progname);
@@ -978,6 +986,7 @@ process_directory_recursively(Oid tsoid,
 											  &checksum_length,
 											  &checksum_payload,
 											  opt->copy_method,
+											  opt->prefetch_target,
 											  opt->debug,
 											  opt->dry_run);
 		}
diff --git a/src/bin/pg_combinebackup/reconstruct.c b/src/bin/pg_combinebackup/reconstruct.c
index 15f62c18df8..ea740fd6232 100644
--- a/src/bin/pg_combinebackup/reconstruct.c
+++ b/src/bin/pg_combinebackup/reconstruct.c
@@ -59,6 +59,7 @@ static void write_reconstructed_file(char *input_filename,
 									 off_t *offsetmap,
 									 pg_checksum_context *checksum_ctx,
 									 CopyMethod copy_method,
+									 int prefetch_target,
 									 bool debug,
 									 bool dry_run);
 static void read_bytes(rfile *rf, void *buffer, unsigned length);
@@ -67,6 +68,27 @@ static void write_block(int wfd, char *output_filename,
 						pg_checksum_context *checksum_ctx);
 static void read_block(rfile *s, off_t off, uint8 *buffer);
 
+/*
+ * state of the asynchronous prefetcher
+ */
+typedef struct prefetch_state
+{
+	unsigned	next_block;			/* block to prefetch next */
+	int			prefetch_distance;	/* current distance (<= target) */
+	int			prefetch_target;	/* target distance */
+
+	/* prefetch statistics - number of prefetched blocks */
+	unsigned	prefetch_blocks;
+} prefetch_state;
+
+static void prefetch_init(prefetch_state *state,
+						  int prefetch_target);
+static void prefetch_blocks(prefetch_state *state,
+							unsigned block,
+							unsigned block_length,
+							rfile **sourcemap,
+							off_t *offsetmap);
+
 /*
  * Reconstruct a full file from an incremental file and a chain of prior
  * backups.
@@ -95,6 +117,7 @@ reconstruct_from_incremental_file(char *input_filename,
 								  int *checksum_length,
 								  uint8 **checksum_payload,
 								  CopyMethod copy_method,
+								  int prefetch_target,
 								  bool debug,
 								  bool dry_run)
 {
@@ -331,7 +354,7 @@ reconstruct_from_incremental_file(char *input_filename,
 		write_reconstructed_file(input_filename, output_filename,
 								 block_length, sourcemap, offsetmap,
 								 &checksum_ctx, copy_method,
-								 debug, dry_run);
+								 prefetch_target, debug, dry_run);
 		debug_reconstruction(n_prior_backups + 1, source, dry_run);
 	}
 
@@ -542,12 +565,17 @@ write_reconstructed_file(char *input_filename,
 						 off_t *offsetmap,
 						 pg_checksum_context *checksum_ctx,
 						 CopyMethod copy_method,
+						 int prefetch_target,
 						 bool debug,
 						 bool dry_run)
 {
 	int			wfd = -1;
 	unsigned	i;
 	unsigned	zero_blocks = 0;
+	prefetch_state	prefetch;
+
+	/* initialize the block prefetcher */
+	prefetch_init(&prefetch, prefetch_target);
 
 	/* Debugging output. */
 	if (debug)
@@ -644,6 +672,9 @@ write_reconstructed_file(char *input_filename,
 		if (dry_run)
 			continue;
 
+		/* do prefetching if enabled */
+		prefetch_blocks(&prefetch, i, block_length, sourcemap, offsetmap);
+
 		/* Read or zero-fill the block as appropriate. */
 		if (s == NULL)
 		{
@@ -722,6 +753,14 @@ write_reconstructed_file(char *input_filename,
 			pg_log_debug("zero-filled %u blocks", zero_blocks);
 	}
 
+	if (prefetch.prefetch_blocks > 0)
+	{
+		/* print how many blocks we prefetched / skipped */
+		pg_log_debug("prefetch blocks %u (%u skipped)",
+					 prefetch.prefetch_blocks,
+					 (block_length - prefetch.prefetch_blocks));
+	}
+
 	/* Close the output file. */
 	if (wfd >= 0 && close(wfd) != 0)
 		pg_fatal("could not close \"%s\": %m", output_filename);
@@ -775,3 +814,94 @@ read_block(rfile *s, off_t off, uint8 *buffer)
 					 (unsigned long long) off);
 	}
 }
+
+/*
+ * prefetch_init
+ *		Initializes state of the prefetcher.
+ *
+ * Initialize state of the prefetcher, to start with the first block and maximum
+ * prefetch distance (prefetch_target=0 means prefetching disabled). The actual
+ * prefetch distance will gradually increase, until it reaches the target.
+ */
+static void
+prefetch_init(prefetch_state *state, int prefetch_target)
+{
+	Assert(prefetch_target >= 0);
+
+	state->next_block = 0;
+	state->prefetch_distance = 0;
+	state->prefetch_target = prefetch_target;
+	state->prefetch_blocks = 0;
+}
+
+/*
+ * prefetch_blocks
+ *		Perform asynchronous prefetching of blocks to be reconstructed next.
+ *
+ * Initiates asynchronous prefetch of to be reconstructed blocks.
+ *
+ * current_block - The block to be reconstructed in the current loop, right
+ * after the prefetching. This means we're potentially prefetching blocks
+ * in the range [current_block+1, current_block+current_dinstance], with
+ * both values inclusive.
+ *
+ * block_length - Number of blocks to reconstruct, also length of sourcemap
+ * and offsetmap arrays.
+ */
+static void
+prefetch_blocks(prefetch_state *state, unsigned current_block,
+				unsigned block_length, rfile **sourcemap, off_t* offsetmap)
+{
+#ifdef USE_PREFETCH
+	unsigned	max_block;
+
+	/* bail out if prefetching not enabled */
+	if (state->prefetch_target == 0)
+		return;
+
+	/* bail out if we've already prefetched the last block */
+	if (state->next_block == block_length)
+		return;
+
+	/* gradually increase prefetch distance until the target */
+	state->prefetch_distance = Min(state->prefetch_distance + 1,
+								   state->prefetch_target);
+
+	/*
+	 * Where should we start prefetching? We don't want to prefetch blocks
+	 * that we've already prefetched, that's pointless. And we also don't
+	 * want to prefetch the block we're just about to read. This can't
+	 * overflow because we know (current_block < block_length).
+	 */
+	state->next_block = Max(state->next_block, current_block + 1);
+
+	/*
+	 * How far to prefetch? Calculate the first block to not prefetch, i.e.
+	 * right after [current_block + current_distance]. It's possible the
+	 * second part overflows and wraps around, but in that case we just
+	 * don't prefetch a couple pages at the end.
+	 *
+	 * XXX But this also shouldn't be possible, thanks to the check of
+	 * (next_block == block_length) at the very beginning.
+	 */
+	max_block = Min(block_length, current_block + state->prefetch_distance + 1);
+
+	while (state->next_block < max_block)
+	{
+		rfile  *f = sourcemap[state->next_block];
+		off_t	off = offsetmap[state->next_block];
+
+		state->next_block++;
+
+		if (f == NULL)
+			continue;
+
+		state->prefetch_blocks += 1;
+
+		/* We ignore errors because this is only a hint.*/
+		(void) posix_fadvise(f->fd, off, BLCKSZ, POSIX_FADV_WILLNEED);
+	}
+
+	Assert(state->next_block <= block_length);
+#endif
+}
diff --git a/src/bin/pg_combinebackup/reconstruct.h b/src/bin/pg_combinebackup/reconstruct.h
index 902a8e9abb5..e2089f25818 100644
--- a/src/bin/pg_combinebackup/reconstruct.h
+++ b/src/bin/pg_combinebackup/reconstruct.h
@@ -28,6 +28,7 @@ extern void reconstruct_from_incremental_file(char *input_filename,
 											  int *checksum_length,
 											  uint8 **checksum_payload,
 											  CopyMethod copy_method,
+											  int prefetch_target,
 											  bool debug,
 											  bool dry_run);
 
-- 
2.44.0

