Feedback-ID: i131946ab:Fastmail
Message-ID: <22fed8ba-01c3-2008-a256-4ea912d68fab@enterprisedb.com>
Date: Wed, 10 May 2023 11:50:14 +0200
MIME-Version: 1.0
User-Agent: Mozilla/5.0 (Macintosh; Intel Mac OS X 10.15; rv:102.0)
 Gecko/20100101 Thunderbird/102.10.1
Content-Language: en-US
From: Peter Eisentraut <peter.eisentraut@enterprisedb.com>
Subject: smgrzeroextend clarification
To: pgsql-hackers <pgsql-hackers@postgresql.org>
Content-Type: text/plain; charset=UTF-8; format=flowed
Content-Transfer-Encoding: 7bit
Archived-At: 
 <https://www.postgresql.org/message-id/22fed8ba-01c3-2008-a256-4ea912d68fab%40enterprisedb.com>
Precedence: bulk

I was looking at the new smgrzeroextend() function in the smgr API.  The 
documentation isn't very extensive:

/*
  *  smgrzeroextend() -- Add new zeroed out blocks to a file.
  *
  *      Similar to smgrextend(), except the relation can be extended by
  *      multiple blocks at once and the added blocks will be filled with
  *      zeroes.
  */

The documentation of smgrextend() is:

/*
  *  smgrextend() -- Add a new block to a file.
  *
  *      The semantics are nearly the same as smgrwrite(): write at the
  *      specified position.  However, this is to be used for the case of
  *      extending a relation (i.e., blocknum is at or beyond the current
  *      EOF).  Note that we assume writing a block beyond current EOF
  *      causes intervening file space to become filled with zeroes.
  */

So if you want to understand what smgrzeroextend() does, you need to 
mentally combine the documentation of three different functions.  Could 
we write documentation for each function that stands on its own?  And 
document the function arguments, like what does blocknum and nblocks mean?

Moreover, the text "except the relation can be extended by multiple 
blocks at once and the added blocks will be filled with zeroes" doesn't 
make much sense as a differentiation, because smgrextend() does that as 
well.

AFAICT, the differences between smgrextend() and smgrzeroextend() are:

1. smgrextend() writes a payload block in addition to extending the 
file, smgrzeroextend() just extends the file without writing a payload.

2. smgrzeroextend() uses various techniques (posix_fallocate() etc.) to 
make sure the extended space is actually reserved on disk, smgrextend() 
does not.

#1 seems fine, but the naming of the APIs does not reflect that at all.

If we think that #2 is important, maybe smgrextend() should do that as 
well?  Or at least explain why it's not needed?