Skip to content

Commit e6c039d

Browse files
anarazelanarazel
committed
Add documentation for the JIT feature.
As promised in earlier commits, this adds documentation about the new build options, the new GUCs, about the planner logic when JIT is used, and the benefits of JIT in general. Also adds a more implementation oriented README. I'm sure we're going to want to expand this further, but I think this is a reasonable start. Author: Andres Freund, with contributions by Thomas Munro Reviewed-By: Thomas Munro Discussion: https://postgr.es/m/20170901064131.tazjxwus3k2w3ybh@alap3.anarazel.de
1 parent 1f0c6a9 commit e6c039d

File tree

9 files changed

+844
-2
lines changed

9 files changed

+844
-2
lines changed

‎doc/src/sgml/acronyms.sgml‎

Lines changed: 10 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -369,6 +369,16 @@
369369
</listitem>
370370
</varlistentry>
371371

372+
<varlistentry>
373+
<term><acronym>JIT</acronym></term>
374+
<listitem>
375+
<para>
376+
<ulink url="https://en.wikipedia.org/wiki/Just-in-time_compilation">Just-in-Time
377+
compilation</ulink>
378+
</para>
379+
</listitem>
380+
</varlistentry>
381+
372382
<varlistentry>
373383
<term><acronym>JSON</acronym></term>
374384
<listitem>

‎doc/src/sgml/config.sgml‎

Lines changed: 182 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -4136,6 +4136,62 @@ ANY <replaceable class="parameter">num_sync</replaceable> ( <replaceable class="
41364136
</listitem>
41374137
</varlistentry>
41384138

4139+
4140+
<varlistentry id="guc-jit-above-cost" xreflabel="jit_above_cost">
4141+
<term><varname>jit_above_cost</varname> (<type>floating point</type>)
4142+
<indexterm>
4143+
<primary><varname>jit_above_cost</varname> configuration parameter</primary>
4144+
</indexterm>
4145+
</term>
4146+
<listitem>
4147+
<para>
4148+
Sets the planner's cutoff above which JIT compilation is used as part
4149+
of query execution (see <xref linkend="jit"/>). Performing
4150+
<acronym>JIT</acronym> costs time but can accelerate query execution.
4151+
4152+
The default is <literal>100000</literal>.
4153+
</para>
4154+
</listitem>
4155+
</varlistentry>
4156+
4157+
<varlistentry id="guc-jit-optimize-above-cost" xreflabel="jit_optimize_above_cost">
4158+
<term><varname>jit_optimize_above_cost</varname> (<type>floating point</type>)
4159+
<indexterm>
4160+
<primary><varname>jit_optimize_above_cost</varname> configuration parameter</primary>
4161+
</indexterm>
4162+
</term>
4163+
<listitem>
4164+
<para>
4165+
Sets the planner's cutoff above which JIT compiled programs (see <xref
4166+
linkend="guc-jit-above-cost"/>) are optimized. Optimization initially
4167+
takes time, but can improve execution speed. It is not meaningful to
4168+
set this to a lower value than <xref linkend="guc-jit-above-cost"/>.
4169+
4170+
The default is <literal>500000</literal>.
4171+
</para>
4172+
</listitem>
4173+
</varlistentry>
4174+
4175+
<varlistentry id="guc-jit-inline-above-cost" xreflabel="jit_inline_above_cost">
4176+
<term><varname>jit_inline_above_cost</varname> (<type>floating point</type>)
4177+
<indexterm>
4178+
<primary><varname>jit_inline_above_cost</varname> configuration parameter</primary>
4179+
</indexterm>
4180+
</term>
4181+
<listitem>
4182+
<para>
4183+
Sets the planner's cutoff above which JIT compiled programs (see <xref
4184+
linkend="guc-jit-above-cost"/>) attempt to inline functions and
4185+
operators. Inlining initially takes time, but can improve execution
4186+
speed. It is unlikely to be beneficial to set
4187+
<varname>jit_inline_above_cost</varname> below
4188+
<varname>jit_optimize_above_cost</varname>.
4189+
4190+
The default is <literal>500000</literal>.
4191+
</para>
4192+
</listitem>
4193+
</varlistentry>
4194+
41394195
</variablelist>
41404196

41414197
</sect2>
@@ -4418,6 +4474,23 @@ SELECT * FROM parent WHERE key = 2400;
44184474
</listitem>
44194475
</varlistentry>
44204476

4477+
<varlistentry id="guc-jit" xreflabel="jit">
4478+
<term><varname>jit</varname> (<type>boolean</type>)
4479+
<indexterm>
4480+
<primary><varname>jit</varname> configuration parameter</primary>
4481+
</indexterm>
4482+
</term>
4483+
<listitem>
4484+
<para>
4485+
Determines whether <acronym>JIT</acronym> may be used by
4486+
<productname>PostgreSQL</productname>, if available (see <xref
4487+
linkend="jit"/>).
4488+
4489+
The default is <literal>on</literal>.
4490+
</para>
4491+
</listitem>
4492+
</varlistentry>
4493+
44214494
<varlistentry id="guc-join-collapse-limit" xreflabel="join_collapse_limit">
44224495
<term><varname>join_collapse_limit</varname> (<type>integer</type>)
44234496
<indexterm>
@@ -7412,6 +7485,29 @@ SET XML OPTION { DOCUMENT | CONTENT };
74127485
</note>
74137486
</listitem>
74147487
</varlistentry>
7488+
7489+
<varlistentry id="guc-jit-provider" xreflabel="jit_provider">
7490+
<term><varname>jit_provider</varname> (<type>string</type>)
7491+
<indexterm>
7492+
<primary><varname>jit_provider</varname> configuration parameter</primary>
7493+
</indexterm>
7494+
</term>
7495+
<listitem>
7496+
<para>
7497+
Determines which JIT provider (see <xref linkend="jit-extensibility"/>) is
7498+
used. The built-in default is <literal>llvmjit</literal>.
7499+
</para>
7500+
<para>
7501+
If set to a non-existent library <acronym>JIT</acronym> will not
7502+
available, but no error will be raised. This allows JIT support to be
7503+
installed separately from the main
7504+
<productname>PostgreSQL</productname> package.
7505+
7506+
This parameter can only be set at server start.
7507+
</para>
7508+
</listitem>
7509+
</varlistentry>
7510+
74157511
</variablelist>
74167512
</sect2>
74177513

@@ -8658,7 +8754,92 @@ LOG: CleanUpLock: deleting: lock(0xb7acd844) id(24688,24696,0,0,0,1)
86588754
</para>
86598755
</listitem>
86608756
</varlistentry>
8661-
</variablelist>
8757+
8758+
<varlistentry id="guc-jit-debugging-support" xreflabel="jit_debugging_support">
8759+
<term><varname>jit_debugging_support</varname> (<type>boolean</type>)
8760+
<indexterm>
8761+
<primary><varname>jit_debugging_support</varname> configuration parameter</primary>
8762+
</indexterm>
8763+
</term>
8764+
<listitem>
8765+
<para>
8766+
If LLVM has the required functionality, register generated functions
8767+
with <productname>GDB</productname>. This makes debugging easier.
8768+
8769+
The default setting is <literal>off</literal>, and can only be set at
8770+
server start.
8771+
</para>
8772+
</listitem>
8773+
</varlistentry>
8774+
8775+
<varlistentry id="guc-jit-dump-bitcode" xreflabel="jit_dump_bitcode">
8776+
<term><varname>jit_dump_bitcode</varname> (<type>boolean</type>)
8777+
<indexterm>
8778+
<primary><varname>jit_dump_bitcode</varname> configuration parameter</primary>
8779+
</indexterm>
8780+
</term>
8781+
<listitem>
8782+
<para>
8783+
Writes the generated <productname>LLVM</productname> IR out to the
8784+
filesystem, inside <xref linkend="guc-data-directory"/>. This is only
8785+
useful for working on the internals of the JIT implementation.
8786+
8787+
The default setting is <literal>off</literal>, and it can only be
8788+
changed by a superuser.
8789+
</para>
8790+
</listitem>
8791+
</varlistentry>
8792+
8793+
<varlistentry id="guc-jit-expressions" xreflabel="jit_expressions">
8794+
<term><varname>jit_expressions</varname> (<type>boolean</type>)
8795+
<indexterm>
8796+
<primary><varname>jit_expressions</varname> configuration parameter</primary>
8797+
</indexterm>
8798+
</term>
8799+
<listitem>
8800+
<para>
8801+
Determines whether expressions are JIT compiled, subject to costing
8802+
decisions (see <xref linkend="jit-decision"/>). The default is
8803+
<literal>on</literal>.
8804+
</para>
8805+
</listitem>
8806+
</varlistentry>
8807+
8808+
<varlistentry id="guc-jit-profiling-support" xreflabel="jit_profiling_support">
8809+
<term><varname>jit_profiling_support</varname> (<type>boolean</type>)
8810+
<indexterm>
8811+
<primary><varname>jit_profiling_support</varname> configuration parameter</primary>
8812+
</indexterm>
8813+
</term>
8814+
<listitem>
8815+
<para>
8816+
If LLVM has the required functionality, emit required data to allow
8817+
<productname>perf</productname> to profile functions generated by JIT.
8818+
This writes out files to <filename>$HOME/.debug/jit/</filename>; the
8819+
user is responsible for performing cleanup when desired.
8820+
8821+
The default setting is <literal>off</literal>, and can only be set at
8822+
server start.
8823+
</para>
8824+
</listitem>
8825+
</varlistentry>
8826+
8827+
<varlistentry id="guc-jit-tuple-deforming" xreflabel="jit_tuple_deforming">
8828+
<term><varname>jit_tuple_deforming</varname> (<type>boolean</type>)
8829+
<indexterm>
8830+
<primary><varname>jit_tuple_deforming</varname> configuration parameter</primary>
8831+
</indexterm>
8832+
</term>
8833+
<listitem>
8834+
<para>
8835+
Determines whether tuple deforming is JIT compiled, subject to costing
8836+
decisions (see <xref linkend="jit-decision"/>). The default is
8837+
<literal>on</literal>.
8838+
</para>
8839+
</listitem>
8840+
</varlistentry>
8841+
8842+
</variablelist>
86628843
</sect1>
86638844
<sect1 id="runtime-config-short">
86648845
<title>Short Options</title>

‎doc/src/sgml/filelist.sgml‎

Lines changed: 1 addition & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -48,6 +48,7 @@
4848
<!ENTITY user-manag SYSTEM "user-manag.sgml">
4949
<!ENTITY wal SYSTEM "wal.sgml">
5050
<!ENTITY logical-replication SYSTEM "logical-replication.sgml">
51+
<!ENTITY jit SYSTEM "jit.sgml">
5152

5253
<!-- programmer's guide -->
5354
<!ENTITY bgworker SYSTEM "bgworker.sgml">

‎doc/src/sgml/func.sgml‎

Lines changed: 8 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -15942,6 +15942,14 @@ SELECT * FROM pg_ls_dir('.') WITH ORDINALITY AS t(ls,n);
1594215942
<entry>is schema another session's temporary schema?</entry>
1594315943
</row>
1594415944

15945+
<row>
15946+
<entry><literal><function>pg_jit_available()</function></literal></entry>
15947+
<entry><type>boolean</type></entry>
15948+
<entry>is <acronym>JIT</acronym> available in this session (see <xref
15949+
linkend="jit"/>)? Returns <literal>false</literal> if <xref
15950+
linkend="guc-jit"/> is set to false.</entry>
15951+
</row>
15952+
1594515953
<row>
1594615954
<entry><literal><function>pg_listening_channels()</function></literal></entry>
1594715955
<entry><type>setof text</type></entry>

‎doc/src/sgml/installation.sgml‎

Lines changed: 53 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -758,6 +758,39 @@ su - postgres
758758
</listitem>
759759
</varlistentry>
760760

761+
<varlistentry id="configure-with-llvm">
762+
<term><option>--with-llvm</option></term>
763+
<listitem>
764+
<para>
765+
Build with support for <productname>LLVM</productname> based
766+
<acronym>JIT</acronym> compilation (see <xref linkend="jit"/>). This
767+
requires the <productname>LLVM</productname> library to be installed.
768+
The minimum required version of <productname>LLVM</productname> is
769+
currently 3.9.
770+
</para>
771+
<para>
772+
<command>llvm-config</command><indexterm><primary>llvm-config</primary></indexterm>
773+
will be used to find the required compilation options.
774+
<command>llvm-config</command>, and then
775+
<command>llvm-config-$major-$minor</command> for all supported
776+
versions, will be searched on <envar>PATH</envar>. If that would not
777+
yield the correct binary, use <envar>LLVM_CONFIG</envar> to specify a
778+
path to the correct <command>llvm-config</command>. For example
779+
<programlisting>
780+
./configure ... --with-llvm LLVM_CONFIG='/path/to/llvm/bin/llvm-config'
781+
</programlisting>
782+
</para>
783+
784+
<para>
785+
<productname>LLVM</productname> support requires a compatible
786+
<command>clang</command> compiler (specified, if necessary, using the
787+
<envar>CLANG</envar> environment variable), and a working C++
788+
compiler (specified, if necessary, using the <envar>CXX</envar>
789+
environment variable).
790+
</para>
791+
</listitem>
792+
</varlistentry>
793+
761794
<varlistentry>
762795
<term><option>--with-icu</option></term>
763796
<listitem>
@@ -1342,6 +1375,16 @@ su - postgres
13421375
</listitem>
13431376
</varlistentry>
13441377

1378+
<varlistentry>
1379+
<term><envar>CLANG</envar></term>
1380+
<listitem>
1381+
<para>
1382+
path to <command>clang</command> program used to process source code
1383+
for inlining when compiling with <literal>--with-llvm</literal>
1384+
</para>
1385+
</listitem>
1386+
</varlistentry>
1387+
13451388
<varlistentry>
13461389
<term><envar>CPP</envar></term>
13471390
<listitem>
@@ -1432,6 +1475,16 @@ su - postgres
14321475
</listitem>
14331476
</varlistentry>
14341477

1478+
<varlistentry>
1479+
<term><envar>LLVM_CONFIG</envar></term>
1480+
<listitem>
1481+
<para>
1482+
<command>llvm-config</command> program used to locate the
1483+
<productname>LLVM</productname> installation.
1484+
</para>
1485+
</listitem>
1486+
</varlistentry>
1487+
14351488
<varlistentry>
14361489
<term><envar>MSGFMT</envar></term>
14371490
<listitem>

0 commit comments

Comments
 (0)