• Home
  • Line#
  • Scopes#
  • Navigate#
  • Raw
  • Download
1<html>
2<head>
3<title>pcre2jit specification</title>
4</head>
5<body bgcolor="#FFFFFF" text="#00005A" link="#0066FF" alink="#3399FF" vlink="#2222BB">
6<h1>pcre2jit man page</h1>
7<p>
8Return to the <a href="index.html">PCRE2 index page</a>.
9</p>
10<p>
11This page is part of the PCRE2 HTML documentation. It was generated
12automatically from the original man page. If there is any nonsense in it,
13please consult the man page, in case the conversion went wrong.
14<br>
15<ul>
16<li><a name="TOC1" href="#SEC1">PCRE2 JUST-IN-TIME COMPILER SUPPORT</a>
17<li><a name="TOC2" href="#SEC2">AVAILABILITY OF JIT SUPPORT</a>
18<li><a name="TOC3" href="#SEC3">SIMPLE USE OF JIT</a>
19<li><a name="TOC4" href="#SEC4">UNSUPPORTED OPTIONS AND PATTERN ITEMS</a>
20<li><a name="TOC5" href="#SEC5">RETURN VALUES FROM JIT MATCHING</a>
21<li><a name="TOC6" href="#SEC6">CONTROLLING THE JIT STACK</a>
22<li><a name="TOC7" href="#SEC7">JIT STACK FAQ</a>
23<li><a name="TOC8" href="#SEC8">FREEING JIT SPECULATIVE MEMORY</a>
24<li><a name="TOC9" href="#SEC9">EXAMPLE CODE</a>
25<li><a name="TOC10" href="#SEC10">JIT FAST PATH API</a>
26<li><a name="TOC11" href="#SEC11">SEE ALSO</a>
27<li><a name="TOC12" href="#SEC12">AUTHOR</a>
28<li><a name="TOC13" href="#SEC13">REVISION</a>
29</ul>
30<br><a name="SEC1" href="#TOC1">PCRE2 JUST-IN-TIME COMPILER SUPPORT</a><br>
31<P>
32Just-in-time compiling is a heavyweight optimization that can greatly speed up
33pattern matching. However, it comes at the cost of extra processing before the
34match is performed, so it is of most benefit when the same pattern is going to
35be matched many times. This does not necessarily mean many calls of a matching
36function; if the pattern is not anchored, matching attempts may take place many
37times at various positions in the subject, even for a single call. Therefore,
38if the subject string is very long, it may still pay to use JIT even for
39one-off matches. JIT support is available for all of the 8-bit, 16-bit and
4032-bit PCRE2 libraries.
41</P>
42<P>
43JIT support applies only to the traditional Perl-compatible matching function.
44It does not apply when the DFA matching function is being used. The code for
45this support was written by Zoltan Herczeg.
46</P>
47<br><a name="SEC2" href="#TOC1">AVAILABILITY OF JIT SUPPORT</a><br>
48<P>
49JIT support is an optional feature of PCRE2. The "configure" option
50--enable-jit (or equivalent CMake option) must be set when PCRE2 is built if
51you want to use JIT. The support is limited to the following hardware
52platforms:
53<pre>
54  ARM 32-bit (v5, v7, and Thumb2)
55  ARM 64-bit
56  Intel x86 32-bit and 64-bit
57  MIPS 32-bit and 64-bit
58  Power PC 32-bit and 64-bit
59  SPARC 32-bit
60</pre>
61If --enable-jit is set on an unsupported platform, compilation fails.
62</P>
63<P>
64A program can tell if JIT support is available by calling <b>pcre2_config()</b>
65with the PCRE2_CONFIG_JIT option. The result is 1 when JIT is available, and 0
66otherwise. However, a simple program does not need to check this in order to
67use JIT. The API is implemented in a way that falls back to the interpretive
68code if JIT is not available. For programs that need the best possible
69performance, there is also a "fast path" API that is JIT-specific.
70</P>
71<br><a name="SEC3" href="#TOC1">SIMPLE USE OF JIT</a><br>
72<P>
73To make use of the JIT support in the simplest way, all you have to do is to
74call <b>pcre2_jit_compile()</b> after successfully compiling a pattern with
75<b>pcre2_compile()</b>. This function has two arguments: the first is the
76compiled pattern pointer that was returned by <b>pcre2_compile()</b>, and the
77second is zero or more of the following option bits: PCRE2_JIT_COMPLETE,
78PCRE2_JIT_PARTIAL_HARD, or PCRE2_JIT_PARTIAL_SOFT.
79</P>
80<P>
81If JIT support is not available, a call to <b>pcre2_jit_compile()</b> does
82nothing and returns PCRE2_ERROR_JIT_BADOPTION. Otherwise, the compiled pattern
83is passed to the JIT compiler, which turns it into machine code that executes
84much faster than the normal interpretive code, but yields exactly the same
85results. The returned value from <b>pcre2_jit_compile()</b> is zero on success,
86or a negative error code.
87</P>
88<P>
89There is a limit to the size of pattern that JIT supports, imposed by the size
90of machine stack that it uses. The exact rules are not documented because they
91may change at any time, in particular, when new optimizations are introduced.
92If a pattern is too big, a call to \fBpcre2_jit_compile()\fB returns
93PCRE2_ERROR_NOMEMORY.
94</P>
95<P>
96PCRE2_JIT_COMPLETE requests the JIT compiler to generate code for complete
97matches. If you want to run partial matches using the PCRE2_PARTIAL_HARD or
98PCRE2_PARTIAL_SOFT options of <b>pcre2_match()</b>, you should set one or both
99of the other options as well as, or instead of PCRE2_JIT_COMPLETE. The JIT
100compiler generates different optimized code for each of the three modes
101(normal, soft partial, hard partial). When <b>pcre2_match()</b> is called, the
102appropriate code is run if it is available. Otherwise, the pattern is matched
103using interpretive code.
104</P>
105<P>
106You can call <b>pcre2_jit_compile()</b> multiple times for the same compiled
107pattern. It does nothing if it has previously compiled code for any of the
108option bits. For example, you can call it once with PCRE2_JIT_COMPLETE and
109(perhaps later, when you find you need partial matching) again with
110PCRE2_JIT_COMPLETE and PCRE2_JIT_PARTIAL_HARD. This time it will ignore
111PCRE2_JIT_COMPLETE and just compile code for partial matching. If
112<b>pcre2_jit_compile()</b> is called with no option bits set, it immediately
113returns zero. This is an alternative way of testing whether JIT is available.
114</P>
115<P>
116At present, it is not possible to free JIT compiled code except when the entire
117compiled pattern is freed by calling <b>pcre2_code_free()</b>.
118</P>
119<P>
120In some circumstances you may need to call additional functions. These are
121described in the section entitled
122<a href="#stackcontrol">"Controlling the JIT stack"</a>
123below.
124</P>
125<P>
126There are some <b>pcre2_match()</b> options that are not supported by JIT, and
127there are also some pattern items that JIT cannot handle. Details are given
128below. In both cases, matching automatically falls back to the interpretive
129code. If you want to know whether JIT was actually used for a particular match,
130you should arrange for a JIT callback function to be set up as described in the
131section entitled
132<a href="#stackcontrol">"Controlling the JIT stack"</a>
133below, even if you do not need to supply a non-default JIT stack. Such a
134callback function is called whenever JIT code is about to be obeyed. If the
135match-time options are not right for JIT execution, the callback function is
136not obeyed.
137</P>
138<P>
139If the JIT compiler finds an unsupported item, no JIT data is generated. You
140can find out if JIT matching is available after compiling a pattern by calling
141<b>pcre2_pattern_info()</b> with the PCRE2_INFO_JITSIZE option. A non-zero
142result means that JIT compilation was successful. A result of 0 means that JIT
143support is not available, or the pattern was not processed by
144<b>pcre2_jit_compile()</b>, or the JIT compiler was not able to handle the
145pattern.
146</P>
147<br><a name="SEC4" href="#TOC1">UNSUPPORTED OPTIONS AND PATTERN ITEMS</a><br>
148<P>
149The <b>pcre2_match()</b> options that are supported for JIT matching are
150PCRE2_NOTBOL, PCRE2_NOTEOL, PCRE2_NOTEMPTY, PCRE2_NOTEMPTY_ATSTART,
151PCRE2_NO_UTF_CHECK, PCRE2_PARTIAL_HARD, and PCRE2_PARTIAL_SOFT. The
152PCRE2_ANCHORED option is not supported at match time.
153</P>
154<P>
155If the PCRE2_NO_JIT option is passed to <b>pcre2_match()</b> it disables the
156use of JIT, forcing matching by the interpreter code.
157</P>
158<P>
159The only unsupported pattern items are \C (match a single data unit) when
160running in a UTF mode, and a callout immediately before an assertion condition
161in a conditional group.
162</P>
163<br><a name="SEC5" href="#TOC1">RETURN VALUES FROM JIT MATCHING</a><br>
164<P>
165When a pattern is matched using JIT matching, the return values are the same
166as those given by the interpretive <b>pcre2_match()</b> code, with the addition
167of one new error code: PCRE2_ERROR_JIT_STACKLIMIT. This means that the memory
168used for the JIT stack was insufficient. See
169<a href="#stackcontrol">"Controlling the JIT stack"</a>
170below for a discussion of JIT stack usage.
171</P>
172<P>
173The error code PCRE2_ERROR_MATCHLIMIT is returned by the JIT code if searching
174a very large pattern tree goes on for too long, as it is in the same
175circumstance when JIT is not used, but the details of exactly what is counted
176are not the same. The PCRE2_ERROR_DEPTHLIMIT error code is never returned
177when JIT matching is used.
178<a name="stackcontrol"></a></P>
179<br><a name="SEC6" href="#TOC1">CONTROLLING THE JIT STACK</a><br>
180<P>
181When the compiled JIT code runs, it needs a block of memory to use as a stack.
182By default, it uses 32KiB on the machine stack. However, some large or
183complicated patterns need more than this. The error PCRE2_ERROR_JIT_STACKLIMIT
184is given when there is not enough stack. Three functions are provided for
185managing blocks of memory for use as JIT stacks. There is further discussion
186about the use of JIT stacks in the section entitled
187<a href="#stackfaq">"JIT stack FAQ"</a>
188below.
189</P>
190<P>
191The <b>pcre2_jit_stack_create()</b> function creates a JIT stack. Its arguments
192are a starting size, a maximum size, and a general context (for memory
193allocation functions, or NULL for standard memory allocation). It returns a
194pointer to an opaque structure of type <b>pcre2_jit_stack</b>, or NULL if there
195is an error. The <b>pcre2_jit_stack_free()</b> function is used to free a stack
196that is no longer needed. If its argument is NULL, this function returns
197immediately, without doing anything. (For the technically minded: the address
198space is allocated by mmap or VirtualAlloc.) A maximum stack size of 512KiB to
1991MiB should be more than enough for any pattern.
200</P>
201<P>
202The <b>pcre2_jit_stack_assign()</b> function specifies which stack JIT code
203should use. Its arguments are as follows:
204<pre>
205  pcre2_match_context  *mcontext
206  pcre2_jit_callback    callback
207  void                 *data
208</pre>
209The first argument is a pointer to a match context. When this is subsequently
210passed to a matching function, its information determines which JIT stack is
211used. If this argument is NULL, the function returns immediately, without doing
212anything. There are three cases for the values of the other two options:
213<pre>
214  (1) If <i>callback</i> is NULL and <i>data</i> is NULL, an internal 32KiB block
215      on the machine stack is used. This is the default when a match
216      context is created.
217
218  (2) If <i>callback</i> is NULL and <i>data</i> is not NULL, <i>data</i> must be
219      a pointer to a valid JIT stack, the result of calling
220      <b>pcre2_jit_stack_create()</b>.
221
222  (3) If <i>callback</i> is not NULL, it must point to a function that is
223      called with <i>data</i> as an argument at the start of matching, in
224      order to set up a JIT stack. If the return from the callback
225      function is NULL, the internal 32KiB stack is used; otherwise the
226      return value must be a valid JIT stack, the result of calling
227      <b>pcre2_jit_stack_create()</b>.
228</pre>
229A callback function is obeyed whenever JIT code is about to be run; it is not
230obeyed when <b>pcre2_match()</b> is called with options that are incompatible
231for JIT matching. A callback function can therefore be used to determine
232whether a match operation was executed by JIT or by the interpreter.
233</P>
234<P>
235You may safely use the same JIT stack for more than one pattern (either by
236assigning directly or by callback), as long as the patterns are matched
237sequentially in the same thread. Currently, the only way to set up
238non-sequential matches in one thread is to use callouts: if a callout function
239starts another match, that match must use a different JIT stack to the one used
240for currently suspended match(es).
241</P>
242<P>
243In a multithread application, if you do not
244specify a JIT stack, or if you assign or pass back NULL from a callback, that
245is thread-safe, because each thread has its own machine stack. However, if you
246assign or pass back a non-NULL JIT stack, this must be a different stack for
247each thread so that the application is thread-safe.
248</P>
249<P>
250Strictly speaking, even more is allowed. You can assign the same non-NULL stack
251to a match context that is used by any number of patterns, as long as they are
252not used for matching by multiple threads at the same time. For example, you
253could use the same stack in all compiled patterns, with a global mutex in the
254callback to wait until the stack is available for use. However, this is an
255inefficient solution, and not recommended.
256</P>
257<P>
258This is a suggestion for how a multithreaded program that needs to set up
259non-default JIT stacks might operate:
260<pre>
261  During thread initalization
262    thread_local_var = pcre2_jit_stack_create(...)
263
264  During thread exit
265    pcre2_jit_stack_free(thread_local_var)
266
267  Use a one-line callback function
268    return thread_local_var
269</pre>
270All the functions described in this section do nothing if JIT is not available.
271<a name="stackfaq"></a></P>
272<br><a name="SEC7" href="#TOC1">JIT STACK FAQ</a><br>
273<P>
274(1) Why do we need JIT stacks?
275<br>
276<br>
277PCRE2 (and JIT) is a recursive, depth-first engine, so it needs a stack where
278the local data of the current node is pushed before checking its child nodes.
279Allocating real machine stack on some platforms is difficult. For example, the
280stack chain needs to be updated every time if we extend the stack on PowerPC.
281Although it is possible, its updating time overhead decreases performance. So
282we do the recursion in memory.
283</P>
284<P>
285(2) Why don't we simply allocate blocks of memory with <b>malloc()</b>?
286<br>
287<br>
288Modern operating systems have a nice feature: they can reserve an address space
289instead of allocating memory. We can safely allocate memory pages inside this
290address space, so the stack could grow without moving memory data (this is
291important because of pointers). Thus we can allocate 1MiB address space, and
292use only a single memory page (usually 4KiB) if that is enough. However, we can
293still grow up to 1MiB anytime if needed.
294</P>
295<P>
296(3) Who "owns" a JIT stack?
297<br>
298<br>
299The owner of the stack is the user program, not the JIT studied pattern or
300anything else. The user program must ensure that if a stack is being used by
301<b>pcre2_match()</b>, (that is, it is assigned to a match context that is passed
302to the pattern currently running), that stack must not be used by any other
303threads (to avoid overwriting the same memory area). The best practice for
304multithreaded programs is to allocate a stack for each thread, and return this
305stack through the JIT callback function.
306</P>
307<P>
308(4) When should a JIT stack be freed?
309<br>
310<br>
311You can free a JIT stack at any time, as long as it will not be used by
312<b>pcre2_match()</b> again. When you assign the stack to a match context, only a
313pointer is set. There is no reference counting or any other magic. You can free
314compiled patterns, contexts, and stacks in any order, anytime. Just \fIdo
315not\fP call <b>pcre2_match()</b> with a match context pointing to an already
316freed stack, as that will cause SEGFAULT. (Also, do not free a stack currently
317used by <b>pcre2_match()</b> in another thread). You can also replace the stack
318in a context at any time when it is not in use. You should free the previous
319stack before assigning a replacement.
320</P>
321<P>
322(5) Should I allocate/free a stack every time before/after calling
323<b>pcre2_match()</b>?
324<br>
325<br>
326No, because this is too costly in terms of resources. However, you could
327implement some clever idea which release the stack if it is not used in let's
328say two minutes. The JIT callback can help to achieve this without keeping a
329list of patterns.
330</P>
331<P>
332(6) OK, the stack is for long term memory allocation. But what happens if a
333pattern causes stack overflow with a stack of 1MiB? Is that 1MiB kept until the
334stack is freed?
335<br>
336<br>
337Especially on embedded sytems, it might be a good idea to release memory
338sometimes without freeing the stack. There is no API for this at the moment.
339Probably a function call which returns with the currently allocated memory for
340any stack and another which allows releasing memory (shrinking the stack) would
341be a good idea if someone needs this.
342</P>
343<P>
344(7) This is too much of a headache. Isn't there any better solution for JIT
345stack handling?
346<br>
347<br>
348No, thanks to Windows. If POSIX threads were used everywhere, we could throw
349out this complicated API.
350</P>
351<br><a name="SEC8" href="#TOC1">FREEING JIT SPECULATIVE MEMORY</a><br>
352<P>
353<b>void pcre2_jit_free_unused_memory(pcre2_general_context *<i>gcontext</i>);</b>
354</P>
355<P>
356The JIT executable allocator does not free all memory when it is possible.
357It expects new allocations, and keeps some free memory around to improve
358allocation speed. However, in low memory conditions, it might be better to free
359all possible memory. You can cause this to happen by calling
360pcre2_jit_free_unused_memory(). Its argument is a general context, for custom
361memory management, or NULL for standard memory management.
362</P>
363<br><a name="SEC9" href="#TOC1">EXAMPLE CODE</a><br>
364<P>
365This is a single-threaded example that specifies a JIT stack without using a
366callback. A real program should include error checking after all the function
367calls.
368<pre>
369  int rc;
370  pcre2_code *re;
371  pcre2_match_data *match_data;
372  pcre2_match_context *mcontext;
373  pcre2_jit_stack *jit_stack;
374
375  re = pcre2_compile(pattern, PCRE2_ZERO_TERMINATED, 0,
376    &errornumber, &erroffset, NULL);
377  rc = pcre2_jit_compile(re, PCRE2_JIT_COMPLETE);
378  mcontext = pcre2_match_context_create(NULL);
379  jit_stack = pcre2_jit_stack_create(32*1024, 512*1024, NULL);
380  pcre2_jit_stack_assign(mcontext, NULL, jit_stack);
381  match_data = pcre2_match_data_create(re, 10);
382  rc = pcre2_match(re, subject, length, 0, 0, match_data, mcontext);
383  /* Process result */
384
385  pcre2_code_free(re);
386  pcre2_match_data_free(match_data);
387  pcre2_match_context_free(mcontext);
388  pcre2_jit_stack_free(jit_stack);
389
390</PRE>
391</P>
392<br><a name="SEC10" href="#TOC1">JIT FAST PATH API</a><br>
393<P>
394Because the API described above falls back to interpreted matching when JIT is
395not available, it is convenient for programs that are written for general use
396in many environments. However, calling JIT via <b>pcre2_match()</b> does have a
397performance impact. Programs that are written for use where JIT is known to be
398available, and which need the best possible performance, can instead use a
399"fast path" API to call JIT matching directly instead of calling
400<b>pcre2_match()</b> (obviously only for patterns that have been successfully
401processed by <b>pcre2_jit_compile()</b>).
402</P>
403<P>
404The fast path function is called <b>pcre2_jit_match()</b>, and it takes exactly
405the same arguments as <b>pcre2_match()</b>. The return values are also the same,
406plus PCRE2_ERROR_JIT_BADOPTION if a matching mode (partial or complete) is
407requested that was not compiled. Unsupported option bits (for example,
408PCRE2_ANCHORED) are ignored, as is the PCRE2_NO_JIT option.
409</P>
410<P>
411When you call <b>pcre2_match()</b>, as well as testing for invalid options, a
412number of other sanity checks are performed on the arguments. For example, if
413the subject pointer is NULL, an immediate error is given. Also, unless
414PCRE2_NO_UTF_CHECK is set, a UTF subject string is tested for validity. In the
415interests of speed, these checks do not happen on the JIT fast path, and if
416invalid data is passed, the result is undefined.
417</P>
418<P>
419Bypassing the sanity checks and the <b>pcre2_match()</b> wrapping can give
420speedups of more than 10%.
421</P>
422<br><a name="SEC11" href="#TOC1">SEE ALSO</a><br>
423<P>
424<b>pcre2api</b>(3)
425</P>
426<br><a name="SEC12" href="#TOC1">AUTHOR</a><br>
427<P>
428Philip Hazel (FAQ by Zoltan Herczeg)
429<br>
430University Computing Service
431<br>
432Cambridge, England.
433<br>
434</P>
435<br><a name="SEC13" href="#TOC1">REVISION</a><br>
436<P>
437Last updated: 28 June 2018
438<br>
439Copyright &copy; 1997-2018 University of Cambridge.
440<br>
441<p>
442Return to the <a href="index.html">PCRE2 index page</a>.
443</p>
444