Final source and document tidies for 8.20-RC1.

git-svn-id: svn://vcs.exim.org/pcre/code/trunk@691 2f5784b3-3f2a-0410-8824-cb99058d5e15

1 files changed, 255 insertions, 0 deletions

diff --git a/doc/html/pcrejit.html b/doc/html/pcrejit.html
index 438812a..b6a1c05 100644
--- a/doc/html/pcrejit.html
+++ b/doc/html/pcrejit.html
@@ -13,7 +13,262 @@ from the original man page. If there is any nonsense in it, please consult the
 man page, in case the conversion went wrong.
 <br>
 <ul>
+<li><a name="TOC1" href="#SEC1">PCRE JUST-IN-TIME COMPILER SUPPORT</a>
+<li><a name="TOC2" href="#SEC2">AVAILABILITY OF JIT SUPPORT</a>
+<li><a name="TOC3" href="#SEC3">SIMPLE USE OF JIT</a>
+<li><a name="TOC4" href="#SEC4">UNSUPPORTED OPTIONS AND PATTERN ITEMS</a>
+<li><a name="TOC5" href="#SEC5">RETURN VALUES FROM JIT EXECUTION</a>
+<li><a name="TOC6" href="#SEC6">SAVING AND RESTORING COMPILED PATTERNS</a>
+<li><a name="TOC7" href="#SEC7">CONTROLLING THE JIT STACK</a>
+<li><a name="TOC8" href="#SEC8">EXAMPLE CODE</a>
+<li><a name="TOC9" href="#SEC9">SEE ALSO</a>
+<li><a name="TOC10" href="#SEC10">AUTHOR</a>
+<li><a name="TOC11" href="#SEC11">REVISION</a>
 </ul>
+<br><a name="SEC1" href="#TOC1">PCRE JUST-IN-TIME COMPILER SUPPORT</a><br>
+<P>
+Just-in-time compiling is a heavyweight optimization that can greatly speed up
+pattern matching. However, it comes at the cost of extra processing before the
+match is performed. Therefore, it is of most benefit when the same pattern is
+going to be matched many times. This does not necessarily mean many calls of
+\fPpcre_exec()\fP; if the pattern is not anchored, matching attempts may take
+place many times at various positions in the subject, even for a single call to
+<b>pcre_exec()</b>. If the subject string is very long, it may still pay to use
+JIT for one-off matches.
+</P>
+<P>
+JIT support applies only to the traditional matching function,
+<b>pcre_exec()</b>. It does not apply when <b>pcre_dfa_exec()</b> is being used.
+The code for this support was written by Zoltan Herczeg.
+</P>
+<br><a name="SEC2" href="#TOC1">AVAILABILITY OF JIT SUPPORT</a><br>
+<P>
+JIT support is an optional feature of PCRE. The "configure" option --enable-jit
+(or equivalent CMake option) must be set when PCRE is built if you want to use
+JIT. The support is limited to the following hardware platforms:
+<pre>
+  ARM v5, v7, and Thumb2
+  Intel x86 32-bit and 64-bit
+  MIPS 32-bit
+  Power PC 32-bit and 64-bit
+</pre>
+If --enable-jit is set on an unsupported platform, compilation fails.
+</P>
+<P>
+A program can tell if JIT support is available by calling <b>pcre_config()</b>
+with the PCRE_CONFIG_JIT option. The result is 1 when JIT is available, and 0
+otherwise. However, a simple program does not need to check this in order to
+use JIT. The API is implemented in a way that falls back to the ordinary PCRE
+code if JIT is not available.
+</P>
+<br><a name="SEC3" href="#TOC1">SIMPLE USE OF JIT</a><br>
+<P>
+You have to do two things to make use of the JIT support in the simplest way:
+<pre>
+  (1) Call <b>pcre_study()</b> with the PCRE_STUDY_JIT_COMPILE option for
+      each compiled pattern, and pass the resulting <b>pcre_extra</b> block to
+      <b>pcre_exec()</b>.
+
+  (2) Use <b>pcre_free_study()</b> to free the <b>pcre_extra</b> block when it is
+      no longer needed instead of just freeing it yourself. This
+      ensures that any JIT data is also freed.
+</pre>
+In some circumstances you may need to call additional functions. These are
+described in the section entitled
+<a href="#stackcontrol">"Controlling the JIT stack"</a>
+below.
+</P>
+<P>
+If JIT support is not available, PCRE_STUDY_JIT_COMPILE is ignored, and no JIT
+data is set up. Otherwise, the compiled pattern is passed to the JIT compiler,
+which turns it into machine code that executes much faster than the normal
+interpretive code. When <b>pcre_exec()</b> is passed a <b>pcre_extra</b> block
+containing a pointer to JIT code, it obeys that instead of the normal code. The
+result is identical, but the code runs much faster.
+</P>
+<P>
+There are some <b>pcre_exec()</b> options that are not supported for JIT
+execution. There are also some pattern items that JIT cannot handle. Details
+are given below. In both cases, execution automatically falls back to the
+interpretive code.
+</P>
+<P>
+If the JIT compiler finds an unsupported item, no JIT data is generated. You
+can find out if JIT execution is available after studying a pattern by calling
+<b>pcre_fullinfo()</b> with the PCRE_INFO_JIT option. A result of 1 means that
+JIT compilationw was successful. A result of 0 means that JIT support is not
+available, or the pattern was not studied with PCRE_STUDY_JIT_COMPILE, or the
+JIT compiler was not able to handle the pattern.
+</P>
+<br><a name="SEC4" href="#TOC1">UNSUPPORTED OPTIONS AND PATTERN ITEMS</a><br>
+<P>
+The only <b>pcre_exec()</b> options that are supported for JIT execution are
+PCRE_NO_UTF8_CHECK, PCRE_NOTBOL, PCRE_NOTEOL, PCRE_NOTEMPTY, and
+PCRE_NOTEMPTY_ATSTART. Note in particular that partial matching is not
+supported.
+</P>
+<P>
+The unsupported pattern items are:
+<pre>
+  \C            match a single byte, even in UTF-8 mode
+  (?Cn)          callouts
+  (?(&#60;name&#62;)...  conditional test on setting of a named subpattern
+  (?(R)...       conditional test on whole pattern recursion
+  (?(Rn)...      conditional test on recursion, by number
+  (?(R&name)...  conditional test on recursion, by name
+  (*COMMIT)      )
+  (*MARK)        )
+  (*PRUNE)       ) the backtracking control verbs
+  (*SKIP)        )
+  (*THEN)        )
+</pre>
+Support for some of these may be added in future.
+</P>
+<br><a name="SEC5" href="#TOC1">RETURN VALUES FROM JIT EXECUTION</a><br>
+<P>
+When a pattern is matched using JIT execution, the return values are the same
+as those given by the interpretive <b>pcre_exec()</b> code, with the addition of
+one new error code: PCRE_ERROR_JIT_STACKLIMIT. This means that the memory used
+for the JIT stack was insufficient. See
+<a href="#stackcontrol">"Controlling the JIT stack"</a>
+below for a discussion of JIT stack usage. For compatibility with the
+interpretive <b>pcre_exec()</b> code, no more than two-thirds of the
+<i>ovector</i> argument is used for passing back captured substrings.
+</P>
+<P>
+The error code PCRE_ERROR_MATCHLIMIT is returned by the JIT code if searching a
+very large pattern tree goes on for too long, as it is in the same circumstance
+when JIT is not used, but the details of exactly what is counted are not the
+same. The PCRE_ERROR_RECURSIONLIMIT error code is never returned by JIT
+execution.
+</P>
+<br><a name="SEC6" href="#TOC1">SAVING AND RESTORING COMPILED PATTERNS</a><br>
+<P>
+The code that is generated by the JIT compiler is architecture-specific, and is
+also position dependent. For those reasons it cannot be saved and restored like
+the bytecode and other data of a compiled pattern. You should be able run
+<b>pcre_study()</b> on a saved and restored pattern, and thereby recreate the
+JIT data, but because JIT compilation uses significant resources, it is
+probably not worth doing this.
+<a name="stackcontrol"></a></P>
+<br><a name="SEC7" href="#TOC1">CONTROLLING THE JIT STACK</a><br>
+<P>
+When the compiled JIT code runs, it needs a block of memory to use as a stack.
+By default, it uses 32K on the machine stack. However, some large or
+complicated patterns need more than this. The error PCRE_ERROR_JIT_STACKLIMIT
+is given when there is not enough stack. Three functions are provided for
+managing blocks of memory for use as JIT stacks.
+</P>
+<P>
+The <b>pcre_jit_stack_alloc()</b> function creates a JIT stack. Its arguments
+are a starting size and a maximum size, and it returns a pointer to an opaque
+structure of type <b>pcre_jit_stack</b>, or NULL if there is an error. The
+<b>pcre_jit_stack_free()</b> function can be used to free a stack that is no
+longer needed. (For the technically minded: the address space is allocated by
+mmap or VirtualAlloc.)
+</P>
+<P>
+JIT uses far less memory for recursion than the interpretive code,
+and a maximum stack size of 512K to 1M should be more than enough for any
+pattern.
+</P>
+<P>
+The <b>pcre_assign_jit_stack()</b> function specifies which stack JIT code
+should use. Its arguments are as follows:
+<pre>
+  pcre_extra         *extra
+  pcre_jit_callback  callback
+  void               *data
+</pre>
+The <i>extra</i> argument must be the result of studying a pattern with
+PCRE_STUDY_JIT_COMPILE. There are three cases for the values of the other two
+options:
+<pre>
+  (1) If <i>callback</i> is NULL and <i>data</i> is NULL, an internal 32K block
+      on the machine stack is used.
+
+  (2) If <i>callback</i> is NULL and <i>data</i> is not NULL, <i>data</i> must be
+      a valid JIT stack, the result of calling <b>pcre_jit_stack_alloc()</b>.
+
+  (3) If <i>callback</i> not NULL, it must point to a function that is called
+      with <i>data</i> as an argument at the start of matching, in order to
+      set up a JIT stack. If the result is NULL, the internal 32K stack
+      is used; otherwise the return value must be a valid JIT stack,
+      the result of calling <b>pcre_jit_stack_alloc()</b>.
+</pre>
+You may safely assign the same JIT stack to more than one pattern, as long as
+they are all matched sequentially in the same thread. In a multithread
+application, each thread must use its own JIT stack.
+</P>
+<P>
+Strictly speaking, even more is allowed. You can assign the same stack to any
+number of patterns as long as they are not used for matching by multiple
+threads at the same time. For example, you can assign the same stack to all
+compiled patterns, and use a global mutex in the callback to wait until the
+stack is available for use. However, this is an inefficient solution, and
+not recommended.
+</P>
+<P>
+This is a suggestion for how a typical multithreaded program might operate:
+<pre>
+  During thread initalization
+    thread_local_var = pcre_jit_stack_alloc(...)
+
+  During thread exit
+    pcre_jit_stack_free(thread_local_var)
+
+  Use a one-line callback function
+    return thread_local_var
+</pre>
+All the functions described in this section do nothing if JIT is not available,
+and <b>pcre_assign_jit_stack()</b> does nothing unless the <b>extra</b> argument
+is non-NULL and points to a <b>pcre_extra</b> block that is the result of a
+successful study with PCRE_STUDY_JIT_COMPILE.
+</P>
+<br><a name="SEC8" href="#TOC1">EXAMPLE CODE</a><br>
+<P>
+This is a single-threaded example that specifies a JIT stack without using a
+callback.
+<pre>
+  int rc;
+  int ovector[30];
+  pcre *re;
+  pcre_extra *extra;
+  pcre_jit_stack *jit_stack;
+
+  re = pcre_compile(pattern, 0, &error, &erroffset, NULL);
+  /* Check for errors */
+  extra = pcre_study(re, PCRE_STUDY_JIT_COMPILE, &error);
+  jit_stack = pcre_jit_stack_alloc(32*1024, 512*1024);
+  /* Check for error (NULL) */
+  pcre_assign_jit_stack(extra, NULL, jit_stack);
+  rc = pcre_exec(re, extra, subject, length, 0, 0, ovector, 30);
+  /* Check results */
+  pcre_free(re);
+  pcre_free_study(extra);
+  pcre_jit_stack_free(jit_stack);
+
+</PRE>
+</P>
+<br><a name="SEC9" href="#TOC1">SEE ALSO</a><br>
+<P>
+<b>pcreapi</b>(3)
+</P>
+<br><a name="SEC10" href="#TOC1">AUTHOR</a><br>
+<P>
+Philip Hazel
+<br>
+University Computing Service
+<br>
+Cambridge CB2 3QH, England.
+<br>
+</P>
+<br><a name="SEC11" href="#TOC1">REVISION</a><br>
+<P>
+Last updated: 06 September 2011
+<br>
+Copyright &copy; 1997-2011 University of Cambridge.
+<br>
 <p>
 Return to the <a href="index.html">PCRE index page</a>.
 </p>