PageGetFreeSpace() isn't quite the right thing for some of its callers

I notice that a number of contrib modules call PageGetFreeSpace()
where they should really call PageGetExactFreeSpace() instead.
PageGetFreeSpace() assumes that the overhead for one line pointer
should be pro-actively subtracted, which is handy for plenty of nbtree
code, but doesn't quite make sense for stuff like pageinspect's
bt_page_stats() function.

I was thinking about fixing one or two of these buglets, without
expecting that to be complicated in any way. However, now that I take
a closer look I also notice that there is core code that calls
PageGetFreeSpace() when it probably shouldn't, either. For example,
what business does heap_xlog_visible() have calling
PageGetFreeSpace()? I also doubt that terminate_brin_buildstate()
should call it -- doesn't BRIN avoid using conventional item pointers?
Doesn't GIN's entryIsEnoughSpace() function double-count the item
pointer overhead?

I wonder if we should add an assertion based on the pd_special offset
of the page to PageGetFreeSpace(). That would make it harder to make
mistakes like this in the future. Maybe it would be better to revise
the whole API instead, though.
--
Peter Geoghegan