Annotation of embedaddon/pcre/doc/pcrejit.3, revision 1.1.1.4
1.1.1.4 ! misho 1: .TH PCREJIT 3 "17 March 2013" "PCRE 8.33"
1.1 misho 2: .SH NAME
3: PCRE - Perl-compatible regular expressions
4: .SH "PCRE JUST-IN-TIME COMPILER SUPPORT"
5: .rs
6: .sp
7: Just-in-time compiling is a heavyweight optimization that can greatly speed up
8: pattern matching. However, it comes at the cost of extra processing before the
9: match is performed. Therefore, it is of most benefit when the same pattern is
1.1.1.2 misho 10: going to be matched many times. This does not necessarily mean many calls of a
11: matching function; if the pattern is not anchored, matching attempts may take
12: place many times at various positions in the subject, even for a single call.
13: Therefore, if the subject string is very long, it may still pay to use JIT for
14: one-off matches.
15: .P
16: JIT support applies only to the traditional Perl-compatible matching function.
17: It does not apply when the DFA matching function is being used. The code for
18: this support was written by Zoltan Herczeg.
19: .
20: .
1.1.1.4 ! misho 21: .SH "8-BIT, 16-BIT AND 32-BIT SUPPORT"
1.1.1.2 misho 22: .rs
23: .sp
1.1.1.4 ! misho 24: JIT support is available for all of the 8-bit, 16-bit and 32-bit PCRE
! 25: libraries. To keep this documentation simple, only the 8-bit interface is
! 26: described in what follows. If you are using the 16-bit library, substitute the
! 27: 16-bit functions and 16-bit structures (for example, \fIpcre16_jit_stack\fP
! 28: instead of \fIpcre_jit_stack\fP). If you are using the 32-bit library,
! 29: substitute the 32-bit functions and 32-bit structures (for example,
! 30: \fIpcre32_jit_stack\fP instead of \fIpcre_jit_stack\fP).
1.1 misho 31: .
32: .
33: .SH "AVAILABILITY OF JIT SUPPORT"
34: .rs
35: .sp
36: JIT support is an optional feature of PCRE. The "configure" option --enable-jit
37: (or equivalent CMake option) must be set when PCRE is built if you want to use
38: JIT. The support is limited to the following hardware platforms:
39: .sp
40: ARM v5, v7, and Thumb2
41: Intel x86 32-bit and 64-bit
42: MIPS 32-bit
1.1.1.2 misho 43: Power PC 32-bit and 64-bit
1.1.1.4 ! misho 44: SPARC 32-bit (experimental)
1.1 misho 45: .sp
1.1.1.3 misho 46: If --enable-jit is set on an unsupported platform, compilation fails.
1.1 misho 47: .P
48: A program that is linked with PCRE 8.20 or later can tell if JIT support is
49: available by calling \fBpcre_config()\fP with the PCRE_CONFIG_JIT option. The
50: result is 1 when JIT is available, and 0 otherwise. However, a simple program
1.1.1.4 ! misho 51: does not need to check this in order to use JIT. The normal API is implemented
! 52: in a way that falls back to the interpretive code if JIT is not available. For
! 53: programs that need the best possible performance, there is also a "fast path"
! 54: API that is JIT-specific.
1.1 misho 55: .P
56: If your program may sometimes be linked with versions of PCRE that are older
57: than 8.20, but you want to use JIT when it is available, you can test
58: the values of PCRE_MAJOR and PCRE_MINOR, or the existence of a JIT macro such
59: as PCRE_CONFIG_JIT, for compile-time control of your code.
60: .
61: .
62: .SH "SIMPLE USE OF JIT"
63: .rs
64: .sp
65: You have to do two things to make use of the JIT support in the simplest way:
66: .sp
67: (1) Call \fBpcre_study()\fP with the PCRE_STUDY_JIT_COMPILE option for
68: each compiled pattern, and pass the resulting \fBpcre_extra\fP block to
69: \fBpcre_exec()\fP.
70: .sp
71: (2) Use \fBpcre_free_study()\fP to free the \fBpcre_extra\fP block when it is
1.1.1.4 ! misho 72: no longer needed, instead of just freeing it yourself. This ensures that
! 73: any JIT data is also freed.
1.1 misho 74: .sp
75: For a program that may be linked with pre-8.20 versions of PCRE, you can insert
76: .sp
77: #ifndef PCRE_STUDY_JIT_COMPILE
78: #define PCRE_STUDY_JIT_COMPILE 0
79: #endif
80: .sp
81: so that no option is passed to \fBpcre_study()\fP, and then use something like
82: this to free the study data:
83: .sp
84: #ifdef PCRE_CONFIG_JIT
85: pcre_free_study(study_ptr);
86: #else
87: pcre_free(study_ptr);
88: #endif
89: .sp
1.1.1.3 misho 90: PCRE_STUDY_JIT_COMPILE requests the JIT compiler to generate code for complete
91: matches. If you want to run partial matches using the PCRE_PARTIAL_HARD or
92: PCRE_PARTIAL_SOFT options of \fBpcre_exec()\fP, you should set one or both of
93: the following options in addition to, or instead of, PCRE_STUDY_JIT_COMPILE
94: when you call \fBpcre_study()\fP:
95: .sp
96: PCRE_STUDY_JIT_PARTIAL_HARD_COMPILE
97: PCRE_STUDY_JIT_PARTIAL_SOFT_COMPILE
98: .sp
99: The JIT compiler generates different optimized code for each of the three
100: modes (normal, soft partial, hard partial). When \fBpcre_exec()\fP is called,
101: the appropriate code is run if it is available. Otherwise, the pattern is
102: matched using interpretive code.
103: .P
1.1 misho 104: In some circumstances you may need to call additional functions. These are
105: described in the section entitled
106: .\" HTML <a href="#stackcontrol">
107: .\" </a>
108: "Controlling the JIT stack"
109: .\"
110: below.
111: .P
1.1.1.3 misho 112: If JIT support is not available, PCRE_STUDY_JIT_COMPILE etc. are ignored, and
113: no JIT data is created. Otherwise, the compiled pattern is passed to the JIT
114: compiler, which turns it into machine code that executes much faster than the
115: normal interpretive code. When \fBpcre_exec()\fP is passed a \fBpcre_extra\fP
116: block containing a pointer to JIT code of the appropriate mode (normal or
117: hard/soft partial), it obeys that code instead of running the interpreter. The
118: result is identical, but the compiled JIT code runs much faster.
1.1 misho 119: .P
120: There are some \fBpcre_exec()\fP options that are not supported for JIT
121: execution. There are also some pattern items that JIT cannot handle. Details
122: are given below. In both cases, execution automatically falls back to the
1.1.1.3 misho 123: interpretive code. If you want to know whether JIT was actually used for a
124: particular match, you should arrange for a JIT callback function to be set up
125: as described in the section entitled
126: .\" HTML <a href="#stackcontrol">
127: .\" </a>
128: "Controlling the JIT stack"
129: .\"
130: below, even if you do not need to supply a non-default JIT stack. Such a
131: callback function is called whenever JIT code is about to be obeyed. If the
132: execution options are not right for JIT execution, the callback function is not
133: obeyed.
1.1 misho 134: .P
135: If the JIT compiler finds an unsupported item, no JIT data is generated. You
136: can find out if JIT execution is available after studying a pattern by calling
137: \fBpcre_fullinfo()\fP with the PCRE_INFO_JIT option. A result of 1 means that
138: JIT compilation was successful. A result of 0 means that JIT support is not
1.1.1.3 misho 139: available, or the pattern was not studied with PCRE_STUDY_JIT_COMPILE etc., or
140: the JIT compiler was not able to handle the pattern.
1.1 misho 141: .P
142: Once a pattern has been studied, with or without JIT, it can be used as many
143: times as you like for matching different subject strings.
144: .
145: .
146: .SH "UNSUPPORTED OPTIONS AND PATTERN ITEMS"
147: .rs
148: .sp
149: The only \fBpcre_exec()\fP options that are supported for JIT execution are
1.1.1.4 ! misho 150: PCRE_NO_UTF8_CHECK, PCRE_NO_UTF16_CHECK, PCRE_NO_UTF32_CHECK, PCRE_NOTBOL,
! 151: PCRE_NOTEOL, PCRE_NOTEMPTY, PCRE_NOTEMPTY_ATSTART, PCRE_PARTIAL_HARD, and
! 152: PCRE_PARTIAL_SOFT.
! 153: .P
! 154: The only unsupported pattern items are \eC (match a single data unit) when
! 155: running in a UTF mode, and a callout immediately before an assertion condition
! 156: in a conditional group.
1.1 misho 157: .
158: .
159: .SH "RETURN VALUES FROM JIT EXECUTION"
160: .rs
161: .sp
162: When a pattern is matched using JIT execution, the return values are the same
163: as those given by the interpretive \fBpcre_exec()\fP code, with the addition of
164: one new error code: PCRE_ERROR_JIT_STACKLIMIT. This means that the memory used
165: for the JIT stack was insufficient. See
166: .\" HTML <a href="#stackcontrol">
167: .\" </a>
168: "Controlling the JIT stack"
169: .\"
170: below for a discussion of JIT stack usage. For compatibility with the
171: interpretive \fBpcre_exec()\fP code, no more than two-thirds of the
172: \fIovector\fP argument is used for passing back captured substrings.
173: .P
174: The error code PCRE_ERROR_MATCHLIMIT is returned by the JIT code if searching a
175: very large pattern tree goes on for too long, as it is in the same circumstance
176: when JIT is not used, but the details of exactly what is counted are not the
177: same. The PCRE_ERROR_RECURSIONLIMIT error code is never returned by JIT
178: execution.
179: .
180: .
181: .SH "SAVING AND RESTORING COMPILED PATTERNS"
182: .rs
183: .sp
184: The code that is generated by the JIT compiler is architecture-specific, and is
185: also position dependent. For those reasons it cannot be saved (in a file or
186: database) and restored later like the bytecode and other data of a compiled
187: pattern. Saving and restoring compiled patterns is not something many people
188: do. More detail about this facility is given in the
189: .\" HREF
190: \fBpcreprecompile\fP
191: .\"
192: documentation. It should be possible to run \fBpcre_study()\fP on a saved and
193: restored pattern, and thereby recreate the JIT data, but because JIT
194: compilation uses significant resources, it is probably not worth doing this;
195: you might as well recompile the original pattern.
196: .
197: .
198: .\" HTML <a name="stackcontrol"></a>
199: .SH "CONTROLLING THE JIT STACK"
200: .rs
201: .sp
202: When the compiled JIT code runs, it needs a block of memory to use as a stack.
203: By default, it uses 32K on the machine stack. However, some large or
204: complicated patterns need more than this. The error PCRE_ERROR_JIT_STACKLIMIT
205: is given when there is not enough stack. Three functions are provided for
206: managing blocks of memory for use as JIT stacks. There is further discussion
207: about the use of JIT stacks in the section entitled
208: .\" HTML <a href="#stackcontrol">
209: .\" </a>
210: "JIT stack FAQ"
211: .\"
212: below.
213: .P
214: The \fBpcre_jit_stack_alloc()\fP function creates a JIT stack. Its arguments
215: are a starting size and a maximum size, and it returns a pointer to an opaque
216: structure of type \fBpcre_jit_stack\fP, or NULL if there is an error. The
217: \fBpcre_jit_stack_free()\fP function can be used to free a stack that is no
218: longer needed. (For the technically minded: the address space is allocated by
219: mmap or VirtualAlloc.)
220: .P
221: JIT uses far less memory for recursion than the interpretive code,
222: and a maximum stack size of 512K to 1M should be more than enough for any
223: pattern.
224: .P
225: The \fBpcre_assign_jit_stack()\fP function specifies which stack JIT code
226: should use. Its arguments are as follows:
227: .sp
228: pcre_extra *extra
229: pcre_jit_callback callback
230: void *data
231: .sp
232: The \fIextra\fP argument must be the result of studying a pattern with
1.1.1.3 misho 233: PCRE_STUDY_JIT_COMPILE etc. There are three cases for the values of the other
234: two options:
1.1 misho 235: .sp
236: (1) If \fIcallback\fP is NULL and \fIdata\fP is NULL, an internal 32K block
237: on the machine stack is used.
238: .sp
239: (2) If \fIcallback\fP is NULL and \fIdata\fP is not NULL, \fIdata\fP must be
240: a valid JIT stack, the result of calling \fBpcre_jit_stack_alloc()\fP.
241: .sp
1.1.1.3 misho 242: (3) If \fIcallback\fP is not NULL, it must point to a function that is
243: called with \fIdata\fP as an argument at the start of matching, in
244: order to set up a JIT stack. If the return from the callback
245: function is NULL, the internal 32K stack is used; otherwise the
246: return value must be a valid JIT stack, the result of calling
247: \fBpcre_jit_stack_alloc()\fP.
248: .sp
249: A callback function is obeyed whenever JIT code is about to be run; it is not
250: obeyed when \fBpcre_exec()\fP is called with options that are incompatible for
251: JIT execution. A callback function can therefore be used to determine whether a
252: match operation was executed by JIT or by the interpreter.
253: .P
254: You may safely use the same JIT stack for more than one pattern (either by
255: assigning directly or by callback), as long as the patterns are all matched
256: sequentially in the same thread. In a multithread application, if you do not
257: specify a JIT stack, or if you assign or pass back NULL from a callback, that
258: is thread-safe, because each thread has its own machine stack. However, if you
259: assign or pass back a non-NULL JIT stack, this must be a different stack for
260: each thread so that the application is thread-safe.
1.1 misho 261: .P
1.1.1.3 misho 262: Strictly speaking, even more is allowed. You can assign the same non-NULL stack
263: to any number of patterns as long as they are not used for matching by multiple
1.1 misho 264: threads at the same time. For example, you can assign the same stack to all
265: compiled patterns, and use a global mutex in the callback to wait until the
1.1.1.3 misho 266: stack is available for use. However, this is an inefficient solution, and not
267: recommended.
1.1 misho 268: .P
1.1.1.3 misho 269: This is a suggestion for how a multithreaded program that needs to set up
270: non-default JIT stacks might operate:
1.1 misho 271: .sp
272: During thread initalization
273: thread_local_var = pcre_jit_stack_alloc(...)
274: .sp
275: During thread exit
276: pcre_jit_stack_free(thread_local_var)
277: .sp
278: Use a one-line callback function
279: return thread_local_var
280: .sp
281: All the functions described in this section do nothing if JIT is not available,
282: and \fBpcre_assign_jit_stack()\fP does nothing unless the \fBextra\fP argument
283: is non-NULL and points to a \fBpcre_extra\fP block that is the result of a
1.1.1.3 misho 284: successful study with PCRE_STUDY_JIT_COMPILE etc.
1.1 misho 285: .
286: .
287: .\" HTML <a name="stackfaq"></a>
288: .SH "JIT STACK FAQ"
289: .rs
290: .sp
291: (1) Why do we need JIT stacks?
292: .sp
293: PCRE (and JIT) is a recursive, depth-first engine, so it needs a stack where
294: the local data of the current node is pushed before checking its child nodes.
295: Allocating real machine stack on some platforms is difficult. For example, the
296: stack chain needs to be updated every time if we extend the stack on PowerPC.
297: Although it is possible, its updating time overhead decreases performance. So
298: we do the recursion in memory.
299: .P
300: (2) Why don't we simply allocate blocks of memory with \fBmalloc()\fP?
301: .sp
302: Modern operating systems have a nice feature: they can reserve an address space
303: instead of allocating memory. We can safely allocate memory pages inside this
304: address space, so the stack could grow without moving memory data (this is
305: important because of pointers). Thus we can allocate 1M address space, and use
306: only a single memory page (usually 4K) if that is enough. However, we can still
307: grow up to 1M anytime if needed.
308: .P
309: (3) Who "owns" a JIT stack?
310: .sp
311: The owner of the stack is the user program, not the JIT studied pattern or
312: anything else. The user program must ensure that if a stack is used by
313: \fBpcre_exec()\fP, (that is, it is assigned to the pattern currently running),
314: that stack must not be used by any other threads (to avoid overwriting the same
315: memory area). The best practice for multithreaded programs is to allocate a
316: stack for each thread, and return this stack through the JIT callback function.
317: .P
318: (4) When should a JIT stack be freed?
319: .sp
320: You can free a JIT stack at any time, as long as it will not be used by
321: \fBpcre_exec()\fP again. When you assign the stack to a pattern, only a pointer
322: is set. There is no reference counting or any other magic. You can free the
323: patterns and stacks in any order, anytime. Just \fIdo not\fP call
324: \fBpcre_exec()\fP with a pattern pointing to an already freed stack, as that
325: will cause SEGFAULT. (Also, do not free a stack currently used by
326: \fBpcre_exec()\fP in another thread). You can also replace the stack for a
327: pattern at any time. You can even free the previous stack before assigning a
328: replacement.
329: .P
330: (5) Should I allocate/free a stack every time before/after calling
331: \fBpcre_exec()\fP?
332: .sp
333: No, because this is too costly in terms of resources. However, you could
334: implement some clever idea which release the stack if it is not used in let's
1.1.1.4 ! misho 335: say two minutes. The JIT callback can help to achieve this without keeping a
1.1 misho 336: list of the currently JIT studied patterns.
337: .P
338: (6) OK, the stack is for long term memory allocation. But what happens if a
339: pattern causes stack overflow with a stack of 1M? Is that 1M kept until the
340: stack is freed?
341: .sp
1.1.1.3 misho 342: Especially on embedded sytems, it might be a good idea to release memory
343: sometimes without freeing the stack. There is no API for this at the moment.
344: Probably a function call which returns with the currently allocated memory for
345: any stack and another which allows releasing memory (shrinking the stack) would
346: be a good idea if someone needs this.
1.1 misho 347: .P
348: (7) This is too much of a headache. Isn't there any better solution for JIT
349: stack handling?
350: .sp
351: No, thanks to Windows. If POSIX threads were used everywhere, we could throw
352: out this complicated API.
353: .
354: .
355: .SH "EXAMPLE CODE"
356: .rs
357: .sp
358: This is a single-threaded example that specifies a JIT stack without using a
359: callback.
360: .sp
361: int rc;
362: int ovector[30];
363: pcre *re;
364: pcre_extra *extra;
365: pcre_jit_stack *jit_stack;
366: .sp
367: re = pcre_compile(pattern, 0, &error, &erroffset, NULL);
368: /* Check for errors */
369: extra = pcre_study(re, PCRE_STUDY_JIT_COMPILE, &error);
370: jit_stack = pcre_jit_stack_alloc(32*1024, 512*1024);
371: /* Check for error (NULL) */
372: pcre_assign_jit_stack(extra, NULL, jit_stack);
373: rc = pcre_exec(re, extra, subject, length, 0, 0, ovector, 30);
374: /* Check results */
375: pcre_free(re);
376: pcre_free_study(extra);
377: pcre_jit_stack_free(jit_stack);
378: .sp
379: .
380: .
1.1.1.4 ! misho 381: .SH "JIT FAST PATH API"
! 382: .rs
! 383: .sp
! 384: Because the API described above falls back to interpreted execution when JIT is
! 385: not available, it is convenient for programs that are written for general use
! 386: in many environments. However, calling JIT via \fBpcre_exec()\fP does have a
! 387: performance impact. Programs that are written for use where JIT is known to be
! 388: available, and which need the best possible performance, can instead use a
! 389: "fast path" API to call JIT execution directly instead of calling
! 390: \fBpcre_exec()\fP (obviously only for patterns that have been successfully
! 391: studied by JIT).
! 392: .P
! 393: The fast path function is called \fBpcre_jit_exec()\fP, and it takes exactly
! 394: the same arguments as \fBpcre_exec()\fP, plus one additional argument that
! 395: must point to a JIT stack. The JIT stack arrangements described above do not
! 396: apply. The return values are the same as for \fBpcre_exec()\fP.
! 397: .P
! 398: When you call \fBpcre_exec()\fP, as well as testing for invalid options, a
! 399: number of other sanity checks are performed on the arguments. For example, if
! 400: the subject pointer is NULL, or its length is negative, an immediate error is
! 401: given. Also, unless PCRE_NO_UTF[8|16|32] is set, a UTF subject string is tested
! 402: for validity. In the interests of speed, these checks do not happen on the JIT
! 403: fast path, and if invalid data is passed, the result is undefined.
! 404: .P
! 405: Bypassing the sanity checks and the \fBpcre_exec()\fP wrapping can give
! 406: speedups of more than 10%.
! 407: .
! 408: .
1.1 misho 409: .SH "SEE ALSO"
410: .rs
411: .sp
412: \fBpcreapi\fP(3)
413: .
414: .
415: .SH AUTHOR
416: .rs
417: .sp
418: .nf
419: Philip Hazel (FAQ by Zoltan Herczeg)
420: University Computing Service
421: Cambridge CB2 3QH, England.
422: .fi
423: .
424: .
425: .SH REVISION
426: .rs
427: .sp
428: .nf
1.1.1.4 ! misho 429: Last updated: 17 March 2013
! 430: Copyright (c) 1997-2013 University of Cambridge.
1.1 misho 431: .fi
FreeBSD-CVSweb <freebsd-cvsweb@FreeBSD.org>
![[BACK]](/icons/cvsweb/back.gif){kind=icon}
Return to pcrejit.3 CVS log ![[TXT]](/icons/cvsweb/text.gif){kind=icon}
![[DIR]](/icons/cvsweb/dir.gif){kind=icon}
Up to [ELWIX - Embedded LightWeight unIX -] / embedaddon / pcre / doc