Skip to content

P
Postgres FD Implementation
Commit e6c039d1 authored by Andres Freund's avatar Andres Freund
Browse files
Options

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
parent 1f0c6a9e
Expand all Hide whitespace changes
Inline Side-by-side
Showing with 844 additions and 2 deletions
doc/src/sgml/acronyms.sgml
View file @ e6c039d1
......@@ -369,6 +369,16 @@
</listitem>
</varlistentry>
<varlistentry>
<term><acronym>JIT</acronym></term>
<listitem>
<para>
<ulink url="https://en.wikipedia.org/wiki/Just-in-time_compilation">Just-in-Time
compilation</ulink>
</para>
</listitem>
</varlistentry>
<varlistentry>
<term><acronym>JSON</acronym></term>
<listitem>
......
doc/src/sgml/config.sgml
View file @ e6c039d1
......@@ -4136,6 +4136,62 @@ ANY <replaceable class="parameter">num_sync</replaceable> ( <replaceable class="
</listitem>
</varlistentry>
<varlistentry id="guc-jit-above-cost" xreflabel="jit_above_cost">
<term><varname>jit_above_cost</varname> (<type>floating point</type>)
<indexterm>
<primary><varname>jit_above_cost</varname> configuration parameter</primary>
</indexterm>
</term>
<listitem>
<para>
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.
The default is <literal>100000</literal>.
</para>
</listitem>
</varlistentry>
<varlistentry id="guc-jit-optimize-above-cost" xreflabel="jit_optimize_above_cost">
<term><varname>jit_optimize_above_cost</varname> (<type>floating point</type>)
<indexterm>
<primary><varname>jit_optimize_above_cost</varname> configuration parameter</primary>
</indexterm>
</term>
<listitem>
<para>
Sets the planner's cutoff above which JIT compiled programs (see <xref
linkend="guc-jit-above-cost"/>) are optimized. Optimization initially
takes time, but can improve execution speed. It is not meaningful to
set this to a lower value than <xref linkend="guc-jit-above-cost"/>.
The default is <literal>500000</literal>.
</para>
</listitem>
</varlistentry>
<varlistentry id="guc-jit-inline-above-cost" xreflabel="jit_inline_above_cost">
<term><varname>jit_inline_above_cost</varname> (<type>floating point</type>)
<indexterm>
<primary><varname>jit_inline_above_cost</varname> configuration parameter</primary>
</indexterm>
</term>
<listitem>
<para>
Sets the planner's cutoff above which JIT compiled programs (see <xref
linkend="guc-jit-above-cost"/>) attempt to inline functions and
operators. Inlining initially takes time, but can improve execution
speed. It is unlikely to be beneficial to set
<varname>jit_inline_above_cost</varname> below
<varname>jit_optimize_above_cost</varname>.
The default is <literal>500000</literal>.
</para>
</listitem>
</varlistentry>
</variablelist>
</sect2>
......@@ -4418,6 +4474,23 @@ SELECT * FROM parent WHERE key = 2400;
</listitem>
</varlistentry>
<varlistentry id="guc-jit" xreflabel="jit">
<term><varname>jit</varname> (<type>boolean</type>)
<indexterm>
<primary><varname>jit</varname> configuration parameter</primary>
</indexterm>
</term>
<listitem>
<para>
Determines whether <acronym>JIT</acronym> may be used by
<productname>PostgreSQL</productname>, if available (see <xref
linkend="jit"/>).
The default is <literal>on</literal>.
</para>
</listitem>
</varlistentry>
<varlistentry id="guc-join-collapse-limit" xreflabel="join_collapse_limit">
<term><varname>join_collapse_limit</varname> (<type>integer</type>)
<indexterm>
......@@ -7412,6 +7485,29 @@ SET XML OPTION { DOCUMENT | CONTENT };
</note>
</listitem>
</varlistentry>
<varlistentry id="guc-jit-provider" xreflabel="jit_provider">
<term><varname>jit_provider</varname> (<type>string</type>)
<indexterm>
<primary><varname>jit_provider</varname> configuration parameter</primary>
</indexterm>
</term>
<listitem>
<para>
Determines which JIT provider (see <xref linkend="jit-extensibility"/>) is
used. The built-in default is <literal>llvmjit</literal>.
</para>
<para>
If set to a non-existent library <acronym>JIT</acronym> will not
available, but no error will be raised. This allows JIT support to be
installed separately from the main
<productname>PostgreSQL</productname> package.
This parameter can only be set at server start.
</para>
</listitem>
</varlistentry>
</variablelist>
</sect2>
......@@ -8658,7 +8754,92 @@ LOG: CleanUpLock: deleting: lock(0xb7acd844) id(24688,24696,0,0,0,1)
</para>
</listitem>
</varlistentry>
</variablelist>
<varlistentry id="guc-jit-debugging-support" xreflabel="jit_debugging_support">
<term><varname>jit_debugging_support</varname> (<type>boolean</type>)
<indexterm>
<primary><varname>jit_debugging_support</varname> configuration parameter</primary>
</indexterm>
</term>
<listitem>
<para>
If LLVM has the required functionality, register generated functions
with <productname>GDB</productname>. This makes debugging easier.
The default setting is <literal>off</literal>, and can only be set at
server start.
</para>
</listitem>
</varlistentry>
<varlistentry id="guc-jit-dump-bitcode" xreflabel="jit_dump_bitcode">
<term><varname>jit_dump_bitcode</varname> (<type>boolean</type>)
<indexterm>
<primary><varname>jit_dump_bitcode</varname> configuration parameter</primary>
</indexterm>
</term>
<listitem>
<para>
Writes the generated <productname>LLVM</productname> IR out to the
filesystem, inside <xref linkend="guc-data-directory"/>. This is only
useful for working on the internals of the JIT implementation.
The default setting is <literal>off</literal>, and it can only be
changed by a superuser.
</para>
</listitem>
</varlistentry>
<varlistentry id="guc-jit-expressions" xreflabel="jit_expressions">
<term><varname>jit_expressions</varname> (<type>boolean</type>)
<indexterm>
<primary><varname>jit_expressions</varname> configuration parameter</primary>
</indexterm>
</term>
<listitem>
<para>
Determines whether expressions are JIT compiled, subject to costing
decisions (see <xref linkend="jit-decision"/>). The default is
<literal>on</literal>.
</para>
</listitem>
</varlistentry>
<varlistentry id="guc-jit-profiling-support" xreflabel="jit_profiling_support">
<term><varname>jit_profiling_support</varname> (<type>boolean</type>)
<indexterm>
<primary><varname>jit_profiling_support</varname> configuration parameter</primary>
</indexterm>
</term>
<listitem>
<para>
If LLVM has the required functionality, emit required data to allow
<productname>perf</productname> to profile functions generated by JIT.
This writes out files to <filename>$HOME/.debug/jit/</filename>; the
user is responsible for performing cleanup when desired.
The default setting is <literal>off</literal>, and can only be set at
server start.
</para>
</listitem>
</varlistentry>
<varlistentry id="guc-jit-tuple-deforming" xreflabel="jit_tuple_deforming">
<term><varname>jit_tuple_deforming</varname> (<type>boolean</type>)
<indexterm>
<primary><varname>jit_tuple_deforming</varname> configuration parameter</primary>
</indexterm>
</term>
<listitem>
<para>
Determines whether tuple deforming is JIT compiled, subject to costing
decisions (see <xref linkend="jit-decision"/>). The default is
<literal>on</literal>.
</para>
</listitem>
</varlistentry>
</variablelist>
</sect1>
<sect1 id="runtime-config-short">
<title>Short Options</title>
......
doc/src/sgml/filelist.sgml
View file @ e6c039d1
......@@ -48,6 +48,7 @@
<!ENTITY user-manag SYSTEM "user-manag.sgml">
<!ENTITY wal SYSTEM "wal.sgml">
<!ENTITY logical-replication SYSTEM "logical-replication.sgml">
<!ENTITY jit SYSTEM "jit.sgml">
<!-- programmer's guide -->
<!ENTITY bgworker SYSTEM "bgworker.sgml">
......
doc/src/sgml/func.sgml
View file @ e6c039d1
......@@ -15942,6 +15942,14 @@ SELECT * FROM pg_ls_dir('.') WITH ORDINALITY AS t(ls,n);
<entry>is schema another session's temporary schema?</entry>
</row>
<row>
<entry><literal><function>pg_jit_available()</function></literal></entry>
<entry><type>boolean</type></entry>
<entry>is <acronym>JIT</acronym> available in this session (see <xref
linkend="jit"/>)? Returns <literal>false</literal> if <xref
linkend="guc-jit"/> is set to false.</entry>
</row>
<row>
<entry><literal><function>pg_listening_channels()</function></literal></entry>
<entry><type>setof text</type></entry>
......
doc/src/sgml/installation.sgml
View file @ e6c039d1
......@@ -758,6 +758,39 @@ su - postgres
</listitem>
</varlistentry>
<varlistentry id="configure-with-llvm">
<term><option>--with-llvm</option></term>
<listitem>
<para>
Build with support for <productname>LLVM</productname> based
<acronym>JIT</acronym> compilation (see <xref linkend="jit"/>). This
requires the <productname>LLVM</productname> library to be installed.
The minimum required version of <productname>LLVM</productname> is
currently 3.9.
</para>
<para>
<command>llvm-config</command><indexterm><primary>llvm-config</primary></indexterm>
will be used to find the required compilation options.
<command>llvm-config</command>, and then
<command>llvm-config-$major-$minor</command> for all supported
versions, will be searched on <envar>PATH</envar>. If that would not
yield the correct binary, use <envar>LLVM_CONFIG</envar> to specify a
path to the correct <command>llvm-config</command>. For example
<programlisting>
./configure ... --with-llvm LLVM_CONFIG='/path/to/llvm/bin/llvm-config'
</programlisting>
</para>
<para>
<productname>LLVM</productname> support requires a compatible
<command>clang</command> compiler (specified, if necessary, using the
<envar>CLANG</envar> environment variable), and a working C++
compiler (specified, if necessary, using the <envar>CXX</envar>
environment variable).
</para>
</listitem>
</varlistentry>
<varlistentry>
<term><option>--with-icu</option></term>
<listitem>
......@@ -1342,6 +1375,16 @@ su - postgres
</listitem>
</varlistentry>
<varlistentry>
<term><envar>CLANG</envar></term>
<listitem>
<para>
path to <command>clang</command> program used to process source code
for inlining when compiling with <literal>--with-llvm</literal>
</para>
</listitem>
</varlistentry>
<varlistentry>
<term><envar>CPP</envar></term>
<listitem>
......@@ -1432,6 +1475,16 @@ su - postgres
</listitem>
</varlistentry>
<varlistentry>
<term><envar>LLVM_CONFIG</envar></term>
<listitem>
<para>
<command>llvm-config</command> program used to locate the
<productname>LLVM</productname> installation.
</para>
</listitem>
</varlistentry>
<varlistentry>
<term><envar>MSGFMT</envar></term>
<listitem>
......
doc/src/sgml/jit.sgml 0 → 100644
View file @ e6c039d1
This diff is collapsed.
doc/src/sgml/postgres.sgml
View file @ e6c039d1
......@@ -163,6 +163,7 @@
&diskusage;
&wal;
&logical-replication;
&jit;
&regress;
</part>
......
doc/src/sgml/storage.sgml
View file @ e6c039d1
......@@ -875,7 +875,7 @@ data. Empty in ordinary tables.</entry>
<filename>src/include/storage/bufpage.h</filename>.
</para>
<para>
<para id="heaptuple">
Following the page header are item identifiers
(<type>ItemIdData</type>), each requiring four bytes.
......
src/backend/jit/README 0 → 100644
View file @ e6c039d1
This diff is collapsed.
Markdown is supported
0% or
You are about to add 0 people to the discussion. Proceed with caution.
Finish editing this message first!
Please register or to comment