On 2015-08-16 05:58:17 +0200, Andres Freund wrote:
> On 2015-08-15 23:50:09 -0400, Noah Misch wrote:
> > The policy would then be
> > (already is?) to wrap in "#ifdef FRONTEND" any inline function that uses a
> > backend symbol. When a header is dedicated to such functions, we might
> > avoid
> > the whole header in the frontend instead of wrapping each function. That
> > policy works for me.
>
> Cool. I was wondering before where we'd document policy around
> this. sources.sgml?
As Noah I think it'd be good if we, over time, started to document a few
more things one currently have to pick up over time. I'm wondering
whether these should be subsections under a new sect1 ('Code Structure'?
Don't like that much), or all independent sect1s.
Stuff I'd like to see documented there over time includes:
1) Definition of the standard that we require, i.e. for now C89.
2) error handling with setjmp, specifically that and when volatile has
to be used.
3) Signal handlers, and what you can/cannod do.
4) That we rely on 4 byte aligned single-copy atomicity (i.e. some
recent value is read, not a mixture of two), but that we do not realy
on atomic 8 byte writes/reads.
The WIP patch I have on C89 and static inline is:
<sect1 id="source-structure">
<title>Structure</title>
<simplesect>
<title>C Standard</title>
<para>
Code in <productname>PostgreSQL</> should only rely on language
features available in the C89 standard. That means a conforming
C89 compiler has to be able to compile postgres. Features from
later revision of the C standard or compiler specific features
can be used, if a fallback is provided.
</para>
<para>
For example <literal>static inline</> and
<literal>_StaticAssert()</literal> are used, even though they are
from newer revisions of the C standard. If not available we
respectively fall back to defining the functions without inline,
and to using a C89 compatible replacement that also emits errors,
but emits far less readable errors.
</para>
</simplesect>
<simplesect>
<title>Function-Like Macros and Inline Functions</title>
<para>
Both, macros with arguments and <literal>static inline</>
functions, may be used. The latter are preferrable if there are
multiple-evaluation hazards when written as a macro, as e.g. the
case with
<programlisting>
#define Max(x, y) ((x) > (y) ? (x) : (y))
</programlisting>
or when the macro would be very long. In other cases it's only
possible to use macros, or at least easier. For example because
expressions of various types need to be passed to the macro.
</para>
<para>
When defining an inline function in a header that references
symbols (i.e. variables, functions) that are only available as
part of the backend, the function may not be visible when included
from frontend code.
<programlisting>
#ifndef FRONTEND
static inline MemoryContext
MemoryContextSwitchTo(MemoryContext context)
{
MemoryContext old = CurrentMemoryContext;
CurrentMemoryContext = context;
return old;
}
#endif /* FRONTEND */
</programlisting>
In this example <literal>CurrentMemoryContext</>, which is only
available in the backend, is referenced and the function thus
hidden with a <literal>#ifndef FRONTEND</literal>. This rule
exists because some compilers emit references to symbols
contained in inline functions even if the function is not used.
</para>
</simplesect>
</sect1>
That's not yet perfect, but shows what I'm thinking of. Comments?
Greetings,
Andres Freund
--
Sent via pgsql-hackers mailing list (pgsql-hackers@postgresql.org)
To make changes to your subscription:
http://www.postgresql.org/mailpref/pgsql-hackers
