Обсуждение: pgsql: Add documentation for the JIT feature.
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 Branch ------ master Details ------- https://git.postgresql.org/pg/commitdiff/e6c039d13e16a3a2dec5ba479d9d1fb3229c03a3 Modified Files -------------- doc/src/sgml/acronyms.sgml | 10 ++ doc/src/sgml/config.sgml | 183 ++++++++++++++++++++++++- doc/src/sgml/filelist.sgml | 1 + doc/src/sgml/func.sgml | 8 ++ doc/src/sgml/installation.sgml | 53 ++++++++ doc/src/sgml/jit.sgml | 299 +++++++++++++++++++++++++++++++++++++++++ doc/src/sgml/postgres.sgml | 1 + doc/src/sgml/storage.sgml | 2 +- src/backend/jit/README | 289 +++++++++++++++++++++++++++++++++++++++ 9 files changed, 844 insertions(+), 2 deletions(-)
On 28 March 2018 at 22:23, Andres Freund <andres@anarazel.de> wrote: > Add documentation for the JIT feature. Very nice feature and most welcome but we should call it something other than just "JIT" JIT means Just In Time, which could be applied to many concepts and has been in use for many years in a range of concepts. particularly in manufacturing/logistics and project management. The feature is JIT compilation, not just "JIT". If we had replication with eager consensus, it would be silly to call the feature simply "eager" with no other qualifier. Thanks -- Simon Riggs http://www.2ndQuadrant.com/ PostgreSQL Development, 24x7 Support, Remote DBA, Training & Services
Andres Freund <andres@anarazel.de> writes:
> Add documentation for the JIT feature.
guaibausaurus complains that this broke tarball building:
make -C postgresql-11devel/doc/src/sgml/ INSTALL
make[1]: Entering directory '/home/pgsql/buildfarm/buildroot/HEAD/pgsql.build/postgresql-11devel/doc/src/sgml'
/usr/bin/xsltproc --path . --stringparam pg.version '11devel' --xinclude standalone-profile.xsl standalone-install.xml
>INSTALL.xml
/usr/bin/xmllint --noout --valid INSTALL.xml
INSTALL.xml:721: element xref: validity error : IDREF attribute linkend references an unknown ID "jit"
Makefile:115: recipe for target 'INSTALL.html' failed
make[1]: *** [INSTALL.html] Error 4
I'd guess you put a link into installation.sgml that can't be there.
regards, tom lane
On 2018-03-29 01:10:46 -0400, Tom Lane wrote: > Andres Freund <andres@anarazel.de> writes: > > Add documentation for the JIT feature. > > guaibausaurus complains that this broke tarball building: > > make -C postgresql-11devel/doc/src/sgml/ INSTALL > make[1]: Entering directory '/home/pgsql/buildfarm/buildroot/HEAD/pgsql.build/postgresql-11devel/doc/src/sgml' > /usr/bin/xsltproc --path . --stringparam pg.version '11devel' --xinclude standalone-profile.xsl standalone-install.xml>INSTALL.xml > /usr/bin/xmllint --noout --valid INSTALL.xml > INSTALL.xml:721: element xref: validity error : IDREF attribute linkend references an unknown ID "jit" > Makefile:115: recipe for target 'INSTALL.html' failed > make[1]: *** [INSTALL.html] Error 4 > > I'd guess you put a link into installation.sgml that can't be there. Thanks for noticing, and thanks Bruce for fixing. Could we add INSTALL to the all target in src/docs/sgml? It's a bit awkward that one can build the docs and miss such a mistake. It's fast to build in comparison to the rest of the docs, so that doesn't seem like a high price? Greetings, Andres Freund
Andres Freund wrote: > Could we add INSTALL to the all target in src/docs/sgml? It's a bit > awkward that one can build the docs and miss such a mistake. It's fast > to build in comparison to the rest of the docs, so that doesn't seem > like a high price? Maybe it can be tested for in "make check"? That's probably even faster. -- Álvaro Herrera https://www.2ndQuadrant.com/ PostgreSQL Development, 24x7 Support, Remote DBA, Training & Services
Hi, On 2018-03-29 15:20:58 -0300, Alvaro Herrera wrote: > Andres Freund wrote: > > > Could we add INSTALL to the all target in src/docs/sgml? It's a bit > > awkward that one can build the docs and miss such a mistake. It's fast > > to build in comparison to the rest of the docs, so that doesn't seem > > like a high price? > > Maybe it can be tested for in "make check"? That's probably even > faster. Hm, what's wrong just doing it in the normal build? It's a desired build artifact, so I really don't see any argument for not building it by default? Don't quite see what the advantage of doing it during make check would be? Greetings, Andres Freund
Andres Freund wrote: > Hi, > > On 2018-03-29 15:20:58 -0300, Alvaro Herrera wrote: > > Andres Freund wrote: > > > > > Could we add INSTALL to the all target in src/docs/sgml? It's a bit > > > awkward that one can build the docs and miss such a mistake. It's fast > > > to build in comparison to the rest of the docs, so that doesn't seem > > > like a high price? > > > > Maybe it can be tested for in "make check"? That's probably even > > faster. > > Hm, what's wrong just doing it in the normal build? It's a desired build > artifact, so I really don't see any argument for not building it by > default? Don't quite see what the advantage of doing it during make > check would be? I meant running something that would check that the file compiles, without actually producing the output. For the regular docs, there's a couple of orders of magnitude of difference in time to do the check vs. the actual build. It takes 1.2 second to build for me FWIW, so it's not like it's a huge time waste anyhow. Probably more than what will ever be saved has already been spent in this conversation :-) -- Álvaro Herrera https://www.2ndQuadrant.com/ PostgreSQL Development, 24x7 Support, Remote DBA, Training & Services
On 3/29/18 14:43, Alvaro Herrera wrote: >> Hm, what's wrong just doing it in the normal build? It's a desired build >> artifact, so I really don't see any argument for not building it by >> default? Don't quite see what the advantage of doing it during make >> check would be? > I meant running something that would check that the file compiles, > without actually producing the output. For the regular docs, there's a > couple of orders of magnitude of difference in time to do the check vs. > the actual build. Or we do both. -- Peter Eisentraut http://www.2ndQuadrant.com/ PostgreSQL Development, 24x7 Support, Remote DBA, Training & Services
Peter Eisentraut <peter.eisentraut@2ndquadrant.com> writes:
> On 3/29/18 14:43, Alvaro Herrera wrote:
>>> Hm, what's wrong just doing it in the normal build? It's a desired build
>>> artifact, so I really don't see any argument for not building it by
>>> default? Don't quite see what the advantage of doing it during make
>>> check would be?
>> I meant running something that would check that the file compiles,
>> without actually producing the output. For the regular docs, there's a
>> couple of orders of magnitude of difference in time to do the check vs.
>> the actual build.
> Or we do both.
I'm OK with adding INSTALL to the default build target in doc/src/sgml;
the incremental cost isn't large and we now realize there'd be useful
error detection. I'm *not* OK with expanding the scope of "make check"
to include building the documentation. It's never had anything to do
with docs before and I see no reason to start now. Personally, when
I'm working on a patch, the doc updates if any are a completely separate
matter. I don't want to waste cycles on testing docs when I'm trying
to test code, any more than I would like the reverse (ie forcing a docs
build to build code too).
regards, tom lane
On March 31, 2018 8:43:37 AM PDT, Tom Lane <tgl@sss.pgh.pa.us> wrote: >Peter Eisentraut <peter.eisentraut@2ndquadrant.com> writes: >> On 3/29/18 14:43, Alvaro Herrera wrote: > I'm *not* OK with expanding the scope of "make check" >to include building the documentation. It's never had anything to do >with docs before and I see no reason to start now. Personally, when >I'm working on a patch, the doc updates if any are a completely >separate >matter. I don't want to waste cycles on testing docs when I'm trying >to test code, any more than I would like the reverse (ie forcing a docs >build to build code too). They're a local check target in the docs directory. But it just checks postgres.xml, not additional targets. Don't thinkanybody proposed to add the doc check to the top-level check target. Andres -- Sent from my Android device with K-9 Mail. Please excuse my brevity.
Andres Freund <andres@anarazel.de> writes:
> On March 31, 2018 8:43:37 AM PDT, Tom Lane <tgl@sss.pgh.pa.us> wrote:
>> I don't want to waste cycles on testing docs when I'm trying
>> to test code, any more than I would like the reverse (ie forcing a docs
>> build to build code too).
> They're a local check target in the docs directory. But it just checks
> postgres.xml, not additional targets. Don't think anybody proposed to
> add the doc check to the top-level check target.
Ah, didn't realize that "make check" in the docs isn't connected up to
the main check target. As long as that's true, no objection.
regards, tom lane
Tom Lane wrote: > Andres Freund <andres@anarazel.de> writes: > > On March 31, 2018 8:43:37 AM PDT, Tom Lane <tgl@sss.pgh.pa.us> wrote: > >> I don't want to waste cycles on testing docs when I'm trying > >> to test code, any more than I would like the reverse (ie forcing a docs > >> build to build code too). > > > They're a local check target in the docs directory. But it just checks > > postgres.xml, not additional targets. Don't think anybody proposed to > > add the doc check to the top-level check target. > > Ah, didn't realize that "make check" in the docs isn't connected up to > the main check target. As long as that's true, no objection. I'm not proposing to add doc/src/sgml's check target to top-level check, though perhaps it wouldn't be such a terrible idea -- seems quick enough, at under half a second: $ time LC_ALL=C make -C doc/src/sgml/ check make: Entering directory '/home/alvherre/Code/pgsql/build/master/doc/src/sgml' /usr/bin/xmllint --path . --noout --valid /pgsql/source/master/doc/src/sgml/postgres.sgml make: Leaving directory '/home/alvherre/Code/pgsql/build/master/doc/src/sgml' real 0m0,494s user 0m0,461s sys 0m0,033s -- Álvaro Herrera https://www.2ndQuadrant.com/ PostgreSQL Development, 24x7 Support, Remote DBA, Training & Services