Expand documentation about JIT compilation.

This commit is contained in:
Philip.Hazel 2015-09-12 18:10:57 +00:00
parent 297024d65b
commit 06477b27af
1 changed files with 49 additions and 15 deletions

View File

@ -1,4 +1,4 @@
.TH PCRE2TEST 1 "08 September 2015" "PCRE 10.21"
.TH PCRE2TEST 1 "12 September 2015" "PCRE 10.21"
.SH NAME
pcre2test - a program for testing Perl-compatible regular expressions.
.SH SYNOPSIS
@ -614,21 +614,54 @@ actual length of the pattern is passed.
.SS "JIT compilation"
.rs
.sp
The \fB/jit\fP modifier may optionally be followed by an equals sign and a
number in the range 0 to 7:
Just-in-time (JIT) compiling is a heavyweight optimization that can greatly
speed up pattern matching. See the
.\" HREF
\fBpcre2jit\fP
.\"
documentation for details. JIT compiling happens, optionally, after a pattern
has been successfully compiled into an internal form. The JIT compiler converts
this to optimized machine code. It needs to know whether the match-time options
PCRE2_PARTIAL_HARD and PCRE2_PARTIAL_SOFT are going to be used, because
different code is generated for the different cases. See the \fBpartial\fP
modifier in "Subject Modifiers"
.\" HTML <a href="#subjectmodifiers">
.\" </a>
below
.\"
for details of how these options are specified for each match attempt.
.P
JIT compilation is requested by the \fB/jit\fP pattern modifier, which may
optionally be followed by an equals sign and a number in the range 0 to 7.
The three bits that make up the number specify which of the three JIT operating
modes are to be compiled:
.sp
1 compile JIT code for non-partial matching
2 compile JIT code for soft partial matching
4 compile JIT code for hard partial matching
.sp
The possible values for the \fB/jit\fP modifier are therefore:
.sp
0 disable JIT
1 use JIT for normal match only
2 use JIT for soft partial match only
3 use JIT for normal match and soft partial match
4 use JIT for hard partial match only
6 use JIT for soft and hard partial match
1 normal matching only
2 soft partial matching only
3 normal and soft partial matching
4 hard partial matching only
6 soft and hard partial matching only
7 all three modes
.sp
If no number is given, 7 is assumed. If JIT compilation is successful, the
compiled JIT code will automatically be used when \fBpcre2_match()\fP is run
for the appropriate type of match, except when incompatible run-time options
are specified. For more details, see the
If no number is given, 7 is assumed. The phrase "partial matching" means a call
to \fBpcre2_match()\fP with either the PCRE2_PARTIAL_SOFT or the
PCRE2_PARTIAL_HARD option set. Note that such a call may return a complete
match; the options enable the possibility of a partial match, but do not
require it. Note also that if you request JIT compilation only for partial
matching (for example, /jit=2) but do not set the \fBpartial\fP modifier on a
subject line, that match will not use JIT code because none was compiled for
non-partial matching.
.P
If JIT compilation is successful, the compiled JIT code will automatically be
used when an appropriate type of match is run, except when incompatible
run-time options are specified. For more details, see the
.\" HREF
\fBpcre2jit\fP
.\"
@ -789,6 +822,7 @@ warning message, except for \fBreplace\fP, which causes an error. Note that,
matching that uses this pattern.
.
.
.\" HTML <a name="subjectmodifiers"></a>
.SH "SUBJECT MODIFIERS"
.rs
.sp
@ -1485,6 +1519,6 @@ Cambridge, England.
.rs
.sp
.nf
Last updated: 08 September 2015
Last updated: 12 September 2015
Copyright (c) 1997-2015 University of Cambridge.
.fi