Subject: A small correction to doc and comment of FSM for indexes

From: Alex Friedman <[email-masked]>
Date: Tue, 25 Feb 2025 19:24:14 +0200

Hi,

This patch fixes a couple of small inaccuracies in the doc and the comment for FSM about index handling.

1. In the doc for pg_freespacemap, it currently says:

> For indexes, what is tracked is entirely-unused pages, rather than free space within pages. Therefore, the values are not meaningful, just whether a page is full or empty.

However, as what is tracked is entirely-unused pages, the values mean whether a page is "in-use or empty", rather than "full or empty".

2. In indexfsm.c the header comment says:

>  *     This is similar to the FSM used for heap, in freespace.c, but instead
>  *     of tracking the amount of free space on pages, we only track whether
>  *     pages are completely free or in-use. We use the same FSM implementation
>  *     as for heaps, using BLCKSZ - 1 to denote used pages, and 0 for unused.

However, in the code we see that used pages are marked with 0:

> /*
>  * RecordUsedIndexPage - mark a page as used in the FSM
>  */
> void
> RecordUsedIndexPage(Relation rel, BlockNumber usedBlock)
> {
> 	RecordPageWithFreeSpace(rel, usedBlock, 0);
> }

And free pages are marked with BLCKSZ - 1:

> /*
>  * RecordFreeIndexPage - mark a page as free in the FSM
>  */
> void
> RecordFreeIndexPage(Relation rel, BlockNumber freeBlock)
> {
> 	RecordPageWithFreeSpace(rel, freeBlock, BLCKSZ - 1);
> }

And so, this patch also fixes the comment's "using BLCKSZ - 1 to denote used pages, and 0 for unused" to be "using 0 to denote used pages, and BLCKSZ - 1 for unused".

While these changes are minor, I've seen how this can cause a bit of confusion, and it would be good to clarify it.

Best regards,

Alex Friedman

From a1b78438343fca053aa0014687eaba34d5e160e0 Mon Sep 17 00:00:00 2001
From: Alex Friedman <[email-masked]>
Date: Tue, 25 Feb 2025 19:12:53 +0200
Subject: [PATCH v1] A small correction to doc and comment of FSM for indexes.

---
 doc/src/sgml/pgfreespacemap.sgml         | 2 +-
 src/backend/storage/freespace/indexfsm.c | 2 +-
 2 files changed, 2 insertions(+), 2 deletions(-)

diff --git a/doc/src/sgml/pgfreespacemap.sgml b/doc/src/sgml/pgfreespacemap.sgml
index 829ad60f32f..3774a9f8c6b 100644
--- a/doc/src/sgml/pgfreespacemap.sgml
+++ b/doc/src/sgml/pgfreespacemap.sgml
@@ -67,7 +67,7 @@
   <para>
    For indexes, what is tracked is entirely-unused pages, rather than free
    space within pages.  Therefore, the values are not meaningful, just
-   whether a page is full or empty.
+   whether a page is in-use or empty.
   </para>
  </sect2>
 
diff --git a/src/backend/storage/freespace/indexfsm.c b/src/backend/storage/freespace/indexfsm.c
index 1fc263892a7..3cd2437599d 100644
--- a/src/backend/storage/freespace/indexfsm.c
+++ b/src/backend/storage/freespace/indexfsm.c
@@ -16,7 +16,7 @@
  *	This is similar to the FSM used for heap, in freespace.c, but instead
  *	of tracking the amount of free space on pages, we only track whether
  *	pages are completely free or in-use. We use the same FSM implementation
- *	as for heaps, using BLCKSZ - 1 to denote used pages, and 0 for unused.
+ *	as for heaps, using 0 to denote used pages, and BLCKSZ - 1 for unused.
  *
  *-------------------------------------------------------------------------
  */
-- 
2.41.0

---

From: Michael Paquier <[email-masked]>
Date: Thu, 27 Mar 2025 10:21:39 +0900

On Tue, Feb 25, 2025 at 07:24:14PM +0200, Alex Friedman wrote:
> However, as what is tracked is entirely-unused pages, the values
> mean whether a page is "in-use or empty", rather than "full or
> empty".

Ah, right, you are obviously right here.  Applied and backpatched doen
to 13 as the docs of pg_freespacemap have been incorrect for a long
time.
--
Michael