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

Diff of /code/trunk/doc/pcreapi.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 962  If studying the pattern does not produce Line 962  If studying the pattern does not produce
962  wants to pass any of the other fields to \fBpcre_exec()\fP or  wants to pass any of the other fields to \fBpcre_exec()\fP or
963  \fBpcre_dfa_exec()\fP, it must set up its own \fBpcre_extra\fP block.  \fBpcre_dfa_exec()\fP, it must set up its own \fBpcre_extra\fP block.
964  .P  .P
965  The second argument of \fBpcre_study()\fP contains option bits. There is only  The second argument of \fBpcre_study()\fP contains option bits. There are three
966  one option: PCRE_STUDY_JIT_COMPILE. If this is set, and the just-in-time  options:
967  compiler is available, the pattern is further compiled into machine code that  .sp
968  executes much faster than the \fBpcre_exec()\fP matching function. If    PCRE_STUDY_JIT_COMPILE
969  the just-in-time compiler is not available, this option is ignored. All other    PCRE_STUDY_JIT_PARTIAL_HARD_COMPILE
970  bits in the \fIoptions\fP argument must be zero.    PCRE_STUDY_JIT_PARTIAL_SOFT_COMPILE
971    .sp
972    If any of these are set, and the just-in-time compiler is available, the
973    pattern is further compiled into machine code that executes much faster than
974    the \fBpcre_exec()\fP interpretive matching function. If the just-in-time
975    compiler is not available, these options are ignored. All other bits in the
976    \fIoptions\fP argument must be zero.
977  .P  .P
978  JIT compilation is a heavyweight optimization. It can take some time for  JIT compilation is a heavyweight optimization. It can take some time for
979  patterns to be analyzed, and for one-off matches and simple patterns the  patterns to be analyzed, and for one-off matches and simple patterns the
# Line 991  When you are finished with a pattern, yo Line 997  When you are finished with a pattern, yo
997  study data by calling \fBpcre_free_study()\fP. This function was added to the  study data by calling \fBpcre_free_study()\fP. This function was added to the
998  API for release 8.20. For earlier versions, the memory could be freed with  API for release 8.20. For earlier versions, the memory could be freed with
999  \fBpcre_free()\fP, just like the pattern itself. This will still work in cases  \fBpcre_free()\fP, just like the pattern itself. This will still work in cases
1000  where PCRE_STUDY_JIT_COMPILE is not used, but it is advisable to change to the  where JIT optimization is not used, but it is advisable to change to the new
1001  new function when convenient.  function when convenient.
1002  .P  .P
1003  This is a typical way in which \fBpcre_study\fP() is used (except that in a  This is a typical way in which \fBpcre_study\fP() is used (except that in a
1004  real application there should be tests for errors):  real application there should be tests for errors):
# Line 1025  created. This speeds up finding a positi Line 1031  created. This speeds up finding a positi
1031  matching. (In 16-bit mode, the bitmap is used for 16-bit values less than 256.)  matching. (In 16-bit mode, the bitmap is used for 16-bit values less than 256.)
1032  .P  .P
1033  These two optimizations apply to both \fBpcre_exec()\fP and  These two optimizations apply to both \fBpcre_exec()\fP and
1034  \fBpcre_dfa_exec()\fP. However, they are not used by \fBpcre_exec()\fP if  \fBpcre_dfa_exec()\fP, and the information is also used by the JIT compiler.
1035  \fBpcre_study()\fP is called with the PCRE_STUDY_JIT_COMPILE option, and  The optimizations can be disabled by setting the PCRE_NO_START_OPTIMIZE option
1036  just-in-time compiling is successful. The optimizations can be disabled by  when calling \fBpcre_exec()\fP or \fBpcre_dfa_exec()\fP, but if this is done,
1037  setting the PCRE_NO_START_OPTIMIZE option when calling \fBpcre_exec()\fP or  JIT execution is also disabled. You might want to do this if your pattern
1038  \fBpcre_dfa_exec()\fP. You might want to do this if your pattern contains  contains callouts or (*MARK) and you want to make use of these facilities in
1039  callouts or (*MARK) (which cannot be handled by the JIT compiler), and you want  cases where matching fails. See the discussion of PCRE_NO_START_OPTIMIZE
 to make use of these facilities in cases where matching fails. See the  
 discussion of PCRE_NO_START_OPTIMIZE  
1040  .\" HTML <a href="#execoptions">  .\" HTML <a href="#execoptions">
1041  .\" </a>  .\" </a>
1042  below.  below.
# Line 1205  Return 1 if the (?J) or (?-J) option set Line 1209  Return 1 if the (?J) or (?-J) option set
1209  .sp  .sp
1210    PCRE_INFO_JIT    PCRE_INFO_JIT
1211  .sp  .sp
1212  Return 1 if the pattern was studied with the PCRE_STUDY_JIT_COMPILE option, and  Return 1 if the pattern was studied with one of the JIT options, and
1213  just-in-time compiling was successful. The fourth argument should point to an  just-in-time compiling was successful. The fourth argument should point to an
1214  \fBint\fP variable. A return value of 0 means that JIT support is not available  \fBint\fP variable. A return value of 0 means that JIT support is not available
1215  in this version of PCRE, or that the pattern was not studied with the  in this version of PCRE, or that the pattern was not studied with a JIT option,
1216  PCRE_STUDY_JIT_COMPILE option, or that the JIT compiler could not handle this  or that the JIT compiler could not handle this particular pattern. See the
 particular pattern. See the  
1217  .\" HREF  .\" HREF
1218  \fBpcrejit\fP  \fBpcrejit\fP
1219  .\"  .\"
# Line 1218  documentation for details of what can an Line 1221  documentation for details of what can an
1221  .sp  .sp
1222    PCRE_INFO_JITSIZE    PCRE_INFO_JITSIZE
1223  .sp  .sp
1224  If the pattern was successfully studied with the PCRE_STUDY_JIT_COMPILE option,  If the pattern was successfully studied with a JIT option, return the size of
1225  return the size of the JIT compiled code, otherwise return zero. The fourth  the JIT compiled code, otherwise return zero. The fourth argument should point
1226  argument should point to a \fBsize_t\fP variable.  to a \fBsize_t\fP variable.
1227  .sp  .sp
1228    PCRE_INFO_LASTLITERAL    PCRE_INFO_LASTLITERAL
1229  .sp  .sp
# Line 1492  patterns that are not anchored, the coun Line 1495  patterns that are not anchored, the coun
1495  in the subject string.  in the subject string.
1496  .P  .P
1497  When \fBpcre_exec()\fP is called with a pattern that was successfully studied  When \fBpcre_exec()\fP is called with a pattern that was successfully studied
1498  with the PCRE_STUDY_JIT_COMPILE option, the way that the matching is executed  with a JIT option, the way that the matching is executed is entirely different.
1499  is entirely different. However, there is still the possibility of runaway  However, there is still the possibility of runaway matching that goes on for a
1500  matching that goes on for a very long time, and so the \fImatch_limit\fP value  very long time, and so the \fImatch_limit\fP value is also used in this case
1501  is also used in this case (but in a different way) to limit how long the  (but in a different way) to limit how long the matching can continue.
 matching can continue.  
1502  .P  .P
1503  The default value for the limit can be set when PCRE is built; the default  The default value for the limit can be set when PCRE is built; the default
1504  default is 10 million, which handles all but the most extreme cases. You can  default is 10 million, which handles all but the most extreme cases. You can
# Line 1514  This limit is of use only if it is set s Line 1516  This limit is of use only if it is set s
1516  Limiting the recursion depth limits the amount of machine stack that can be  Limiting the recursion depth limits the amount of machine stack that can be
1517  used, or, when PCRE has been compiled to use memory on the heap instead of the  used, or, when PCRE has been compiled to use memory on the heap instead of the
1518  stack, the amount of heap memory that can be used. This limit is not relevant,  stack, the amount of heap memory that can be used. This limit is not relevant,
1519  and is ignored, if the pattern was successfully studied with  and is ignored, when matching is done using JIT compiled code.
 PCRE_STUDY_JIT_COMPILE.  
1520  .P  .P
1521  The default value for \fImatch_limit_recursion\fP can be set when PCRE is  The default value for \fImatch_limit_recursion\fP can be set when PCRE is
1522  built; the default default is the same value as the default for  built; the default default is the same value as the default for
# Line 1572  documentation. Line 1573  documentation.
1573  The unused bits of the \fIoptions\fP argument for \fBpcre_exec()\fP must be  The unused bits of the \fIoptions\fP argument for \fBpcre_exec()\fP must be
1574  zero. The only bits that may be set are PCRE_ANCHORED, PCRE_NEWLINE_\fIxxx\fP,  zero. The only bits that may be set are PCRE_ANCHORED, PCRE_NEWLINE_\fIxxx\fP,
1575  PCRE_NOTBOL, PCRE_NOTEOL, PCRE_NOTEMPTY, PCRE_NOTEMPTY_ATSTART,  PCRE_NOTBOL, PCRE_NOTEOL, PCRE_NOTEMPTY, PCRE_NOTEMPTY_ATSTART,
1576  PCRE_NO_START_OPTIMIZE, PCRE_NO_UTF8_CHECK, PCRE_PARTIAL_SOFT, and  PCRE_NO_START_OPTIMIZE, PCRE_NO_UTF8_CHECK, PCRE_PARTIAL_HARD, and
1577  PCRE_PARTIAL_HARD.  PCRE_PARTIAL_SOFT.
1578  .P  .P
1579  If the pattern was successfully studied with the PCRE_STUDY_JIT_COMPILE option,  If the pattern was successfully studied with one of the just-in-time (JIT)
1580  the only supported options for JIT execution are PCRE_NO_UTF8_CHECK,  compile options, the only supported options for JIT execution are
1581  PCRE_NOTBOL, PCRE_NOTEOL, PCRE_NOTEMPTY, and PCRE_NOTEMPTY_ATSTART. Note in  PCRE_NO_UTF8_CHECK, PCRE_NOTBOL, PCRE_NOTEOL, PCRE_NOTEMPTY,
1582  particular that partial matching is not supported. If an unsupported option is  PCRE_NOTEMPTY_ATSTART, PCRE_PARTIAL_HARD, and PCRE_PARTIAL_SOFT. If an
1583  used, JIT execution is disabled and the normal interpretive code in  unsupported option is used, JIT execution is disabled and the normal
1584  \fBpcre_exec()\fP is run.  interpretive code in \fBpcre_exec()\fP is run.
1585  .sp  .sp
1586    PCRE_ANCHORED    PCRE_ANCHORED
1587  .sp  .sp
# Line 1699  causing performance to suffer, but ensur Line 1700  causing performance to suffer, but ensur
1700  "no match", the callouts do occur, and that items such as (*COMMIT) and (*MARK)  "no match", the callouts do occur, and that items such as (*COMMIT) and (*MARK)
1701  are considered at every possible starting position in the subject string. If  are considered at every possible starting position in the subject string. If
1702  PCRE_NO_START_OPTIMIZE is set at compile time, it cannot be unset at matching  PCRE_NO_START_OPTIMIZE is set at compile time, it cannot be unset at matching
1703  time.  time. The use of PCRE_NO_START_OPTIMIZE disables JIT execution; when it is set,
1704    matching is always done using interpretively.
1705  .P  .P
1706  Setting PCRE_NO_START_OPTIMIZE can change the outcome of a matching operation.  Setting PCRE_NO_START_OPTIMIZE can change the outcome of a matching operation.
1707  Consider the pattern  Consider the pattern
# Line 2644  Cambridge CB2 3QH, England. Line 2646  Cambridge CB2 3QH, England.
2646  .rs  .rs
2647  .sp  .sp
2648  .nf  .nf
2649  Last updated: 21 January 2012  Last updated: 18 February 2012
2650  Copyright (c) 1997-2012 University of Cambridge.  Copyright (c) 1997-2012 University of Cambridge.
2651  .fi  .fi
Legend:
Removed from v.903  
changed lines
  Added in v.921
webmaster@exim.org
 ViewVC Help
Powered by ViewVC 1.1.12