Re: pgsql: Add documentation for the JIT feature.

On 2018-03-29 15:00:36 -0400, Stephen Frost wrote:
> Greetings,
>
> * Andres Freund (andres(at)anarazel(dot)de) wrote:
> > On 2018-03-29 13:26:31 -0400, Robert Haas wrote:
> > > On Thu, Mar 29, 2018 at 9:44 AM, Tom Lane <tgl(at)sss(dot)pgh(dot)pa(dot)us> wrote:
> > > > I'd go a little further and drop "JIT" from user-facing documentation
> > > > altogether. Instead refer to the feature as "compilation of expressions"
> > > > or some such. JIT is just jargon. Plus, the timing of the compilation is
> > > > actually the least important property for our purpose.
> > >
> > > I agree that talking about JIT compilation (or just-in-time
> > > compilation) would be better than talking just about JIT, but refusing
> > > to mention JIT seems counter-productive to me. There are a lot of
> > > people who know what just-in-time compilation is and will not realize
> > > that "compilation of expressions" refers to any such technology. If
> > > you don't know what it is, you can Google it. Just typing "jit" into
> > > Google produces a stupid urban dictionary hit and then this:
> > > https://en.wikipedia.org/wiki/Just-in-time_compilation -- and that
> > > contains useful information that you'll never find if you search for
> > > "compilation of expressions".
> > >
> > > Also, in a way, you could argue that v10 already did "compilation of
> > > expressions". It didn't compile them to machine language, true, but
> > > it translated them into a form which is faster to execute, and which
> > > is at least arguably a form of bytecode. It's not going to be clear,
> > > even to an expert, that "compilation of expressions" means something
> > > other than that, but if you say JIT, then all of a sudden people know
> > > what we're talking about.
> > >
> > > I agree that JIT is jargon, but it's pretty commonly-used jargon.
> >
> > Precisely this. I'm very strongly against just saying "expression
> > compilation", it's just too imprecise. As Robert mentions it could refer
> > to what we do in v10, it could refer to ahead of time compilation of PL
> > functions, and it doesn't include compiling tuple deforming. Nor will
> > it describe compiling sorting, copy or whatnot.
> >
> > I'm very open however to replacing JITing with JIT compiling and smilar
> > substitutions.
>
> What we've done elsewhere when there's been similar jargon is to say
> something along the lines of:
>
> "compiling of routines (also known as Just-In-Time or JIT compilation)"

There's an entire section explaining what JIT is and what we currently
can JIT. We can't just say "compiling of routines (also ...)", because
a) we don't do that. b) even if you take expressions being JIT compiled
as that, we also JIT compile tuple deforming. And hopefully will JIT
further things in the not too far away future.

The general config.sgml references and such read
Sets the planner's cutoff above which JIT compilation is used as part
of query execution (see <xref linkend="jit"/>). Performing
<acronym>JIT</acronym> costs time but can accelerate query execution.
it's not used in a standalone manner without references.

and the jit specific section starts with:
<para>
Just-in-time compilation (<acronym>JIT</acronym>) is the process of turning
some form of interpreted program evaluation into a native program, and
doing so at runtime.

For example, instead of using a facility that can evaluate arbitrary SQL
expressions to evaluate an SQL predicate like <literal>WHERE a.col =
3</literal>, it is possible to generate a function than can be natively
executed by the CPU that just handles that expression, yielding a speedup.
</para>

and continues a bit later with
<sect2 id="jit-accelerated-operations">
<title><acronym>JIT</acronym> Accelerated Operations</title>
<para>
Currently <productname>PostgreSQL</productname>'s <acronym>JIT</acronym>
implementation has support for accelerating expression evaluation and
tuple deforming. Several other operations could be accelerated in the
future.
</para>
<para>
Expression evaluation is used to evaluate <literal>WHERE</literal>
clauses, target lists, aggregates and projections. It can be accelerated
by generating code specific to each case.
</para>
<para>
Tuple deforming is the process of transforming an on-disk tuple (see <xref
linkend="heaptuple"/>) into its in-memory representation. It can be
accelerated by creating a function specific to the table layout and the
number of columns to be extracted.
</para>
</sect2>

I think there's a few references to standalone JIT that deserve to be
replaced with JIT compilation and similar.

Greetings,

Andres Freund