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?