| 153 |
By default, it uses 32K on the machine stack. However, some large or |
By default, it uses 32K on the machine stack. However, some large or |
| 154 |
complicated patterns need more than this. The error PCRE_ERROR_JIT_STACKLIMIT |
complicated patterns need more than this. The error PCRE_ERROR_JIT_STACKLIMIT |
| 155 |
is given when there is not enough stack. Three functions are provided for |
is given when there is not enough stack. Three functions are provided for |
| 156 |
managing blocks of memory for use as JIT stacks. |
managing blocks of memory for use as JIT stacks. There is further discussion |
| 157 |
|
about the use of JIT stacks in the section entitled |
| 158 |
|
.\" HTML <a href="#stackcontrol"> |
| 159 |
|
.\" </a> |
| 160 |
|
"JIT stack FAQ" |
| 161 |
|
.\" |
| 162 |
|
below. |
| 163 |
.P |
.P |
| 164 |
The \fBpcre_jit_stack_alloc()\fP function creates a JIT stack. Its arguments |
The \fBpcre_jit_stack_alloc()\fP function creates a JIT stack. Its arguments |
| 165 |
are a starting size and a maximum size, and it returns a pointer to an opaque |
are a starting size and a maximum size, and it returns a pointer to an opaque |
| 223 |
successful study with PCRE_STUDY_JIT_COMPILE. |
successful study with PCRE_STUDY_JIT_COMPILE. |
| 224 |
. |
. |
| 225 |
. |
. |
| 226 |
|
.\" HTML <a name="stackfaq"></a> |
| 227 |
|
.SH "JIT STACK FAQ" |
| 228 |
|
.rs |
| 229 |
|
.sp |
| 230 |
|
(1) Why do we need JIT stacks? |
| 231 |
|
.sp |
| 232 |
|
PCRE (and JIT) is a recursive, depth-first engine, so it needs a stack where |
| 233 |
|
the local data of the current node is pushed before checking its child nodes. |
| 234 |
|
Allocating real machine stack on some platforms is difficult. For example, the |
| 235 |
|
stack chain needs to be updated every time if we extend the stack on PowerPC. |
| 236 |
|
Although it is possible, its updating time overhead decreases performance. So |
| 237 |
|
we do the recursion in memory. |
| 238 |
|
.P |
| 239 |
|
(2) Why don't we simply allocate blocks of memory with \fBmalloc()\fP? |
| 240 |
|
.sp |
| 241 |
|
Modern operating systems have a nice feature: they can reserve an address space |
| 242 |
|
instead of allocating memory. We can safely allocate memory pages inside this |
| 243 |
|
address space, so the stack could grow without moving memory data (this is |
| 244 |
|
important because of pointers). Thus we can allocate 1M address space, and use |
| 245 |
|
only a single memory page (usually 4K) if that is enough. However, we can still |
| 246 |
|
grow up to 1M anytime if needed. |
| 247 |
|
.P |
| 248 |
|
(3) Who "owns" a JIT stack? |
| 249 |
|
.sp |
| 250 |
|
The owner of the stack is the user program, not the JIT studied pattern or |
| 251 |
|
anything else. The user program must ensure that if a stack is used by |
| 252 |
|
\fBpcre_exec()\fP, (that is, it is assigned to the pattern currently running), |
| 253 |
|
that stack must not be used by any other threads (to avoid overwriting the same |
| 254 |
|
memory area). The best practice for multithreaded programs is to allocate a |
| 255 |
|
stack for each thread, and return this stack through the JIT callback function. |
| 256 |
|
.P |
| 257 |
|
(4) When should a JIT stack be freed? |
| 258 |
|
.sp |
| 259 |
|
You can free a JIT stack at any time, as long as it will not be used by |
| 260 |
|
\fBpcre_exec()\fP again. When you assign the stack to a pattern, only a pointer |
| 261 |
|
is set. There is no reference counting or any other magic. You can free the |
| 262 |
|
patterns and stacks in any order, anytime. Just \fIdo not\fP call |
| 263 |
|
\fBpcre_exec()\fP with a pattern pointing to an already freed stack, as that |
| 264 |
|
will cause SEGFAULT. (Also, do not free a stack currently used by |
| 265 |
|
\fBpcre_exec()\fP in another thread). You can also replace the stack for a |
| 266 |
|
pattern at any time. You can even free the previous stack before assigning a |
| 267 |
|
replacement. |
| 268 |
|
.P |
| 269 |
|
(5) Should I allocate/free a stack every time before/after calling |
| 270 |
|
\fBpcre_exec()\fP? |
| 271 |
|
.sp |
| 272 |
|
No, because this is too costly in terms of resources. However, you could |
| 273 |
|
implement some clever idea which release the stack if it is not used in let's |
| 274 |
|
say two minutes. The JIT callback can help to achive this without keeping a |
| 275 |
|
list of the currently JIT studied patterns. |
| 276 |
|
.P |
| 277 |
|
(6) OK, the stack is for long term memory allocation. But what happens if a |
| 278 |
|
pattern causes stack overflow with a stack of 1M? Is that 1M kept until the |
| 279 |
|
stack is freed? |
| 280 |
|
.sp |
| 281 |
|
Especially on embedded sytems, it might be a good idea to release |
| 282 |
|
memory sometimes without freeing the stack. There is no API for this at the |
| 283 |
|
moment. Probably a function call which returns with the currently allocated |
| 284 |
|
memory for any stack and another which allows releasing memory (shrinking the |
| 285 |
|
stack) would be a good idea if someone needs this. |
| 286 |
|
.P |
| 287 |
|
(7) This is too much of a headache. Isn't there any better solution for JIT |
| 288 |
|
stack handling? |
| 289 |
|
.sp |
| 290 |
|
No, thanks to Windows. If POSIX threads were used everywhere, we could throw |
| 291 |
|
out this complicated API. |
| 292 |
|
. |
| 293 |
|
. |
| 294 |
.SH "EXAMPLE CODE" |
.SH "EXAMPLE CODE" |
| 295 |
.rs |
.rs |
| 296 |
.sp |
.sp |
| 327 |
.rs |
.rs |
| 328 |
.sp |
.sp |
| 329 |
.nf |
.nf |
| 330 |
Philip Hazel |
Philip Hazel (FAQ by Zoltan Herczeg) |
| 331 |
University Computing Service |
University Computing Service |
| 332 |
Cambridge CB2 3QH, England. |
Cambridge CB2 3QH, England. |
| 333 |
.fi |
.fi |
| 337 |
.rs |
.rs |
| 338 |
.sp |
.sp |
| 339 |
.nf |
.nf |
| 340 |
Last updated: 15 November 2011 |
Last updated: 22 November 2011 |
| 341 |
Copyright (c) 1997-2011 University of Cambridge. |
Copyright (c) 1997-2011 University of Cambridge. |
| 342 |
.fi |
.fi |
Parent Directory
| 
Revision Log
| 
Patch