/[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 903 by ph10, Sat Jan 21 16:37:17 2012 UTC revision 921 by ph10, Sat Feb 18 18:45:55 2012 UTC
# Line 40  JIT. The support is limited to the follo Line 40  JIT. The support is limited to the follo
40    MIPS 32-bit    MIPS 32-bit
41    Power PC 32-bit and 64-bit    Power PC 32-bit and 64-bit
42  .sp  .sp
43  The Power PC support is designated as experimental because it has not been  If --enable-jit is set on an unsupported platform, compilation fails.
 fully tested. If --enable-jit is set on an unsupported platform, compilation  
 fails.  
44  .P  .P
45  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
46  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
47  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
48  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 API is implemented in a
49  way that falls back to the ordinary PCRE code if JIT is not available.  way that falls back to the interpretive code if JIT is not available.
50  .P  .P
51  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
52  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 64  You have to do two things to make use of
64        \fBpcre_exec()\fP.        \fBpcre_exec()\fP.
65  .sp  .sp
66    (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
67        no longer needed instead of just freeing it yourself. This        no longer needed, instead of just freeing it yourself. This
68        ensures that any JIT data is also freed.        ensures that any JIT data is also freed.
69  .sp  .sp
70  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
# Line 84  this to free the study data: Line 82  this to free the study data:
82        pcre_free(study_ptr);        pcre_free(study_ptr);
83    #endif    #endif
84  .sp  .sp
85    PCRE_STUDY_JIT_COMPILE requests the JIT compiler to generate code for complete
86    matches. If you want to run partial matches using the PCRE_PARTIAL_HARD or
87    PCRE_PARTIAL_SOFT options of \fBpcre_exec()\fP, you should set one or both of
88    the following options in addition to, or instead of, PCRE_STUDY_JIT_COMPILE
89    when you call \fBpcre_study()\fP:
90    .sp
91      PCRE_STUDY_JIT_PARTIAL_HARD_COMPILE
92      PCRE_STUDY_JIT_PARTIAL_SOFT_COMPILE
93    .sp
94    The JIT compiler generates different optimized code for each of the three
95    modes (normal, soft partial, hard partial). When \fBpcre_exec()\fP is called,
96    the appropriate code is run if it is available. Otherwise, the pattern is
97    matched using interpretive code.
98    .P
99  In some circumstances you may need to call additional functions. These are  In some circumstances you may need to call additional functions. These are
100  described in the section entitled  described in the section entitled
101  .\" HTML <a href="#stackcontrol">  .\" HTML <a href="#stackcontrol">
# Line 92  described in the section entitled Line 104  described in the section entitled
104  .\"  .\"
105  below.  below.
106  .P  .P
107  If JIT support is not available, PCRE_STUDY_JIT_COMPILE is ignored, and no JIT  If JIT support is not available, PCRE_STUDY_JIT_COMPILE etc. are ignored, and
108  data is set up. Otherwise, the compiled pattern is passed to the JIT compiler,  no JIT data is created. Otherwise, the compiled pattern is passed to the JIT
109  which turns it into machine code that executes much faster than the normal  compiler, which turns it into machine code that executes much faster than the
110  interpretive code. When \fBpcre_exec()\fP is passed a \fBpcre_extra\fP block  normal interpretive code. When \fBpcre_exec()\fP is passed a \fBpcre_extra\fP
111  containing a pointer to JIT code, it obeys that instead of the normal code. The  block containing a pointer to JIT code of the appropriate mode (normal or
112  result is identical, but the code runs much faster.  hard/soft partial), it obeys that code instead of running the interpreter. The
113    result is identical, but the compiled JIT code runs much faster.
114  .P  .P
115  There are some \fBpcre_exec()\fP options that are not supported for JIT  There are some \fBpcre_exec()\fP options that are not supported for JIT
116  execution. There are also some pattern items that JIT cannot handle. Details  execution. There are also some pattern items that JIT cannot handle. Details
# Line 108  If the JIT compiler finds an unsupported Line 121  If the JIT compiler finds an unsupported
121  can find out if JIT execution is available after studying a pattern by calling  can find out if JIT execution is available after studying a pattern by calling
122  \fBpcre_fullinfo()\fP with the PCRE_INFO_JIT option. A result of 1 means that  \fBpcre_fullinfo()\fP with the PCRE_INFO_JIT option. A result of 1 means that
123  JIT compilation was successful. A result of 0 means that JIT support is not  JIT compilation was successful. A result of 0 means that JIT support is not
124  available, or the pattern was not studied with PCRE_STUDY_JIT_COMPILE, or the  available, or the pattern was not studied with PCRE_STUDY_JIT_COMPILE etc., or
125  JIT compiler was not able to handle the pattern.  the JIT compiler was not able to handle the pattern.
126  .P  .P
127  Once a pattern has been studied, with or without JIT, it can be used as many  Once a pattern has been studied, with or without JIT, it can be used as many
128  times as you like for matching different subject strings.  times as you like for matching different subject strings.
# Line 119  times as you like for matching different Line 132  times as you like for matching different
132  .rs  .rs
133  .sp  .sp
134  The only \fBpcre_exec()\fP options that are supported for JIT execution are  The only \fBpcre_exec()\fP options that are supported for JIT execution are
135  PCRE_NO_UTF8_CHECK, PCRE_NOTBOL, PCRE_NOTEOL, PCRE_NOTEMPTY, and  PCRE_NO_UTF8_CHECK, PCRE_NOTBOL, PCRE_NOTEOL, PCRE_NOTEMPTY,
136  PCRE_NOTEMPTY_ATSTART. Note in particular that partial matching is not  PCRE_NOTEMPTY_ATSTART, PCRE_PARTIAL_HARD, and PCRE_PARTIAL_SOFT.
 supported.  
137  .P  .P
138  The unsupported pattern items are:  The unsupported pattern items are:
139  .sp  .sp
# Line 210  should use. Its arguments are as follows Line 222  should use. Its arguments are as follows
222    void               *data    void               *data
223  .sp  .sp
224  The \fIextra\fP argument must be the result of studying a pattern with  The \fIextra\fP argument must be the result of studying a pattern with
225  PCRE_STUDY_JIT_COMPILE. There are three cases for the values of the other two  PCRE_STUDY_JIT_COMPILE etc. There are three cases for the values of the other
226  options:  two options:
227  .sp  .sp
228    (1) If \fIcallback\fP is NULL and \fIdata\fP is NULL, an internal 32K block    (1) If \fIcallback\fP is NULL and \fIdata\fP is NULL, an internal 32K block
229        on the machine stack is used.        on the machine stack is used.
# Line 250  This is a suggestion for how a typical m Line 262  This is a suggestion for how a typical m
262  All the functions described in this section do nothing if JIT is not available,  All the functions described in this section do nothing if JIT is not available,
263  and \fBpcre_assign_jit_stack()\fP does nothing unless the \fBextra\fP argument  and \fBpcre_assign_jit_stack()\fP does nothing unless the \fBextra\fP argument
264  is non-NULL and points to a \fBpcre_extra\fP block that is the result of a  is non-NULL and points to a \fBpcre_extra\fP block that is the result of a
265  successful study with PCRE_STUDY_JIT_COMPILE.  successful study with PCRE_STUDY_JIT_COMPILE etc.
266  .  .
267  .  .
268  .\" HTML <a name="stackfaq"></a>  .\" HTML <a name="stackfaq"></a>
# Line 367  Cambridge CB2 3QH, England. Line 379  Cambridge CB2 3QH, England.
379  .rs  .rs
380  .sp  .sp
381  .nf  .nf
382  Last updated: 08 January 2012  Last updated: 18 February 2012
383  Copyright (c) 1997-2012 University of Cambridge.  Copyright (c) 1997-2012 University of Cambridge.
384  .fi  .fi
Legend:
Removed from v.903  
changed lines
  Added in v.921
webmaster@exim.org
 ViewVC Help
Powered by ViewVC 1.1.12