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 © 1997-2018 University of Cambridge. 440<br> 441<p> 442Return to the <a href="index.html">PCRE2 index page</a>. 443</p> 444