Added bundled PCRE2 library.
This commit is contained in:
Markus Makela
202
pcre2/doc/pcre2stack.3
Normal file
202
pcre2/doc/pcre2stack.3
Normal file
@ -0,0 +1,202 @@
|
||||
.TH PCRE2STACK 3 "21 November 2014" "PCRE2 10.00"
|
||||
.SH NAME
|
||||
PCRE2 - Perl-compatible regular expressions (revised API)
|
||||
.SH "PCRE2 DISCUSSION OF STACK USAGE"
|
||||
.rs
|
||||
.sp
|
||||
When you call \fBpcre2_match()\fP, it makes use of an internal function called
|
||||
\fBmatch()\fP. This calls itself recursively at branch points in the pattern,
|
||||
in order to remember the state of the match so that it can back up and try a
|
||||
different alternative after a failure. As matching proceeds deeper and deeper
|
||||
into the tree of possibilities, the recursion depth increases. The
|
||||
\fBmatch()\fP function is also called in other circumstances, for example,
|
||||
whenever a parenthesized sub-pattern is entered, and in certain cases of
|
||||
repetition.
|
||||
.P
|
||||
Not all calls of \fBmatch()\fP increase the recursion depth; for an item such
|
||||
as a* it may be called several times at the same level, after matching
|
||||
different numbers of a's. Furthermore, in a number of cases where the result of
|
||||
the recursive call would immediately be passed back as the result of the
|
||||
current call (a "tail recursion"), the function is just restarted instead.
|
||||
.P
|
||||
Each time the internal \fBmatch()\fP function is called recursively, it uses
|
||||
memory from the process stack. For certain kinds of pattern and data, very
|
||||
large amounts of stack may be needed, despite the recognition of "tail
|
||||
recursion". Note that if PCRE2 is compiled with the -fsanitize=address option
|
||||
of the GCC compiler, the stack requirements are greatly increased.
|
||||
.P
|
||||
The above comments apply when \fBpcre2_match()\fP is run in its normal
|
||||
interpretive manner. If the compiled pattern was processed by
|
||||
\fBpcre2_jit_compile()\fP, and just-in-time compiling was successful, and the
|
||||
options passed to \fBpcre2_match()\fP were not incompatible, the matching
|
||||
process uses the JIT-compiled code instead of the \fBmatch()\fP function. In
|
||||
this case, the memory requirements are handled entirely differently. See the
|
||||
.\" HREF
|
||||
\fBpcre2jit\fP
|
||||
.\"
|
||||
documentation for details.
|
||||
.P
|
||||
The \fBpcre2_dfa_match()\fP function operates in a different way to
|
||||
\fBpcre2_match()\fP, and uses recursion only when there is a regular expression
|
||||
recursion or subroutine call in the pattern. This includes the processing of
|
||||
assertion and "once-only" subpatterns, which are handled like subroutine calls.
|
||||
Normally, these are never very deep, and the limit on the complexity of
|
||||
\fBpcre2_dfa_match()\fP is controlled by the amount of workspace it is given.
|
||||
However, it is possible to write patterns with runaway infinite recursions;
|
||||
such patterns will cause \fBpcre2_dfa_match()\fP to run out of stack. At
|
||||
present, there is no protection against this.
|
||||
.P
|
||||
The comments that follow do NOT apply to \fBpcre2_dfa_match()\fP; they are
|
||||
relevant only for \fBpcre2_match()\fP without the JIT optimization.
|
||||
.
|
||||
.
|
||||
.SS "Reducing \fBpcre2_match()\fP's stack usage"
|
||||
.rs
|
||||
.sp
|
||||
You can often reduce the amount of recursion, and therefore the
|
||||
amount of stack used, by modifying the pattern that is being matched. Consider,
|
||||
for example, this pattern:
|
||||
.sp
|
||||
([^<]|<(?!inet))+
|
||||
.sp
|
||||
It matches from wherever it starts until it encounters "<inet" or the end of
|
||||
the data, and is the kind of pattern that might be used when processing an XML
|
||||
file. Each iteration of the outer parentheses matches either one character that
|
||||
is not "<" or a "<" that is not followed by "inet". However, each time a
|
||||
parenthesis is processed, a recursion occurs, so this formulation uses a stack
|
||||
frame for each matched character. For a long string, a lot of stack is
|
||||
required. Consider now this rewritten pattern, which matches exactly the same
|
||||
strings:
|
||||
.sp
|
||||
([^<]++|<(?!inet))+
|
||||
.sp
|
||||
This uses very much less stack, because runs of characters that do not contain
|
||||
"<" are "swallowed" in one item inside the parentheses. Recursion happens only
|
||||
when a "<" character that is not followed by "inet" is encountered (and we
|
||||
assume this is relatively rare). A possessive quantifier is used to stop any
|
||||
backtracking into the runs of non-"<" characters, but that is not related to
|
||||
stack usage.
|
||||
.P
|
||||
This example shows that one way of avoiding stack problems when matching long
|
||||
subject strings is to write repeated parenthesized subpatterns to match more
|
||||
than one character whenever possible.
|
||||
.
|
||||
.
|
||||
.SS "Compiling PCRE2 to use heap instead of stack for \fBpcre2_match()\fP"
|
||||
.rs
|
||||
.sp
|
||||
In environments where stack memory is constrained, you might want to compile
|
||||
PCRE2 to use heap memory instead of stack for remembering back-up points when
|
||||
\fBpcre2_match()\fP is running. This makes it run more slowly, however. Details
|
||||
of how to do this are given in the
|
||||
.\" HREF
|
||||
\fBpcre2build\fP
|
||||
.\"
|
||||
documentation. When built in this way, instead of using the stack, PCRE2
|
||||
gets memory for remembering backup points from the heap. By default, the memory
|
||||
is obtained by calling the system \fBmalloc()\fP function, but you can arrange
|
||||
to supply your own memory management function. For details, see the section
|
||||
entitled
|
||||
.\" HTML <a href="pcre2api.html#matchcontext">
|
||||
.\" </a>
|
||||
"The match context"
|
||||
.\"
|
||||
in the
|
||||
.\" HREF
|
||||
\fBpcre2api\fP
|
||||
.\"
|
||||
documentation. Since the block sizes are always the same, it may be possible to
|
||||
implement customized a memory handler that is more efficient than the standard
|
||||
function. The memory blocks obtained for this purpose are retained and re-used
|
||||
if possible while \fBpcre2_match()\fP is running. They are all freed just
|
||||
before it exits.
|
||||
.
|
||||
.
|
||||
.SS "Limiting \fBpcre2_match()\fP's stack usage"
|
||||
.rs
|
||||
.sp
|
||||
You can set limits on the number of times the internal \fBmatch()\fP function
|
||||
is called, both in total and recursively. If a limit is exceeded,
|
||||
\fBpcre2_match()\fP returns an error code. Setting suitable limits should
|
||||
prevent it from running out of stack. The default values of the limits are very
|
||||
large, and unlikely ever to operate. They can be changed when PCRE2 is built,
|
||||
and they can also be set when \fBpcre2_match()\fP is called. For details of
|
||||
these interfaces, see the
|
||||
.\" HREF
|
||||
\fBpcre2build\fP
|
||||
.\"
|
||||
documentation and the section entitled
|
||||
.\" HTML <a href="pcre2api.html#matchcontext">
|
||||
.\" </a>
|
||||
"The match context"
|
||||
.\"
|
||||
in the
|
||||
.\" HREF
|
||||
\fBpcre2api\fP
|
||||
.\"
|
||||
documentation.
|
||||
.P
|
||||
As a very rough rule of thumb, you should reckon on about 500 bytes per
|
||||
recursion. Thus, if you want to limit your stack usage to 8Mb, you should set
|
||||
the limit at 16000 recursions. A 64Mb stack, on the other hand, can support
|
||||
around 128000 recursions.
|
||||
.P
|
||||
The \fBpcre2test\fP test program has a modifier called "find_limits" which, if
|
||||
applied to a subject line, causes it to find the smallest limits that allow a a
|
||||
pattern to match. This is done by calling \fBpcre2_match()\fP repeatedly with
|
||||
different limits.
|
||||
.
|
||||
.
|
||||
.SS "Changing stack size in Unix-like systems"
|
||||
.rs
|
||||
.sp
|
||||
In Unix-like environments, there is not often a problem with the stack unless
|
||||
very long strings are involved, though the default limit on stack size varies
|
||||
from system to system. Values from 8Mb to 64Mb are common. You can find your
|
||||
default limit by running the command:
|
||||
.sp
|
||||
ulimit -s
|
||||
.sp
|
||||
Unfortunately, the effect of running out of stack is often SIGSEGV, though
|
||||
sometimes a more explicit error message is given. You can normally increase the
|
||||
limit on stack size by code such as this:
|
||||
.sp
|
||||
struct rlimit rlim;
|
||||
getrlimit(RLIMIT_STACK, &rlim);
|
||||
rlim.rlim_cur = 100*1024*1024;
|
||||
setrlimit(RLIMIT_STACK, &rlim);
|
||||
.sp
|
||||
This reads the current limits (soft and hard) using \fBgetrlimit()\fP, then
|
||||
attempts to increase the soft limit to 100Mb using \fBsetrlimit()\fP. You must
|
||||
do this before calling \fBpcre2_match()\fP.
|
||||
.
|
||||
.
|
||||
.SS "Changing stack size in Mac OS X"
|
||||
.rs
|
||||
.sp
|
||||
Using \fBsetrlimit()\fP, as described above, should also work on Mac OS X. It
|
||||
is also possible to set a stack size when linking a program. There is a
|
||||
discussion about stack sizes in Mac OS X at this web site:
|
||||
.\" HTML <a href="http://developer.apple.com/qa/qa2005/qa1419.html">
|
||||
.\" </a>
|
||||
http://developer.apple.com/qa/qa2005/qa1419.html.
|
||||
.\"
|
||||
.
|
||||
.
|
||||
.SH AUTHOR
|
||||
.rs
|
||||
.sp
|
||||
.nf
|
||||
Philip Hazel
|
||||
University Computing Service
|
||||
Cambridge, England.
|
||||
.fi
|
||||
.
|
||||
.
|
||||
.SH REVISION
|
||||
.rs
|
||||
.sp
|
||||
.nf
|
||||
Last updated: 21 November 2014
|
||||
Copyright (c) 1997-2014 University of Cambridge.
|
||||
.fi
|
||||
Reference in New Issue
Block a user