@@ -43,13 +44,15 @@ JIT support applies only to the traditional Perl-compa It does not apply when the DFA matching function is being used. The code for this support was written by Zoltan Herczeg.
--JIT support is available for both the 8-bit and 16-bit PCRE libraries. To keep -this documentation simple, only the 8-bit interface is described in what -follows. If you are using the 16-bit library, substitute the 16-bit functions -and 16-bit structures (for example, pcre16_jit_stack instead of -pcre_jit_stack). +JIT support is available for all of the 8-bit, 16-bit and 32-bit PCRE +libraries. To keep this documentation simple, only the 8-bit interface is +described in what follows. If you are using the 16-bit library, substitute the +16-bit functions and 16-bit structures (for example, pcre16_jit_stack +instead of pcre_jit_stack). If you are using the 32-bit library, +substitute the 32-bit functions and 32-bit structures (for example, +pcre32_jit_stack instead of pcre_jit_stack).
@@ -61,6 +64,7 @@ JIT. The support is limited to the following hardware Intel x86 32-bit and 64-bit MIPS 32-bit Power PC 32-bit and 64-bit + SPARC 32-bit (experimental) If --enable-jit is set on an unsupported platform, compilation fails.
@@ -68,8 +72,10 @@ If --enable-jit is set on an unsupported platform, com A program that is linked with PCRE 8.20 or later can tell if JIT support is available by calling pcre_config() with the PCRE_CONFIG_JIT option. The result is 1 when JIT is available, and 0 otherwise. However, a simple program -does not need to check this in order to use JIT. The API is implemented in a -way that falls back to the interpretive code if JIT is not available. +does not need to check this in order to use JIT. The normal API is implemented +in a way that falls back to the interpretive code if JIT is not available. For +programs that need the best possible performance, there is also a "fast path" +API that is JIT-specific.If your program may sometimes be linked with versions of PCRE that are older @@ -86,8 +92,8 @@ You have to do two things to make use of the JIT suppo pcre_exec(). (2) Use pcre_free_study() to free the pcre_extra block when it is - no longer needed, instead of just freeing it yourself. This - ensures that any JIT data is also freed. + no longer needed, instead of just freeing it yourself. This ensures that + any JIT data is also freed. For a program that may be linked with pre-8.20 versions of PCRE, you can insert
@@ -161,19 +167,14 @@ times as you like for matching different subject strin-
UNSUPPORTED OPTIONS AND PATTERN ITEMS
The only pcre_exec() options that are supported for JIT execution are -PCRE_NO_UTF8_CHECK, PCRE_NO_UTF16_CHECK, PCRE_NOTBOL, PCRE_NOTEOL, -PCRE_NOTEMPTY, PCRE_NOTEMPTY_ATSTART, PCRE_PARTIAL_HARD, and PCRE_PARTIAL_SOFT. +PCRE_NO_UTF8_CHECK, PCRE_NO_UTF16_CHECK, PCRE_NO_UTF32_CHECK, PCRE_NOTBOL, +PCRE_NOTEOL, PCRE_NOTEMPTY, PCRE_NOTEMPTY_ATSTART, PCRE_PARTIAL_HARD, and +PCRE_PARTIAL_SOFT.
-The unsupported pattern items are: -
- \C match a single byte; not supported in UTF-8 mode - (?Cn) callouts - (*PRUNE) ) - (*SKIP) ) backtracking control verbs - (*THEN) ) --Support for some of these may be added in future. +The only unsupported pattern items are \C (match a single data unit) when +running in a UTF mode, and a callout immediately before an assertion condition +in a conditional group.
RETURN VALUES FROM JIT EXECUTION
@@ -350,7 +351,7 @@ replacement.
No, because this is too costly in terms of resources. However, you could implement some clever idea which release the stack if it is not used in let's -say two minutes. The JIT callback can help to achive this without keeping a +say two minutes. The JIT callback can help to achieve this without keeping a list of the currently JIT studied patterns.@@ -398,11 +399,40 @@ callback.
+Because the API described above falls back to interpreted execution when JIT is +not available, it is convenient for programs that are written for general use +in many environments. However, calling JIT via pcre_exec() does have a +performance impact. Programs that are written for use where JIT is known to be +available, and which need the best possible performance, can instead use a +"fast path" API to call JIT execution directly instead of calling +pcre_exec() (obviously only for patterns that have been successfully +studied by JIT). +
++The fast path function is called pcre_jit_exec(), and it takes exactly +the same arguments as pcre_exec(), plus one additional argument that +must point to a JIT stack. The JIT stack arrangements described above do not +apply. The return values are the same as for pcre_exec(). +
++When you call pcre_exec(), as well as testing for invalid options, a +number of other sanity checks are performed on the arguments. For example, if +the subject pointer is NULL, or its length is negative, an immediate error is +given. Also, unless PCRE_NO_UTF[8|16|32] is set, a UTF subject string is tested +for validity. In the interests of speed, these checks do not happen on the JIT +fast path, and if invalid data is passed, the result is undefined. +
++Bypassing the sanity checks and the pcre_exec() wrapping can give +speedups of more than 10%. +
+pcreapi(3)
-
Philip Hazel (FAQ by Zoltan Herczeg)
@@ -411,11 +441,11 @@ University Computing Service
Cambridge CB2 3QH, England.
-Last updated: 04 May 2012
+Last updated: 17 March 2013
-Copyright © 1997-2012 University of Cambridge.
+Copyright © 1997-2013 University of Cambridge.
Return to the PCRE index page.