Support parallelism for collecting dead items during lazy vacuum.

This feature allows the vacuum to leverage multiple CPUs in order to
collect dead items (i.e. the first pass over heap table) with parallel
workers. The parallel degree for parallel heap vacuuming is determined
based on the number of blocks to vacuum unless PARALLEL option of
VACUUM command is specified, and further limited by
max_parallel_maintenance_workers.

For the parallel heap scan to collect dead items, we utilize a
parallel block table scan, controlled by ParallelBlockTableScanDesc,
in conjunction with the read stream. The workers' parallel scan
descriptions are stored in the DSM space, enabling different parallel
workers to resume the heap scan (phase 1) after a cycle of heap
vacuuming and index vacuuming (phase 2 and 3) from their previous
state. However, due to the potential presence of pinned buffers loaded
by the read stream's look-ahead mechanism, we cannot abruptly stop
phase 1 even when the space of dead_items TIDs exceeds the
limit. Therefore, once the space of dead_items TIDs exceeds the limit,
we begin processing pages without attempting to retrieve additional
blocks by look-ahead mechanism until the read stream is exhausted,
even if the the memory limit is surpassed. While this approach may
increase the memory usage, it typically doesn't pose a significant
problem, as processing a few 10s-100s buffers doesn't substantially
increase the size of dead_items TIDs.

When the parallel heap scan to collect dead items is enabled, we
disable eager scanning. This is because parallel vacuum is available
only in the VACUUM command and would not occur frequently, which
doesn't align with the purpose of eager scanning.

Reviewed-by: Amit Kapila <[email protected]>
Reviewed-by: Hayato Kuroda <[email protected]>
Reviewed-by: Peter Smith <[email protected]>
Reviewed-by: Tomas Vondra <[email protected]>
Reviewed-by: Dilip Kumar <[email protected]>
Reviewed-by: Melanie Plageman <[email protected]>
Reviewed-by: Andres Freund <[email protected]>
Discussion: https://postgr.es/m/CAD21AoAEfCNv-GgaDheDJ+s-p_Lv1H24AiJeNoPGCmZNSwL1YA@mail.gmail.com

Author: MasahikoSawada

doc/src/sgml/ref/vacuum.sgml

@@ -280,25 +280,41 @@ VACUUM [ ( <replaceable class="parameter">option</replaceable> [, ...] ) ] [ <re
     <term><literal>PARALLEL</literal></term>
     <listitem>
      <para>
-      Perform index vacuum and index cleanup phases of <command>VACUUM</command>
-      in parallel using <replaceable class="parameter">integer</replaceable>
-      background workers (for the details of each vacuum phase, please
-      refer to <xref linkend="vacuum-phases"/>).  The number of workers used
-      to perform the operation is equal to the number of indexes on the
-      relation that support parallel vacuum which is limited by the number of
-      workers specified with <literal>PARALLEL</literal> option if any which is
-      further limited by <xref linkend="guc-max-parallel-maintenance-workers"/>.
-      An index can participate in parallel vacuum if and only if the size of the
-      index is more than <xref linkend="guc-min-parallel-index-scan-size"/>.
-      Please note that it is not guaranteed that the number of parallel workers
-      specified in <replaceable class="parameter">integer</replaceable> will be
-      used during execution.  It is possible for a vacuum to run with fewer
-      workers than specified, or even with no workers at all.  Only one worker
-      can be used per index.  So parallel workers are launched only when there
-      are at least <literal>2</literal> indexes in the table.  Workers for
-      vacuum are launched before the start of each phase and exit at the end of
-      the phase.  These behaviors might change in a future release.  This
-      option can't be used with the <literal>FULL</literal> option.
+      Perform scanning heap, index vacuum, and index cleanup phases of
+      <command>VACUUM</command> in parallel using
+      <replaceable class="parameter">integer</replaceable> background workers
+      (for the details of each vacuum phase, please refer to
+      <xref linkend="vacuum-phases"/>).
+     </para>
+     <para>
+      For heap tables, the number of workers used to perform the scanning
+      heap is determined based on the size of table. A table can participate in
+      parallel scanning heap if and only if the size of the table is more than
+      <xref linkend="guc-min-parallel-table-scan-size"/>. During scanning heap,
+      the heap table's blocks will be divided into ranges and shared among the
+      cooperating processes. Each worker process will complete the scanning of
+      its given range of blocks before requesting an additional range of blocks.
+     </para>
+     <para>
+      The number of workers used to perform parallel index vacuum and index
+      cleanup is equal to the number of indexes on the relation that support
+      parallel vacuum. An index can participate in parallel vacuum if and only
+      if the size of the index is more than <xref linkend="guc-min-parallel-index-scan-size"/>.
+      Only one worker can be used per index. So parallel workers for index vacuum
+      and index cleanup are launched only when there are at least <literal>2</literal>
+      indexes in the table.
+     </para>
+     <para>
+      Workers for vacuum are launched before the start of each phase and exit
+      at the end of the phase. The number of workers for each phase is limited by
+      the number of workers specified with <literal>PARALLEL</literal> option if
+      any which is futher limited by <xref linkend="guc-max-parallel-maintenance-workers"/>.
+      Please note that in any parallel vacuum phase, it is not guaanteed that the
+      number of parallel workers specified in <replaceable class="parameter">integer</replaceable>
+      will be used during execution. It is possible for a vacuum to run with fewer
+      workers than specified, or even with no workers at all. These behaviors might
+      change in a future release. This option can't be used with the <literal>FULL</literal>
+      option.
      </para>
     </listitem>
    </varlistentry>

src/backend/access/heap/heapam_handler.c

@@ -2671,6 +2671,10 @@ static const TableAmRoutine heapam_methods = {
 	.scan_sample_next_tuple = heapam_scan_sample_next_tuple,
 
 	.parallel_vacuum_compute_workers = heap_parallel_vacuum_compute_workers,
+	.parallel_vacuum_estimate = heap_parallel_vacuum_estimate,
+	.parallel_vacuum_initialize = heap_parallel_vacuum_initialize,
+	.parallel_vacuum_initialize_worker = heap_parallel_vacuum_initialize_worker,
+	.parallel_vacuum_collect_dead_items = heap_parallel_vacuum_collect_dead_items,
 };