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

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

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

revision 479 by ph10, Wed Jul 9 11:03:07 2008 UTC revision 480 by ph10, Sun Jan 3 17:29:59 2010 UTC
# Line 17  the recursive call would immediately be Line 17  the recursive call would immediately be
17  current call (a "tail recursion"), the function is just restarted instead.  current call (a "tail recursion"), the function is just restarted instead.
18  .P  .P
19  The \fBpcre_dfa_exec()\fP function operates in an entirely different way, and  The \fBpcre_dfa_exec()\fP function operates in an entirely different way, and
20  hardly uses recursion at all. The limit on its complexity is the amount of  uses recursion only when there is a regular expression recursion or subroutine
21  workspace it is given. The comments that follow do NOT apply to  call in the pattern. This includes the processing of assertion and "once-only"
22  \fBpcre_dfa_exec()\fP; they are relevant only for \fBpcre_exec()\fP.  subpatterns, which are handled like subroutine calls. Normally, these are never
23  .P  very deep, and the limit on the complexity of \fBpcre_dfa_exec()\fP is
24  You can set limits on the number of times that \fBmatch()\fP is called, both in  controlled by the amount of workspace it is given. However, it is possible to
25  total and recursively. If the limit is exceeded, an error occurs. For details,  write patterns with runaway infinite recursions; such patterns will cause
26  see the  \fBpcre_dfa_exec()\fP to run out of stack. At present, there is no protection
27  .\" HTML <a href="pcreapi.html#extradata">  against this.
 .\" </a>  
 section on extra data for \fBpcre_exec()\fP  
 .\"  
 in the  
 .\" HREF  
 \fBpcreapi\fP  
 .\"  
 documentation.  
28  .P  .P
29    The comments that follow do NOT apply to \fBpcre_dfa_exec()\fP; they are
30    relevant only for \fBpcre_exec()\fP.
31    .
32    .
33    .SS "Reducing \fBpcre_exec()\fP's stack usage"
34    .rs
35    .sp
36  Each time that \fBmatch()\fP is actually called recursively, it uses memory  Each time that \fBmatch()\fP is actually called recursively, it uses memory
37  from the process stack. For certain kinds of pattern and data, very large  from the process stack. For certain kinds of pattern and data, very large
38  amounts of stack may be needed, despite the recognition of "tail recursion".  amounts of stack may be needed, despite the recognition of "tail recursion".
# Line 65  This example shows that one way of avoid Line 64  This example shows that one way of avoid
64  subject strings is to write repeated parenthesized subpatterns to match more  subject strings is to write repeated parenthesized subpatterns to match more
65  than one character whenever possible.  than one character whenever possible.
66  .  .
67  .SS "Compiling PCRE to use heap instead of stack"  .
68    .SS "Compiling PCRE to use heap instead of stack for \fBpcre_exec()\fP"
69  .rs  .rs
70  .sp  .sp
71  In environments where stack memory is constrained, you might want to compile  In environments where stack memory is constrained, you might want to compile
72  PCRE to use heap memory instead of stack for remembering back-up points. This  PCRE to use heap memory instead of stack for remembering back-up points when
73  makes it run a lot more slowly, however. Details of how to do this are given in  \fBpcre_exec()\fP is running. This makes it run a lot more slowly, however.
74  the  Details of how to do this are given in the
75  .\" HREF  .\" HREF
76  \fBpcrebuild\fP  \fBpcrebuild\fP
77  .\"  .\"
# Line 83  cause PCRE to use your own functions. Si Line 83  cause PCRE to use your own functions. Si
83  same, and are always freed in reverse order, it may be possible to implement  same, and are always freed in reverse order, it may be possible to implement
84  customized memory handlers that are more efficient than the standard functions.  customized memory handlers that are more efficient than the standard functions.
85  .  .
86  .SS "Limiting PCRE's stack usage"  .
87    .SS "Limiting \fBpcre_exec()\fP's stack usage"
88  .rs  .rs
89  .sp  .sp
90  PCRE has an internal counter that can be used to limit the depth of recursion,  You can set limits on the number of times that \fBmatch()\fP is called, both in
91  and thus cause \fBpcre_exec()\fP to give an error code before it runs out of  total and recursively. If a limit is exceeded, \fBpcre_exec()\fP returns an
92  stack. By default, the limit is very large, and unlikely ever to operate. It  error code. Setting suitable limits should prevent it from running out of
93  can be changed when PCRE is built, and it can also be set when  stack. The default values of the limits are very large, and unlikely ever to
94    operate. They can be changed when PCRE is built, and they can also be set when
95  \fBpcre_exec()\fP is called. For details of these interfaces, see the  \fBpcre_exec()\fP is called. For details of these interfaces, see the
96  .\" HREF  .\" HREF
97  \fBpcrebuild\fP  \fBpcrebuild\fP
98  .\"  .\"
99  and  documentation and the
100    .\" HTML <a href="pcreapi.html#extradata">
101    .\" </a>
102    section on extra data for \fBpcre_exec()\fP
103    .\"
104    in the
105  .\" HREF  .\" HREF
106  \fBpcreapi\fP  \fBpcreapi\fP
107  .\"  .\"
# Line 103  documentation. Line 110  documentation.
110  As a very rough rule of thumb, you should reckon on about 500 bytes per  As a very rough rule of thumb, you should reckon on about 500 bytes per
111  recursion. Thus, if you want to limit your stack usage to 8Mb, you  recursion. Thus, if you want to limit your stack usage to 8Mb, you
112  should set the limit at 16000 recursions. A 64Mb stack, on the other hand, can  should set the limit at 16000 recursions. A 64Mb stack, on the other hand, can
113  support around 128000 recursions. The \fBpcretest\fP test program has a command  support around 128000 recursions.
114  line option (\fB-S\fP) that can be used to increase the size of its stack.  .P
115    In Unix-like environments, the \fBpcretest\fP test program has a command line
116    option (\fB-S\fP) that can be used to increase the size of its stack. As long
117    as the stack is large enough, another option (\fB-M\fP) can be used to find the
118    smallest limits that allow a particular pattern to match a given subject
119    string. This is done by calling \fBpcre_exec()\fP repeatedly with different
120    limits.
121    .
122  .  .
123  .SS "Changing stack size in Unix-like systems"  .SS "Changing stack size in Unix-like systems"
124  .rs  .rs
# Line 129  This reads the current limits (soft and Line 143  This reads the current limits (soft and
143  attempts to increase the soft limit to 100Mb using \fBsetrlimit()\fP. You must  attempts to increase the soft limit to 100Mb using \fBsetrlimit()\fP. You must
144  do this before calling \fBpcre_exec()\fP.  do this before calling \fBpcre_exec()\fP.
145  .  .
146    .
147  .SS "Changing stack size in Mac OS X"  .SS "Changing stack size in Mac OS X"
148  .rs  .rs
149  .sp  .sp
# Line 155  Cambridge CB2 3QH, England. Line 170  Cambridge CB2 3QH, England.
170  .rs  .rs
171  .sp  .sp
172  .nf  .nf
173  Last updated: 09 July 2008  Last updated: 03 January 2010
174  Copyright (c) 1997-2008 University of Cambridge.  Copyright (c) 1997-2010 University of Cambridge.
175  .fi  .fi
Legend:
Removed from v.479  
changed lines
  Added in v.480
  ViewVC Help
Powered by ViewVC 1.1.5