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