The documentation for the Server Programming Interface
is underspecified such that it is impossible to create
real extensions using only the documented interface.
For example, in the example 43.5
http://www.postgresql.org/docs/9.1/static/spi-examples.html
a variable of type SPITupleTable is being dereferenced
as tupdesc->natts but this is not documented. The SPI
documentation suggests studying the contributed extension
code for further examples but that code is full of hundreds
of features which are not in the SPI at all.
My own SPI code uses dozens of macros and field names which
I found in existing source and in conversations on the
mailing lists. I'm always nervous when a new release
comes out because the API I am using is not official and
might therefore change and break my code. This is especially
bad since much of the code is not type-safe and problems
will tend to be hidden by all of the casts in the
pre-ISO-C-style macro code.
It would be good if the Server Programming Interface were
sufficiently documented that most of the contributed
extensions which ship with PostgreSQL and most of the
SPI-based modules in the backend were using ONLY the
documented features of the SPI. Macros hiding casts and
typedefs hiding void * types should replaced with
inline functions and pointers to specific strong types.
To be very clear: Yes, I can always rummage around in
the include files and source to find out how to do things
IN THIS RELEASE. But I can't expect PostgreSQL development
to avoid breaking the idioms I happen upon, nor can
the developers write unit tests to ensure that proper
extensions using the SPI will not break.
I would like to be able to program to a C or C++ SPI
which is clean, complete and type-safe. I am good at
reading API documentation in C or C++ and would be happy
to review any proposed improvements.
_Greg
