/[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 686 by ph10, Tue Sep 6 16:06:36 2011 UTC revision 707 by ph10, Fri Sep 23 10:32:53 2011 UTC
# Line 47  You have to do two things to make use of Line 47  You have to do two things to make use of
47    (1) Call \fBpcre_study()\fP with the PCRE_STUDY_JIT_COMPILE option for    (1) Call \fBpcre_study()\fP with the PCRE_STUDY_JIT_COMPILE option for
48        each compiled pattern, and pass the resulting \fBpcre_extra\fP block to        each compiled pattern, and pass the resulting \fBpcre_extra\fP block to
49        \fBpcre_exec()\fP.        \fBpcre_exec()\fP.
50    .sp
51    (2) Use \fBpcre_free_study()\fP to free the \fBpcre_extra\fP block when it is    (2) Use \fBpcre_free_study()\fP to free the \fBpcre_extra\fP block when it is
52        no longer needed instead of just freeing it yourself. This        no longer needed instead of just freeing it yourself. This
53        ensures that any JIT data is also freed.        ensures that any JIT data is also freed.
54  .sp  .sp
55  In some circumstances you may need to call additional functions. These are  In some circumstances you may need to call additional functions. These are
# Line 75  interpretive code. Line 75  interpretive code.
75  If the JIT compiler finds an unsupported item, no JIT data is generated. You  If the JIT compiler finds an unsupported item, no JIT data is generated. You
76  can find out if JIT execution is available after studying a pattern by calling  can find out if JIT execution is available after studying a pattern by calling
77  \fBpcre_fullinfo()\fP with the PCRE_INFO_JIT option. A result of 1 means that  \fBpcre_fullinfo()\fP with the PCRE_INFO_JIT option. A result of 1 means that
78  JIT compilationw was successful. A result of 0 means that JIT support is not  JIT compilation was successful. A result of 0 means that JIT support is not
79  available, or the pattern was not studied with PCRE_STUDY_JIT_COMPILE, or the  available, or the pattern was not studied with PCRE_STUDY_JIT_COMPILE, or the
80  JIT compiler was not able to handle the pattern.  JIT compiler was not able to handle the pattern.
81    .P
82    Once a pattern has been studied, with or without JIT, it can be used as many
83    times as you like for matching different subject strings.
84  .  .
85  .  .
86  .SH "UNSUPPORTED OPTIONS AND PATTERN ITEMS"  .SH "UNSUPPORTED OPTIONS AND PATTERN ITEMS"
# Line 131  execution. Line 134  execution.
134  .rs  .rs
135  .sp  .sp
136  The code that is generated by the JIT compiler is architecture-specific, and is  The code that is generated by the JIT compiler is architecture-specific, and is
137  also position dependent. For those reasons it cannot be saved and restored like  also position dependent. For those reasons it cannot be saved (in a file or
138  the bytecode and other data of a compiled pattern. You should be able run  database) and restored later like the bytecode and other data of a compiled
139  \fBpcre_study()\fP on a saved and restored pattern, and thereby recreate the  pattern. Saving and restoring compiled patterns is not something many people
140  JIT data, but because JIT compilation uses significant resources, it is  do. More detail about this facility is given in the
141  probably not worth doing this.  .\" HREF
142    \fBpcreprecompile\fP
143    .\"
144    documentation. It should be possible to run \fBpcre_study()\fP on a saved and
145    restored pattern, and thereby recreate the JIT data, but because JIT
146    compilation uses significant resources, it is probably not worth doing this;
147    you might as well recompile the original pattern.
148  .  .
149  .  .
150  .\" HTML <a name="stackcontrol"></a>  .\" HTML <a name="stackcontrol"></a>
# Line 149  is given when there is not enough stack. Line 158  is given when there is not enough stack.
158  managing blocks of memory for use as JIT stacks.  managing blocks of memory for use as JIT stacks.
159  .P  .P
160  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
161  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
162  structure of type \fBpcre_jit_stack\fP, or NULL if there is an error. The  structure of type \fBpcre_jit_stack\fP, or NULL if there is an error. The
163  \fBpcre_jit_stack_free()\fP function can be used to free a stack that is no  \fBpcre_jit_stack_free()\fP function can be used to free a stack that is no
164  longer needed. (For the technically minded: the address space is allocated by  longer needed. (For the technically minded: the address space is allocated by
165  mmap or VirtualAlloc.)  mmap or VirtualAlloc.)
166  .P  .P
167  JIT uses far less memory for recursion than the interpretive code,  JIT uses far less memory for recursion than the interpretive code,
168  and a maximum stack size of 512K to 1M should be more than enough for any  and a maximum stack size of 512K to 1M should be more than enough for any
169  pattern.  pattern.
170  .P  .P
# Line 197  This is a suggestion for how a typical m Line 206  This is a suggestion for how a typical m
206  .sp  .sp
207    During thread initalization    During thread initalization
208      thread_local_var = pcre_jit_stack_alloc(...)      thread_local_var = pcre_jit_stack_alloc(...)
209    .sp
210    During thread exit    During thread exit
211      pcre_jit_stack_free(thread_local_var)      pcre_jit_stack_free(thread_local_var)
212    .sp
213    Use a one-line callback function    Use a one-line callback function
214      return thread_local_var      return thread_local_var
215  .sp  .sp
# Line 214  successful study with PCRE_STUDY_JIT_COM Line 223  successful study with PCRE_STUDY_JIT_COM
223  .rs  .rs
224  .sp  .sp
225  This is a single-threaded example that specifies a JIT stack without using a  This is a single-threaded example that specifies a JIT stack without using a
226  callback.  callback.
227  .sp  .sp
228    int rc;    int rc;
229    int ovector[30];    int ovector[30];
# Line 232  callback. Line 241  callback.
241    /* Check results */    /* Check results */
242    pcre_free(re);    pcre_free(re);
243    pcre_free_study(extra);    pcre_free_study(extra);
244    pcre_jit_stack_free(jit_stack);    pcre_jit_stack_free(jit_stack);
245  .sp  .sp
246  .  .
247  .  .
# Line 256  Cambridge CB2 3QH, England. Line 265  Cambridge CB2 3QH, England.
265  .rs  .rs
266  .sp  .sp
267  .nf  .nf
268  Last updated: 06 September 2011  Last updated: 23 September 2011
269  Copyright (c) 1997-2011 University of Cambridge.  Copyright (c) 1997-2011 University of Cambridge.
270  .fi  .fi
Legend:
Removed from v.686  
changed lines
  Added in v.707
  ViewVC Help
Powered by ViewVC 1.1.5