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

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

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

revision 760 by ph10, Tue Nov 15 17:44:38 2011 UTC revision 761 by ph10, Tue Nov 22 12:24:26 2011 UTC
# Line 153  When the compiled JIT code runs, it need Line 153  When the compiled JIT code runs, it need
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
# Line 217  is non-NULL and points to a \fBpcre_extr Line 223  is non-NULL and points to a \fBpcre_extr
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
# Line 253  callback. Line 327  callback.
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
# Line 263  Cambridge CB2 3QH, England. Line 337  Cambridge CB2 3QH, England.
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

Legend:
Removed from v.760  
changed lines
  Added in v.761

  ViewVC Help
Powered by ViewVC 1.1.5