/[pcre]/code/trunk/doc/html/pcrejit.html
ViewVC logotype

Diff of /code/trunk/doc/html/pcrejit.html

Parent Directory Parent Directory | Revision Log Revision Log | View Patch Patch

revision 1193 by ph10, Sat Jun 2 11:03:06 2012 UTC revision 1194 by ph10, Wed Oct 31 17:42:29 2012 UTC
# Line 14  man page, in case the conversion went wr Line 14  man page, in case the conversion went wr
14  <br>  <br>
15  <ul>  <ul>
16  <li><a name="TOC1" href="#SEC1">PCRE JUST-IN-TIME COMPILER SUPPORT</a>  <li><a name="TOC1" href="#SEC1">PCRE JUST-IN-TIME COMPILER SUPPORT</a>
17  <li><a name="TOC2" href="#SEC2">8-BIT and 16-BIT SUPPORT</a>  <li><a name="TOC2" href="#SEC2">8-BIT, 16-BIT AND 32-BIT SUPPORT</a>
18  <li><a name="TOC3" href="#SEC3">AVAILABILITY OF JIT SUPPORT</a>  <li><a name="TOC3" href="#SEC3">AVAILABILITY OF JIT SUPPORT</a>
19  <li><a name="TOC4" href="#SEC4">SIMPLE USE OF JIT</a>  <li><a name="TOC4" href="#SEC4">SIMPLE USE OF JIT</a>
20  <li><a name="TOC5" href="#SEC5">UNSUPPORTED OPTIONS AND PATTERN ITEMS</a>  <li><a name="TOC5" href="#SEC5">UNSUPPORTED OPTIONS AND PATTERN ITEMS</a>
# Line 23  man page, in case the conversion went wr Line 23  man page, in case the conversion went wr
23  <li><a name="TOC8" href="#SEC8">CONTROLLING THE JIT STACK</a>  <li><a name="TOC8" href="#SEC8">CONTROLLING THE JIT STACK</a>
24  <li><a name="TOC9" href="#SEC9">JIT STACK FAQ</a>  <li><a name="TOC9" href="#SEC9">JIT STACK FAQ</a>
25  <li><a name="TOC10" href="#SEC10">EXAMPLE CODE</a>  <li><a name="TOC10" href="#SEC10">EXAMPLE CODE</a>
26  <li><a name="TOC11" href="#SEC11">SEE ALSO</a>  <li><a name="TOC11" href="#SEC11">JIT FAST PATH API</a>
27  <li><a name="TOC12" href="#SEC12">AUTHOR</a>  <li><a name="TOC12" href="#SEC12">SEE ALSO</a>
28  <li><a name="TOC13" href="#SEC13">REVISION</a>  <li><a name="TOC13" href="#SEC13">AUTHOR</a>
29    <li><a name="TOC14" href="#SEC14">REVISION</a>
30  </ul>  </ul>
31  <br><a name="SEC1" href="#TOC1">PCRE JUST-IN-TIME COMPILER SUPPORT</a><br>  <br><a name="SEC1" href="#TOC1">PCRE JUST-IN-TIME COMPILER SUPPORT</a><br>
32  <P>  <P>
# Line 43  JIT support applies only to the traditio Line 44  JIT support applies only to the traditio
44  It does not apply when the DFA matching function is being used. The code for  It does not apply when the DFA matching function is being used. The code for
45  this support was written by Zoltan Herczeg.  this support was written by Zoltan Herczeg.
46  </P>  </P>
47  <br><a name="SEC2" href="#TOC1">8-BIT and 16-BIT SUPPORT</a><br>  <br><a name="SEC2" href="#TOC1">8-BIT, 16-BIT AND 32-BIT SUPPORT</a><br>
48  <P>  <P>
49  JIT support is available for both the 8-bit and 16-bit PCRE libraries. To keep  JIT support is available for all of the 8-bit, 16-bit and 32-bit PCRE
50  this documentation simple, only the 8-bit interface is described in what  libraries. To keep this documentation simple, only the 8-bit interface is
51  follows. If you are using the 16-bit library, substitute the 16-bit functions  described in what follows. If you are using the 16-bit library, substitute the
52  and 16-bit structures (for example, <i>pcre16_jit_stack</i> instead of  16-bit functions and 16-bit structures (for example, <i>pcre16_jit_stack</i>
53  <i>pcre_jit_stack</i>).  instead of <i>pcre_jit_stack</i>). If you are using the 32-bit library,
54    substitute the 32-bit functions and 32-bit structures (for example,
55    <i>pcre32_jit_stack</i> instead of <i>pcre_jit_stack</i>).
56  </P>  </P>
57  <br><a name="SEC3" href="#TOC1">AVAILABILITY OF JIT SUPPORT</a><br>  <br><a name="SEC3" href="#TOC1">AVAILABILITY OF JIT SUPPORT</a><br>
58  <P>  <P>
# Line 61  JIT. The support is limited to the follo Line 64  JIT. The support is limited to the follo
64    Intel x86 32-bit and 64-bit    Intel x86 32-bit and 64-bit
65    MIPS 32-bit    MIPS 32-bit
66    Power PC 32-bit and 64-bit    Power PC 32-bit and 64-bit
67      SPARC 32-bit (experimental)
68  </pre>  </pre>
69  If --enable-jit is set on an unsupported platform, compilation fails.  If --enable-jit is set on an unsupported platform, compilation fails.
70  </P>  </P>
# Line 68  If --enable-jit is set on an unsupported Line 72  If --enable-jit is set on an unsupported
72  A program that is linked with PCRE 8.20 or later can tell if JIT support is  A program that is linked with PCRE 8.20 or later can tell if JIT support is
73  available by calling <b>pcre_config()</b> with the PCRE_CONFIG_JIT option. The  available by calling <b>pcre_config()</b> with the PCRE_CONFIG_JIT option. The
74  result is 1 when JIT is available, and 0 otherwise. However, a simple program  result is 1 when JIT is available, and 0 otherwise. However, a simple program
75  does not need to check this in order to use JIT. The API is implemented in a  does not need to check this in order to use JIT. The normal API is implemented
76  way that falls back to the interpretive code if JIT is not available.  in a way that falls back to the interpretive code if JIT is not available. For
77    programs that need the best possible performance, there is also a "fast path"
78    API that is JIT-specific.
79  </P>  </P>
80  <P>  <P>
81  If your program may sometimes be linked with versions of PCRE that are older  If your program may sometimes be linked with versions of PCRE that are older
# Line 86  You have to do two things to make use of Line 92  You have to do two things to make use of
92        <b>pcre_exec()</b>.        <b>pcre_exec()</b>.
93    
94    (2) Use <b>pcre_free_study()</b> to free the <b>pcre_extra</b> block when it is    (2) Use <b>pcre_free_study()</b> to free the <b>pcre_extra</b> block when it is
95        no longer needed, instead of just freeing it yourself. This        no longer needed, instead of just freeing it yourself. This ensures that
96        ensures that any JIT data is also freed.        any JIT data is also freed.
97  </pre>  </pre>
98  For a program that may be linked with pre-8.20 versions of PCRE, you can insert  For a program that may be linked with pre-8.20 versions of PCRE, you can insert
99  <pre>  <pre>
# Line 161  times as you like for matching different Line 167  times as you like for matching different
167  <br><a name="SEC5" href="#TOC1">UNSUPPORTED OPTIONS AND PATTERN ITEMS</a><br>  <br><a name="SEC5" href="#TOC1">UNSUPPORTED OPTIONS AND PATTERN ITEMS</a><br>
168  <P>  <P>
169  The only <b>pcre_exec()</b> options that are supported for JIT execution are  The only <b>pcre_exec()</b> options that are supported for JIT execution are
170  PCRE_NO_UTF8_CHECK, PCRE_NO_UTF16_CHECK, PCRE_NOTBOL, PCRE_NOTEOL,  PCRE_NO_UTF8_CHECK, PCRE_NO_UTF16_CHECK, PCRE_NO_UTF32_CHECK, PCRE_NOTBOL,
171  PCRE_NOTEMPTY, PCRE_NOTEMPTY_ATSTART, PCRE_PARTIAL_HARD, and PCRE_PARTIAL_SOFT.  PCRE_NOTEOL, PCRE_NOTEMPTY, PCRE_NOTEMPTY_ATSTART, PCRE_PARTIAL_HARD, and
172    PCRE_PARTIAL_SOFT.
173  </P>  </P>
174  <P>  <P>
175  The unsupported pattern items are:  The unsupported pattern items are:
# Line 350  replacement. Line 357  replacement.
357  <br>  <br>
358  No, because this is too costly in terms of resources. However, you could  No, because this is too costly in terms of resources. However, you could
359  implement some clever idea which release the stack if it is not used in let's  implement some clever idea which release the stack if it is not used in let's
360  say two minutes. The JIT callback can help to achive this without keeping a  say two minutes. The JIT callback can help to achieve this without keeping a
361  list of the currently JIT studied patterns.  list of the currently JIT studied patterns.
362  </P>  </P>
363  <P>  <P>
# Line 398  callback. Line 405  callback.
405    
406  </PRE>  </PRE>
407  </P>  </P>
408  <br><a name="SEC11" href="#TOC1">SEE ALSO</a><br>  <br><a name="SEC11" href="#TOC1">JIT FAST PATH API</a><br>
409    <P>
410    Because the API described above falls back to interpreted execution when JIT is
411    not available, it is convenient for programs that are written for general use
412    in many environments. However, calling JIT via <b>pcre_exec()</b> does have a
413    performance impact. Programs that are written for use where JIT is known to be
414    available, and which need the best possible performance, can instead use a
415    "fast path" API to call JIT execution directly instead of calling
416    <b>pcre_exec()</b> (obviously only for patterns that have been successfully
417    studied by JIT).
418    </P>
419    <P>
420    The fast path function is called <b>pcre_jit_exec()</b>, and it takes exactly
421    the same arguments as <b>pcre_exec()</b>, plus one additional argument that
422    must point to a JIT stack. The JIT stack arrangements described above do not
423    apply. The return values are the same as for <b>pcre_exec()</b>.
424    </P>
425    <P>
426    When you call <b>pcre_exec()</b>, as well as testing for invalid options, a
427    number of other sanity checks are performed on the arguments. For example, if
428    the subject pointer is NULL, or its length is negative, an immediate error is
429    given. Also, unless PCRE_NO_UTF[8|16|32] is set, a UTF subject string is tested
430    for validity. In the interests of speed, these checks do not happen on the JIT
431    fast path, and if invalid data is passed, the result is undefined.
432    </P>
433    <P>
434    Bypassing the sanity checks and the <b>pcre_exec()</b> wrapping can give
435    speedups of more than 10%.
436    </P>
437    <br><a name="SEC12" href="#TOC1">SEE ALSO</a><br>
438  <P>  <P>
439  <b>pcreapi</b>(3)  <b>pcreapi</b>(3)
440  </P>  </P>
441  <br><a name="SEC12" href="#TOC1">AUTHOR</a><br>  <br><a name="SEC13" href="#TOC1">AUTHOR</a><br>
442  <P>  <P>
443  Philip Hazel (FAQ by Zoltan Herczeg)  Philip Hazel (FAQ by Zoltan Herczeg)
444  <br>  <br>
# Line 411  University Computing Service Line 447  University Computing Service
447  Cambridge CB2 3QH, England.  Cambridge CB2 3QH, England.
448  <br>  <br>
449  </P>  </P>
450  <br><a name="SEC13" href="#TOC1">REVISION</a><br>  <br><a name="SEC14" href="#TOC1">REVISION</a><br>
451  <P>  <P>
452  Last updated: 04 May 2012  Last updated: 31 October 2012
453  <br>  <br>
454  Copyright &copy; 1997-2012 University of Cambridge.  Copyright &copy; 1997-2012 University of Cambridge.
455  <br>  <br>

Legend:
Removed from v.1193  
changed lines
  Added in v.1194

  ViewVC Help
Powered by ViewVC 1.1.5