Revision: 368
http://www.exim.org/viewvc/pcre2?view=rev&revision=368
Author: ph10
Date: 2015-09-12 19:10:57 +0100 (Sat, 12 Sep 2015)
Log Message:
-----------
Expand documentation about JIT compilation.
Modified Paths:
--------------
code/trunk/doc/pcre2test.1
Modified: code/trunk/doc/pcre2test.1
===================================================================
--- code/trunk/doc/pcre2test.1 2015-09-11 16:56:47 UTC (rev 367)
+++ code/trunk/doc/pcre2test.1 2015-09-12 18:10:57 UTC (rev 368)
@@ -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
@@ -262,7 +262,7 @@
.sp
#newline_default [<newline-list>]
.sp
-When PCRE2 is built, a default newline convention can be specified. This
+When PCRE2 is built, a default newline convention can be specified. This
determines which characters and/or character pairs are recognized as indicating
a newline in a pattern or subject string. The default can be overridden when a
pattern is compiled. The standard test files contain tests of various newline
@@ -473,7 +473,7 @@
allow_empty_class set PCRE2_ALLOW_EMPTY_CLASS
alt_bsux set PCRE2_ALT_BSUX
alt_circumflex set PCRE2_ALT_CIRCUMFLEX
- alt_verbnames set PCRE2_ALT_VERBNAMES
+ alt_verbnames set PCRE2_ALT_VERBNAMES
anchored set PCRE2_ANCHORED
auto_callout set PCRE2_AUTO_CALLOUT
/i caseless set PCRE2_CASELESS
@@ -614,21 +614,54 @@
.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 @@
matching that uses this pattern.
.
.
+.\" HTML <a name="subjectmodifiers"></a>
.SH "SUBJECT MODIFIERS"
.rs
.sp
@@ -1485,6 +1519,6 @@
.rs
.sp
.nf
-Last updated: 08 September 2015
+Last updated: 12 September 2015
Copyright (c) 1997-2015 University of Cambridge.
.fi
