From: Peter Eisentraut <peter.eisentraut@enterprisedb.com>
To: pgsql-hackers <pgsql-hackers@postgresql.org>
Subject: smgrzeroextend clarification
Date: Wed, 10 May 2023 11:50:14 +0200
Message-ID: <22fed8ba-01c3-2008-a256-4ea912d68fab@enterprisedb.com> (raw)
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?
Reply instructions:
You may reply publicly to this message via plain-text email
using any one of the following methods:
* Reply to all the recipients using the --to and --cc options:
reply via email
To: pgsql-hackers@postgresql.org
Cc: peter.eisentraut@enterprisedb.com
Subject: Re: smgrzeroextend clarification
In-Reply-To: <22fed8ba-01c3-2008-a256-4ea912d68fab@enterprisedb.com>
* Save the following mbox file, import it into your mail client,
and reply-to-all from there: mbox
This inbox is served by DDX for PostgreSQL; see mirroring instructions
for how to clone and mirror all data and code used for this inbox