[Pcre-svn] [901] code/trunk: More tidies and documentation f…

Top Page
Delete this message
Author: Subversion repository
Date:  
To: pcre-svn
Subject: [Pcre-svn] [901] code/trunk: More tidies and documentation for stack frame measurement .
Revision: 901
          http://vcs.pcre.org/viewvc?view=rev&revision=901
Author:   ph10
Date:     2012-01-21 15:47:59 +0000 (Sat, 21 Jan 2012)


Log Message:
-----------
More tidies and documentation for stack frame measurement.

Modified Paths:
--------------
    code/trunk/doc/pcreapi.3
    code/trunk/doc/pcrestack.3
    code/trunk/pcre_exec.c
    code/trunk/pcretest.c


Modified: code/trunk/doc/pcreapi.3
===================================================================
--- code/trunk/doc/pcreapi.3    2012-01-20 15:20:54 UTC (rev 900)
+++ code/trunk/doc/pcreapi.3    2012-01-21 15:47:59 UTC (rev 901)
@@ -2413,6 +2413,32 @@
 will yield PCRE_ERROR_NOMATCH.
 .
 .
+.SH "OBTAINING AN ESTIMATE OF STACK USAGE"
+.rs
+.sp
+Matching certain patterns using \fBpcre_exec()\fP can use a lot of process
+stack, which in certain environments can be rather limited in size. Some users 
+find it helpful to have an estimate of the amount of stack that is used by 
+\fBpcre_exec()\fP, to help them set recursion limits, as described in the
+.\" HREF
+\fBpcrestack\fP
+.\"
+documentation. The estimate that is output by \fBpcretest\fP when called with 
+the \fB-m\fP and \fB-C\fP options is obtained by calling \fBpcre_exec\fP with 
+the values NULL, NULL, NULL, -999, and -999 for its first five arguments.
+.P
+Normally, if its first argument is NULL, \fBpcre_exec()\fP immediately returns
+the negative error code PCRE_ERROR_NULL, but with this special combination of
+arguments, it returns instead a negative number whose absolute value is the
+approximate stack frame size in bytes. (A negative number is used so that it is
+clear that no match has happened.) The value is approximate because in some
+cases, recursive calls to \fBpcre_exec()\fP occur when there are one or two 
+additional variables on the stack.
+.P
+If PCRE has been compiled to use the heap instead of the stack for recursion, 
+the value returned is the size of each block that is obtained from the heap.
+.
+.
 .\" HTML <a name="dfamatch"></a>
 .SH "MATCHING A PATTERN: THE ALTERNATIVE FUNCTION"
 .rs
@@ -2618,6 +2644,6 @@
 .rs
 .sp
 .nf
-Last updated: 17 January 2012
+Last updated: 21 January 2012
 Copyright (c) 1997-2012 University of Cambridge.
 .fi


Modified: code/trunk/doc/pcrestack.3
===================================================================
--- code/trunk/doc/pcrestack.3    2012-01-20 15:20:54 UTC (rev 900)
+++ code/trunk/doc/pcrestack.3    2012-01-21 15:47:59 UTC (rev 901)
@@ -123,9 +123,9 @@
 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.
+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
 In Unix-like environments, the \fBpcretest\fP test program has a command line
 option (\fB-S\fP) that can be used to increase the size of its stack. As long
@@ -135,6 +135,31 @@
 limits.
 .
 .
+.SS "Obtaining an estimate of stack usage"
+.rs
+.sp
+The actual amount of stack used per recursion can vary quite a lot, depending
+on the compiler that was used to build PCRE and the optimization or debugging
+options that were set for it. The rule of thumb value of 500 bytes mentioned 
+above may be larger or smaller than what is actually needed. A better 
+approximation can be obtained by running this command:
+.sp
+  pcretest -m -C
+.sp
+The \fB-C\fP option causes \fBpcretest\fP to output information about the 
+options with which PCRE was compiled. When \fB-m\fP is also given (before 
+\fB-C\fP), information about stack use is given in a line like this:
+.sp
+  Match recursion uses stack: approximate frame size = 640 bytes
+.sp      
+The value is approximate because some recursions need a bit more (up to perhaps 
+16 more bytes).
+.P
+If the above command is given when PCRE is compiled to use the heap instead of 
+the stack for recursion, the value that is output is the size of each block 
+that is obtained from the heap. 
+.
+.
 .SS "Changing stack size in Unix-like systems"
 .rs
 .sp
@@ -185,6 +210,6 @@
 .rs
 .sp
 .nf
-Last updated: 10 January 2012
+Last updated: 21 January 2012
 Copyright (c) 1997-2012 University of Cambridge.
 .fi


Modified: code/trunk/pcre_exec.c
===================================================================
--- code/trunk/pcre_exec.c    2012-01-20 15:20:54 UTC (rev 900)
+++ code/trunk/pcre_exec.c    2012-01-21 15:47:59 UTC (rev 901)
@@ -619,7 +619,7 @@
 /* There is a special fudge for calling match() in a way that causes it to 
 measure the size of its basic stack frame when the stack is being used for
 recursion. The second argument (ecode) being NULL triggers this behaviour. It
-cannot normally every be NULL. The return is the negated value of the frame
+cannot normally ever be NULL. The return is the negated value of the frame
 size. */


if (ecode == NULL)
@@ -6210,7 +6210,8 @@
/* Check for the special magic call that measures the size of the stack used
per recursive call of match(). */

-if (re == NULL && extra_data == NULL && subject == NULL && length == -1)
+if (re == NULL && extra_data == NULL && subject == NULL && length == -999 &&
+    start_offset == -999)
 #ifdef NO_RECURSE
   return -sizeof(heapframe);
 #else  


Modified: code/trunk/pcretest.c
===================================================================
--- code/trunk/pcretest.c    2012-01-20 15:20:54 UTC (rev 900)
+++ code/trunk/pcretest.c    2012-01-21 15:47:59 UTC (rev 901)
@@ -2439,7 +2439,7 @@
     printf("  Match recursion uses %s", rc? "stack" : "heap");
     if (showstore)
       { 
-      PCRE_EXEC(stack_size, NULL, NULL, NULL, -1, -1, 0, NULL, 0);
+      PCRE_EXEC(stack_size, NULL, NULL, NULL, -999, -999, 0, NULL, 0);
       printf(": %sframe size = %d bytes", rc? "approximate " : "", -stack_size); 
       }
     printf("\n");