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

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

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

revision 1193 by chpe, Tue Oct 16 15:53:30 2012 UTC revision 1194 by ph10, Wed Oct 31 17:42:29 2012 UTC
# Line 1  Line 1 
1  .TH PCREJIT 3 "04 May 2012" "PCRE 8.31"  .TH PCREJIT 3 "31 October 2012" "PCRE 8.32"
2  .SH NAME  .SH NAME
3  PCRE - Perl-compatible regular expressions  PCRE - Perl-compatible regular expressions
4  .SH "PCRE JUST-IN-TIME COMPILER SUPPORT"  .SH "PCRE JUST-IN-TIME COMPILER SUPPORT"
# Line 21  this support was written by Zoltan Hercz Line 21  this support was written by Zoltan Hercz
21  .SH "8-BIT, 16-BIT AND 32-BIT SUPPORT"  .SH "8-BIT, 16-BIT AND 32-BIT SUPPORT"
22  .rs  .rs
23  .sp  .sp
24  JIT support is available for all of the 8-bit, 16-bit and 32-bit PCRE libraries.  JIT support is available for all of the 8-bit, 16-bit and 32-bit PCRE
25  To keep this documentation simple, only the 8-bit interface is described in what  libraries. To keep this documentation simple, only the 8-bit interface is
26  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
27  and 16-bit structures (for example, \fIpcre16_jit_stack\fP instead of  16-bit functions and 16-bit structures (for example, \fIpcre16_jit_stack\fP
28  \fIpcre_jit_stack\fP). If you are using the 32-bit library, substitute the 32-bit functions  instead of \fIpcre_jit_stack\fP). If you are using the 32-bit library,
29  and 32-bit structures (for example, \fIpcre32_jit_stack\fP instead of  substitute the 32-bit functions and 32-bit structures (for example,
30  \fIpcre_jit_stack\fP).  \fIpcre32_jit_stack\fP instead of \fIpcre_jit_stack\fP).
31  .  .
32  .  .
33  .SH "AVAILABILITY OF JIT SUPPORT"  .SH "AVAILABILITY OF JIT SUPPORT"
# Line 41  JIT. The support is limited to the follo Line 41  JIT. The support is limited to the follo
41    Intel x86 32-bit and 64-bit    Intel x86 32-bit and 64-bit
42    MIPS 32-bit    MIPS 32-bit
43    Power PC 32-bit and 64-bit    Power PC 32-bit and 64-bit
44      SPARC 32-bit (experimental)
45  .sp  .sp
46  If --enable-jit is set on an unsupported platform, compilation fails.  If --enable-jit is set on an unsupported platform, compilation fails.
47  .P  .P
48  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
49  available by calling \fBpcre_config()\fP with the PCRE_CONFIG_JIT option. The  available by calling \fBpcre_config()\fP with the PCRE_CONFIG_JIT option. The
50  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
51  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
52  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
53    programs that need the best possible performance, there is also a "fast path"
54    API that is JIT-specific.
55  .P  .P
56  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
57  than 8.20, but you want to use JIT when it is available, you can test  than 8.20, but you want to use JIT when it is available, you can test
# Line 66  You have to do two things to make use of Line 69  You have to do two things to make use of
69        \fBpcre_exec()\fP.        \fBpcre_exec()\fP.
70  .sp  .sp
71    (2) Use \fBpcre_free_study()\fP to free the \fBpcre_extra\fP block when it is    (2) Use \fBpcre_free_study()\fP to free the \fBpcre_extra\fP block when it is
72        no longer needed, instead of just freeing it yourself. This        no longer needed, instead of just freeing it yourself. This ensures that
73        ensures that any JIT data is also freed.        any JIT data is also freed.
74  .sp  .sp
75  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
76  .sp  .sp
# Line 335  replacement. Line 338  replacement.
338  .sp  .sp
339  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
340  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
341  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
342  list of the currently JIT studied patterns.  list of the currently JIT studied patterns.
343  .P  .P
344  (6) OK, the stack is for long term memory allocation. But what happens if a  (6) OK, the stack is for long term memory allocation. But what happens if a
# Line 381  callback. Line 384  callback.
384  .sp  .sp
385  .  .
386  .  .
387    .SH "JIT FAST PATH API"
388    .rs
389    .sp
390    Because the API described above falls back to interpreted execution when JIT is
391    not available, it is convenient for programs that are written for general use
392    in many environments. However, calling JIT via \fBpcre_exec()\fP does have a
393    performance impact. Programs that are written for use where JIT is known to be
394    available, and which need the best possible performance, can instead use a
395    "fast path" API to call JIT execution directly instead of calling
396    \fBpcre_exec()\fP (obviously only for patterns that have been successfully
397    studied by JIT).
398    .P
399    The fast path function is called \fBpcre_jit_exec()\fP, and it takes exactly
400    the same arguments as \fBpcre_exec()\fP, plus one additional argument that
401    must point to a JIT stack. The JIT stack arrangements described above do not
402    apply. The return values are the same as for \fBpcre_exec()\fP.
403    .P
404    When you call \fBpcre_exec()\fP, as well as testing for invalid options, a
405    number of other sanity checks are performed on the arguments. For example, if
406    the subject pointer is NULL, or its length is negative, an immediate error is
407    given. Also, unless PCRE_NO_UTF[8|16|32] is set, a UTF subject string is tested
408    for validity. In the interests of speed, these checks do not happen on the JIT
409    fast path, and if invalid data is passed, the result is undefined.
410    .P
411    Bypassing the sanity checks and the \fBpcre_exec()\fP wrapping can give
412    speedups of more than 10%.
413    .
414    .
415  .SH "SEE ALSO"  .SH "SEE ALSO"
416  .rs  .rs
417  .sp  .sp
# Line 401  Cambridge CB2 3QH, England. Line 432  Cambridge CB2 3QH, England.
432  .rs  .rs
433  .sp  .sp
434  .nf  .nf
435  Last updated: 04 May 2012  Last updated: 31 October 2012
436  Copyright (c) 1997-2012 University of Cambridge.  Copyright (c) 1997-2012 University of Cambridge.
437  .fi  .fi

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

  ViewVC Help
Powered by ViewVC 1.1.5