src/external/pcre2-10.32/doc/html/pcre2jit.html

   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>
   8 Return to the <a href="index.html">PCRE2 index page</a>.
   9 </p>
  10 <p>
  11 This page is part of the PCRE2 HTML documentation. It was generated
  12 automatically from the original man page. If there is any nonsense in it,
  13 please 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>
  32 Just-in-time compiling is a heavyweight optimization that can greatly speed up
  33 pattern matching. However, it comes at the cost of extra processing before the
  34 match is performed, so it is of most benefit when the same pattern is going to
  35 be matched many times. This does not necessarily mean many calls of a matching
  36 function; if the pattern is not anchored, matching attempts may take place many
  37 times at various positions in the subject, even for a single call. Therefore,
  38 if the subject string is very long, it may still pay to use JIT even for
  39 one-off matches. JIT support is available for all of the 8-bit, 16-bit and
  40 32-bit PCRE2 libraries.
  41 </P>
  42 <P>
  43 JIT support applies only to the traditional Perl-compatible matching function.
  44 It does not apply when the DFA matching function is being used. The code for
  45 this support was written by Zoltan Herczeg.
  46 </P>
  47 <br><a name="SEC2" href="#TOC1">AVAILABILITY OF JIT SUPPORT</a><br>
  48 <P>
  49 JIT 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
  51 you want to use JIT. The support is limited to the following hardware
  52 platforms:
  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>
  61 If --enable-jit is set on an unsupported platform, compilation fails.
  62 </P>
  63 <P>
  64 A program can tell if JIT support is available by calling <b>pcre2_config()</b>
  65 with the PCRE2_CONFIG_JIT option. The result is 1 when JIT is available, and 0
  66 otherwise. However, a simple program does not need to check this in order to
  67 use JIT. The API is implemented in a way that falls back to the interpretive
  68 code if JIT is not available. For programs that need the best possible
  69 performance, 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>
  73 To make use of the JIT support in the simplest way, all you have to do is to
  74 call <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
  76 compiled pattern pointer that was returned by <b>pcre2_compile()</b>, and the
  77 second is zero or more of the following option bits: PCRE2_JIT_COMPLETE,
  78 PCRE2_JIT_PARTIAL_HARD, or PCRE2_JIT_PARTIAL_SOFT.
  79 </P>
  80 <P>
  81 If JIT support is not available, a call to <b>pcre2_jit_compile()</b> does
  82 nothing and returns PCRE2_ERROR_JIT_BADOPTION. Otherwise, the compiled pattern
  83 is passed to the JIT compiler, which turns it into machine code that executes
  84 much faster than the normal interpretive code, but yields exactly the same
  85 results. The returned value from <b>pcre2_jit_compile()</b> is zero on success,
  86 or a negative error code.
  87 </P>
  88 <P>
  89 There is a limit to the size of pattern that JIT supports, imposed by the size
  90 of machine stack that it uses. The exact rules are not documented because they
  91 may change at any time, in particular, when new optimizations are introduced.
  92 If a pattern is too big, a call to \fBpcre2_jit_compile()\fB returns
  93 PCRE2_ERROR_NOMEMORY.
  94 </P>
  95 <P>
  96 PCRE2_JIT_COMPLETE requests the JIT compiler to generate code for complete
  97 matches. If you want to run partial matches using the PCRE2_PARTIAL_HARD or
  98 PCRE2_PARTIAL_SOFT options of <b>pcre2_match()</b>, you should set one or both
  99 of the other options as well as, or instead of PCRE2_JIT_COMPLETE. The JIT
 100 compiler generates different optimized code for each of the three modes
 101 (normal, soft partial, hard partial). When <b>pcre2_match()</b> is called, the
 102 appropriate code is run if it is available. Otherwise, the pattern is matched
 103 using interpretive code.
 104 </P>
 105 <P>
 106 You can call <b>pcre2_jit_compile()</b> multiple times for the same compiled
 107 pattern. It does nothing if it has previously compiled code for any of the
 108 option 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
 110 PCRE2_JIT_COMPLETE and PCRE2_JIT_PARTIAL_HARD. This time it will ignore
 111 PCRE2_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
 113 returns zero. This is an alternative way of testing whether JIT is available.
 114 </P>
 115 <P>
 116 At present, it is not possible to free JIT compiled code except when the entire
 117 compiled pattern is freed by calling <b>pcre2_code_free()</b>.
 118 </P>
 119 <P>
 120 In some circumstances you may need to call additional functions. These are
 121 described in the section entitled
 122 <a href="#stackcontrol">"Controlling the JIT stack"</a>
 123 below.
 124 </P>
 125 <P>
 126 There are some <b>pcre2_match()</b> options that are not supported by JIT, and
 127 there are also some pattern items that JIT cannot handle. Details are given
 128 below. In both cases, matching automatically falls back to the interpretive
 129 code. If you want to know whether JIT was actually used for a particular match,
 130 you should arrange for a JIT callback function to be set up as described in the
 131 section entitled
 132 <a href="#stackcontrol">"Controlling the JIT stack"</a>
 133 below, even if you do not need to supply a non-default JIT stack. Such a
 134 callback function is called whenever JIT code is about to be obeyed. If the
 135 match-time options are not right for JIT execution, the callback function is
 136 not obeyed.
 137 </P>
 138 <P>
 139 If the JIT compiler finds an unsupported item, no JIT data is generated. You
 140 can 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
 142 result means that JIT compilation was successful. A result of 0 means that JIT
 143 support 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
 145 pattern.
 146 </P>
 147 <br><a name="SEC4" href="#TOC1">UNSUPPORTED OPTIONS AND PATTERN ITEMS</a><br>
 148 <P>
 149 The <b>pcre2_match()</b> options that are supported for JIT matching are
 150 PCRE2_NOTBOL, PCRE2_NOTEOL, PCRE2_NOTEMPTY, PCRE2_NOTEMPTY_ATSTART,
 151 PCRE2_NO_UTF_CHECK, PCRE2_PARTIAL_HARD, and PCRE2_PARTIAL_SOFT. The
 152 PCRE2_ANCHORED option is not supported at match time.
 153 </P>
 154 <P>
 155 If the PCRE2_NO_JIT option is passed to <b>pcre2_match()</b> it disables the
 156 use of JIT, forcing matching by the interpreter code.
 157 </P>
 158 <P>
 159 The only unsupported pattern items are \C (match a single data unit) when
 160 running in a UTF mode, and a callout immediately before an assertion condition
 161 in a conditional group.
 162 </P>
 163 <br><a name="SEC5" href="#TOC1">RETURN VALUES FROM JIT MATCHING</a><br>
 164 <P>
 165 When a pattern is matched using JIT matching, the return values are the same
 166 as those given by the interpretive <b>pcre2_match()</b> code, with the addition
 167 of one new error code: PCRE2_ERROR_JIT_STACKLIMIT. This means that the memory
 168 used for the JIT stack was insufficient. See
 169 <a href="#stackcontrol">"Controlling the JIT stack"</a>
 170 below for a discussion of JIT stack usage.
 171 </P>
 172 <P>
 173 The error code PCRE2_ERROR_MATCHLIMIT is returned by the JIT code if searching
 174 a very large pattern tree goes on for too long, as it is in the same
 175 circumstance when JIT is not used, but the details of exactly what is counted
 176 are not the same. The PCRE2_ERROR_DEPTHLIMIT error code is never returned
 177 when 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>
 181 When the compiled JIT code runs, it needs a block of memory to use as a stack.
 182 By default, it uses 32KiB on the machine stack. However, some large or
 183 complicated patterns need more than this. The error PCRE2_ERROR_JIT_STACKLIMIT
 184 is given when there is not enough stack. Three functions are provided for
 185 managing blocks of memory for use as JIT stacks. There is further discussion
 186 about the use of JIT stacks in the section entitled
 187 <a href="#stackfaq">"JIT stack FAQ"</a>
 188 below.
 189 </P>
 190 <P>
 191 The <b>pcre2_jit_stack_create()</b> function creates a JIT stack. Its arguments
 192 are a starting size, a maximum size, and a general context (for memory
 193 allocation functions, or NULL for standard memory allocation). It returns a
 194 pointer to an opaque structure of type <b>pcre2_jit_stack</b>, or NULL if there
 195 is an error. The <b>pcre2_jit_stack_free()</b> function is used to free a stack
 196 that is no longer needed. If its argument is NULL, this function returns
 197 immediately, without doing anything. (For the technically minded: the address
 198 space is allocated by mmap or VirtualAlloc.) A maximum stack size of 512KiB to
 199 1MiB should be more than enough for any pattern.
 200 </P>
 201 <P>
 202 The <b>pcre2_jit_stack_assign()</b> function specifies which stack JIT code
 203 should use. Its arguments are as follows:
 204 <pre>
 205   pcre2_match_context  *mcontext
 206   pcre2_jit_callback    callback
 207   void                 *data
 208 </pre>
 209 The first argument is a pointer to a match context. When this is subsequently
 210 passed to a matching function, its information determines which JIT stack is
 211 used. If this argument is NULL, the function returns immediately, without doing
 212 anything. 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>
 229 A callback function is obeyed whenever JIT code is about to be run; it is not
 230 obeyed when <b>pcre2_match()</b> is called with options that are incompatible
 231 for JIT matching. A callback function can therefore be used to determine
 232 whether a match operation was executed by JIT or by the interpreter.
 233 </P>
 234 <P>
 235 You may safely use the same JIT stack for more than one pattern (either by
 236 assigning directly or by callback), as long as the patterns are matched
 237 sequentially in the same thread. Currently, the only way to set up
 238 non-sequential matches in one thread is to use callouts: if a callout function
 239 starts another match, that match must use a different JIT stack to the one used
 240 for currently suspended match(es).
 241 </P>
 242 <P>
 243 In a multithread application, if you do not
 244 specify a JIT stack, or if you assign or pass back NULL from a callback, that
 245 is thread-safe, because each thread has its own machine stack. However, if you
 246 assign or pass back a non-NULL JIT stack, this must be a different stack for
 247 each thread so that the application is thread-safe.
 248 </P>
 249 <P>
 250 Strictly speaking, even more is allowed. You can assign the same non-NULL stack
 251 to a match context that is used by any number of patterns, as long as they are
 252 not used for matching by multiple threads at the same time. For example, you
 253 could use the same stack in all compiled patterns, with a global mutex in the
 254 callback to wait until the stack is available for use. However, this is an
 255 inefficient solution, and not recommended.
 256 </P>
 257 <P>
 258 This is a suggestion for how a multithreaded program that needs to set up
 259 non-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>
 270 All 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>
 277 PCRE2 (and JIT) is a recursive, depth-first engine, so it needs a stack where
 278 the local data of the current node is pushed before checking its child nodes.
 279 Allocating real machine stack on some platforms is difficult. For example, the
 280 stack chain needs to be updated every time if we extend the stack on PowerPC.
 281 Although it is possible, its updating time overhead decreases performance. So
 282 we 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>
 288 Modern operating systems have a nice feature: they can reserve an address space
 289 instead of allocating memory. We can safely allocate memory pages inside this
 290 address space, so the stack could grow without moving memory data (this is
 291 important because of pointers). Thus we can allocate 1MiB address space, and
 292 use only a single memory page (usually 4KiB) if that is enough. However, we can
 293 still grow up to 1MiB anytime if needed.
 294 </P>
 295 <P>
 296 (3) Who "owns" a JIT stack?
 297 <br>
 298 <br>
 299 The owner of the stack is the user program, not the JIT studied pattern or
 300 anything 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
 302 to the pattern currently running), that stack must not be used by any other
 303 threads (to avoid overwriting the same memory area). The best practice for
 304 multithreaded programs is to allocate a stack for each thread, and return this
 305 stack through the JIT callback function.
 306 </P>
 307 <P>
 308 (4) When should a JIT stack be freed?
 309 <br>
 310 <br>
 311 You 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
 313 pointer is set. There is no reference counting or any other magic. You can free
 314 compiled patterns, contexts, and stacks in any order, anytime. Just \fIdo
 315 not\fP call <b>pcre2_match()</b> with a match context pointing to an already
 316 freed stack, as that will cause SEGFAULT. (Also, do not free a stack currently
 317 used by <b>pcre2_match()</b> in another thread). You can also replace the stack
 318 in a context at any time when it is not in use. You should free the previous
 319 stack 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>
 326 No, because this is too costly in terms of resources. However, you could
 327 implement some clever idea which release the stack if it is not used in let's
 328 say two minutes. The JIT callback can help to achieve this without keeping a
 329 list of patterns.
 330 </P>
 331 <P>
 332 (6) OK, the stack is for long term memory allocation. But what happens if a
 333 pattern causes stack overflow with a stack of 1MiB? Is that 1MiB kept until the
 334 stack is freed?
 335 <br>
 336 <br>
 337 Especially on embedded sytems, it might be a good idea to release memory
 338 sometimes without freeing the stack. There is no API for this at the moment.
 339 Probably a function call which returns with the currently allocated memory for
 340 any stack and another which allows releasing memory (shrinking the stack) would
 341 be 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
 345 stack handling?
 346 <br>
 347 <br>
 348 No, thanks to Windows. If POSIX threads were used everywhere, we could throw
 349 out 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>
 356 The JIT executable allocator does not free all memory when it is possible.
 357 It expects new allocations, and keeps some free memory around to improve
 358 allocation speed. However, in low memory conditions, it might be better to free
 359 all possible memory. You can cause this to happen by calling
 360 pcre2_jit_free_unused_memory(). Its argument is a general context, for custom
 361 memory management, or NULL for standard memory management.
 362 </P>
 363 <br><a name="SEC9" href="#TOC1">EXAMPLE CODE</a><br>
 364 <P>
 365 This is a single-threaded example that specifies a JIT stack without using a
 366 callback. A real program should include error checking after all the function
 367 calls.
 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>
 394 Because the API described above falls back to interpreted matching when JIT is
 395 not available, it is convenient for programs that are written for general use
 396 in many environments. However, calling JIT via <b>pcre2_match()</b> does have a
 397 performance impact. Programs that are written for use where JIT is known to be
 398 available, 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
 401 processed by <b>pcre2_jit_compile()</b>).
 402 </P>
 403 <P>
 404 The fast path function is called <b>pcre2_jit_match()</b>, and it takes exactly
 405 the same arguments as <b>pcre2_match()</b>. The return values are also the same,
 406 plus PCRE2_ERROR_JIT_BADOPTION if a matching mode (partial or complete) is
 407 requested that was not compiled. Unsupported option bits (for example,
 408 PCRE2_ANCHORED) are ignored, as is the PCRE2_NO_JIT option.
 409 </P>
 410 <P>
 411 When you call <b>pcre2_match()</b>, as well as testing for invalid options, a
 412 number of other sanity checks are performed on the arguments. For example, if
 413 the subject pointer is NULL, an immediate error is given. Also, unless
 414 PCRE2_NO_UTF_CHECK is set, a UTF subject string is tested for validity. In the
 415 interests of speed, these checks do not happen on the JIT fast path, and if
 416 invalid data is passed, the result is undefined.
 417 </P>
 418 <P>
 419 Bypassing the sanity checks and the <b>pcre2_match()</b> wrapping can give
 420 speedups 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>
 428 Philip Hazel (FAQ by Zoltan Herczeg)
 429 <br>
 430 University Computing Service
 431 <br>
 432 Cambridge, England.
 433 <br>
 434 </P>
 435 <br><a name="SEC13" href="#TOC1">REVISION</a><br>
 436 <P>
 437 Last updated: 28 June 2018
 438 <br>
 439 Copyright &copy; 1997-2018 University of Cambridge.
 440 <br>
 441 <p>
 442 Return to the <a href="index.html">PCRE2 index page</a>.
 443 </p>