Re: PostgreSQL extension API? Documentation?

On 02/27/16 08:37, Álvaro Hernández Tortosa wrote:
>     In other words: what is the API surface exposed by PostgreSQL to
> extension developers? The assumption is that no PostgreSQL code should be
> modified, just adding your own and calling existing funcitons.

That's an excellent question that repeatedly comes up, in particular
because of the difference between the way the MSVC linker works on Windows,
and the way most other linkers work on other platforms.

The issue there is ... on most non-Windows platforms, there are only the
general C rules to think about: if a symbol is static (or auto of course)
it is not visible to extensions, but otherwise it is.

For MSVC, in contrast, symbols need to have a certain decoration
(look for PGDLLIMPORT in various PostgreSQL .h files) for an MSVC-built
extension to be able to see it, otherwise it isn't accessible.

Well, that's not quite right. It turns out (and it may have taken some
work on the build process to make it turn out this way) ... *functions*
are accessible from MSVC (as long as they would be accessible under
normal C rules) whether or not they have PGDLLIMPORT. It's just
data symbols/variables that have to have PGDLLIMPORT or they aren't
available on Windows/MSVC.

And *that* arrangement is the result of a long thread in 2014 that
unfolded after discovering that what was really happening in MSVC
*before* that was that MSVC would silently pretend to link your
non-PGDLLIMPORT data symbols, and then give you the wrong data.

http://www.postgresql.org/message-id/flat/52FAB90B.6020302@2ndquadrant.com

In that long thread, there are a few messages in the middle that probably
give the closest current answer to your API question. Craig Ringer has
consistently favored making other platforms work more like Windows/MSVC,
so that the PGDLLIMPORT business would serve to limit and more clearly
define the API surface:

http://www.postgresql.org/message-id/52EF1468.6080107@2ndquadrant.com

Andres Freund had the pragmatic reply:

http://www.postgresql.org/message-id/20140203103701.GA1225@awork2.anarazel.de

> I think that'd be an exercise in futility. ... We'd break countless
> extensions people have written. ... we'd need to have a really
> separate API layer ... doesn't seem likely to arrive anytime soon,
> if ever.

which was ultimately concurred in by Tom, and Craig too:

http://www.postgresql.org/message-id/29286.1391436782@sss.pgh.pa.us
http://www.postgresql.org/message-id/52EFA654.8010609@2ndquadrant.com

Andres characterized it as "We have a (mostly) proper API. Just not
an internal/external API split."

http://www.postgresql.org/message-id/20140203142514.GD1225@awork2.anarazel.de

-Chap