diff options
Diffstat (limited to 'doc/pcrejit.3')
-rw-r--r-- | doc/pcrejit.3 | 59 |
1 files changed, 45 insertions, 14 deletions
diff --git a/doc/pcrejit.3 b/doc/pcrejit.3 index 7716ed6..a492dcd 100644 --- a/doc/pcrejit.3 +++ b/doc/pcrejit.3 @@ -1,4 +1,4 @@ -.TH PCREJIT 3 "04 May 2012" "PCRE 8.31" +.TH PCREJIT 3 "31 October 2012" "PCRE 8.32" .SH NAME PCRE - Perl-compatible regular expressions .SH "PCRE JUST-IN-TIME COMPILER SUPPORT" @@ -21,13 +21,13 @@ this support was written by Zoltan Herczeg. .SH "8-BIT, 16-BIT AND 32-BIT SUPPORT" .rs .sp -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, \fIpcre16_jit_stack\fP instead of -\fIpcre_jit_stack\fP). If you are using the 32-bit library, substitute the 32-bit functions -and 32-bit structures (for example, \fIpcre32_jit_stack\fP instead of -\fIpcre_jit_stack\fP). +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, \fIpcre16_jit_stack\fP +instead of \fIpcre_jit_stack\fP). If you are using the 32-bit library, +substitute the 32-bit functions and 32-bit structures (for example, +\fIpcre32_jit_stack\fP instead of \fIpcre_jit_stack\fP). . . .SH "AVAILABILITY OF JIT SUPPORT" @@ -41,14 +41,17 @@ JIT. The support is limited to the following hardware platforms: Intel x86 32-bit and 64-bit MIPS 32-bit Power PC 32-bit and 64-bit + SPARC 32-bit (experimental) .sp If --enable-jit is set on an unsupported platform, compilation fails. .P A program that is linked with PCRE 8.20 or later can tell if JIT support is available by calling \fBpcre_config()\fP 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. .P If your program may sometimes be linked with versions of PCRE that are older than 8.20, but you want to use JIT when it is available, you can test @@ -66,8 +69,8 @@ You have to do two things to make use of the JIT support in the simplest way: \fBpcre_exec()\fP. .sp (2) Use \fBpcre_free_study()\fP to free the \fBpcre_extra\fP 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. .sp For a program that may be linked with pre-8.20 versions of PCRE, you can insert .sp @@ -335,7 +338,7 @@ replacement. .sp 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. .P (6) OK, the stack is for long term memory allocation. But what happens if a @@ -381,6 +384,34 @@ callback. .sp . . +.SH "JIT FAST PATH API" +.rs +.sp +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 \fBpcre_exec()\fP 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 +\fBpcre_exec()\fP (obviously only for patterns that have been successfully +studied by JIT). +.P +The fast path function is called \fBpcre_jit_exec()\fP, and it takes exactly +the same arguments as \fBpcre_exec()\fP, 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 \fBpcre_exec()\fP. +.P +When you call \fBpcre_exec()\fP, 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. +.P +Bypassing the sanity checks and the \fBpcre_exec()\fP wrapping can give +speedups of more than 10%. +. +. .SH "SEE ALSO" .rs .sp @@ -401,6 +432,6 @@ Cambridge CB2 3QH, England. .rs .sp .nf -Last updated: 04 May 2012 +Last updated: 31 October 2012 Copyright (c) 1997-2012 University of Cambridge. .fi |