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