1PCRE2JIT(3)                Library Functions Manual                PCRE2JIT(3)
2
3
4

NAME

6       PCRE2 - Perl-compatible regular expressions (revised API)
7

PCRE2 JUST-IN-TIME COMPILER SUPPORT

9
10       Just-in-time  compiling  is a heavyweight optimization that can greatly
11       speed up pattern matching. However, it comes at the cost of extra  pro‐
12       cessing  before  the  match is performed, so it is of most benefit when
13       the same pattern is going to be matched many times. This does not  nec‐
14       essarily  mean many calls of a matching function; if the pattern is not
15       anchored, matching attempts may take place many times at various  posi‐
16       tions in the subject, even for a single call. Therefore, if the subject
17       string is very long, it may still pay  to  use  JIT  even  for  one-off
18       matches.  JIT  support  is  available  for all of the 8-bit, 16-bit and
19       32-bit PCRE2 libraries.
20
21       JIT support applies only to the  traditional  Perl-compatible  matching
22       function.   It  does  not apply when the DFA matching function is being
23       used. The code for this support was written by Zoltan Herczeg.
24

AVAILABILITY OF JIT SUPPORT

26
27       JIT support is an optional feature of  PCRE2.  The  "configure"  option
28       --enable-jit  (or  equivalent  CMake  option) must be set when PCRE2 is
29       built if you want to use JIT. The support is limited to  the  following
30       hardware platforms:
31
32         ARM 32-bit (v5, v7, and Thumb2)
33         ARM 64-bit
34         Intel x86 32-bit and 64-bit
35         MIPS 32-bit and 64-bit
36         Power PC 32-bit and 64-bit
37         SPARC 32-bit
38
39       If --enable-jit is set on an unsupported platform, compilation fails.
40
41       A  program  can  tell if JIT support is available by calling pcre2_con‐
42       fig() with the PCRE2_CONFIG_JIT option. The result is  1  when  JIT  is
43       available,  and 0 otherwise. However, a simple program does not need to
44       check this in order to use JIT. The API is implemented in  a  way  that
45       falls  back  to the interpretive code if JIT is not available. For pro‐
46       grams that need the best possible performance, there is  also  a  "fast
47       path" API that is JIT-specific.
48

SIMPLE USE OF JIT

50
51       To  make use of the JIT support in the simplest way, all you have to do
52       is to call pcre2_jit_compile() after successfully compiling  a  pattern
53       with pcre2_compile(). This function has two arguments: the first is the
54       compiled pattern pointer that was returned by pcre2_compile(), and  the
55       second  is  zero  or  more of the following option bits: PCRE2_JIT_COM‐
56       PLETE, PCRE2_JIT_PARTIAL_HARD, or PCRE2_JIT_PARTIAL_SOFT.
57
58       If JIT support is not available, a  call  to  pcre2_jit_compile()  does
59       nothing  and returns PCRE2_ERROR_JIT_BADOPTION. Otherwise, the compiled
60       pattern is passed to the JIT compiler, which turns it into machine code
61       that executes much faster than the normal interpretive code, but yields
62       exactly the same results. The returned value  from  pcre2_jit_compile()
63       is zero on success, or a negative error code.
64
65       There  is  a limit to the size of pattern that JIT supports, imposed by
66       the size of machine stack that it uses. The exact rules are  not  docu‐
67       mented  because  they  may  change at any time, in particular, when new
68       optimizations are introduced.  If a pattern  is  too  big,  a  call  to
69       pcre2_jit_compile() returns PCRE2_ERROR_NOMEMORY.
70
71       PCRE2_JIT_COMPLETE  requests the JIT compiler to generate code for com‐
72       plete matches. If you want to run partial matches using the  PCRE2_PAR‐
73       TIAL_HARD  or  PCRE2_PARTIAL_SOFT  options of pcre2_match(), you should
74       set one or both of  the  other  options  as  well  as,  or  instead  of
75       PCRE2_JIT_COMPLETE. The JIT compiler generates different optimized code
76       for each of the three modes (normal, soft partial, hard partial).  When
77       pcre2_match()  is  called,  the appropriate code is run if it is avail‐
78       able. Otherwise, the pattern is matched using interpretive code.
79
80       You can call pcre2_jit_compile() multiple times for the  same  compiled
81       pattern.  It does nothing if it has previously compiled code for any of
82       the option bits. For example, you can call it once with  PCRE2_JIT_COM‐
83       PLETE  and  (perhaps  later,  when  you find you need partial matching)
84       again with PCRE2_JIT_COMPLETE and PCRE2_JIT_PARTIAL_HARD. This time  it
85       will ignore PCRE2_JIT_COMPLETE and just compile code for partial match‐
86       ing. If pcre2_jit_compile() is called with no option bits set, it imme‐
87       diately returns zero. This is an alternative way of testing whether JIT
88       is available.
89
90       At present, it is not possible to free JIT compiled  code  except  when
91       the entire compiled pattern is freed by calling pcre2_code_free().
92
93       In  some circumstances you may need to call additional functions. These
94       are described in the  section  entitled  "Controlling  the  JIT  stack"
95       below.
96
97       There are some pcre2_match() options that are not supported by JIT, and
98       there are also some pattern items that JIT cannot handle.  Details  are
99       given  below.  In  both cases, matching automatically falls back to the
100       interpretive code. If you want to know whether JIT  was  actually  used
101       for  a particular match, you should arrange for a JIT callback function
102       to be set up as described in the section entitled "Controlling the  JIT
103       stack"  below,  even  if  you  do  not need to supply a non-default JIT
104       stack. Such a callback function is called whenever JIT code is about to
105       be  obeyed.  If the match-time options are not right for JIT execution,
106       the callback function is not obeyed.
107
108       If the JIT compiler finds an unsupported item, no JIT  data  is  gener‐
109       ated.  You  can find out if JIT matching is available after compiling a
110       pattern by calling  pcre2_pattern_info()  with  the  PCRE2_INFO_JITSIZE
111       option.  A non-zero result means that JIT compilation was successful. A
112       result of 0 means that JIT support is not available, or the pattern was
113       not  processed by pcre2_jit_compile(), or the JIT compiler was not able
114       to handle the pattern.
115

MATCHING SUBJECTS CONTAINING INVALID UTF

117
118       When a pattern is compiled with the PCRE2_UTF option,  subject  strings
119       are  normally  expected  to  be  a valid sequence of UTF code units. By
120       default, this is checked at the start of matching and an error is  gen‐
121       erated if invalid UTF is detected. The PCRE2_NO_UTF_CHECK option can be
122       passed to pcre2_match() to skip the check (for improved performance) if
123       you  are  sure  that  a subject string is valid. If this option is used
124       with an invalid string, the result is undefined.
125
126       However, a way of running matches on strings that may  contain  invalid
127       UTF   sequences   is   available.   Calling  pcre2_compile()  with  the
128       PCRE2_MATCH_INVALID_UTF option has two effects:  it  tells  the  inter‐
129       preter  in pcre2_match() to support invalid UTF, and, if pcre2_jit_com‐
130       pile() is called, the compiled JIT  code  also  supports  invalid  UTF.
131       Details of how this support works, in both the JIT and the interpretive
132       cases, is given in the pcre2unicode documentation.
133
134       There  is  also  an  obsolete  option  for  pcre2_jit_compile()  called
135       PCRE2_JIT_INVALID_UTF, which currently exists only for backward compat‐
136       ibility.    It   is   superseded   by   the   pcre2_compile()    option
137       PCRE2_MATCH_INVALID_UTF and should no longer be used. It may be removed
138       in future.
139

UNSUPPORTED OPTIONS AND PATTERN ITEMS

141
142       The pcre2_match() options that  are  supported  for  JIT  matching  are
143       PCRE2_COPY_MATCHED_SUBJECT, PCRE2_NOTBOL, PCRE2_NOTEOL, PCRE2_NOTEMPTY,
144       PCRE2_NOTEMPTY_ATSTART,  PCRE2_NO_UTF_CHECK,  PCRE2_PARTIAL_HARD,   and
145       PCRE2_PARTIAL_SOFT.  The  PCRE2_ANCHORED  and PCRE2_ENDANCHORED options
146       are not supported at match time.
147
148       If the PCRE2_NO_JIT option is passed to pcre2_match() it  disables  the
149       use of JIT, forcing matching by the interpreter code.
150
151       The  only  unsupported  pattern items are \C (match a single data unit)
152       when running in a UTF mode, and a callout immediately before an  asser‐
153       tion condition in a conditional group.
154

RETURN VALUES FROM JIT MATCHING

156
157       When a pattern is matched using JIT matching, the return values are the
158       same as those given by the interpretive pcre2_match()  code,  with  the
159       addition  of one new error code: PCRE2_ERROR_JIT_STACKLIMIT. This means
160       that the memory used for the JIT stack was insufficient. See  "Control‐
161       ling the JIT stack" below for a discussion of JIT stack usage.
162
163       The  error  code  PCRE2_ERROR_MATCHLIMIT is returned by the JIT code if
164       searching a very large pattern tree goes on for too long, as it  is  in
165       the  same circumstance when JIT is not used, but the details of exactly
166       what is counted are not the same. The PCRE2_ERROR_DEPTHLIMIT error code
167       is never returned when JIT matching is used.
168

CONTROLLING THE JIT STACK

170
171       When the compiled JIT code runs, it needs a block of memory to use as a
172       stack.  By default, it uses 32KiB on the machine stack.  However,  some
173       large   or   complicated  patterns  need  more  than  this.  The  error
174       PCRE2_ERROR_JIT_STACKLIMIT is given when there  is  not  enough  stack.
175       Three  functions  are provided for managing blocks of memory for use as
176       JIT stacks. There is further discussion about the use of JIT stacks  in
177       the section entitled "JIT stack FAQ" below.
178
179       The  pcre2_jit_stack_create()  function  creates a JIT stack. Its argu‐
180       ments are a starting size, a maximum size, and a general  context  (for
181       memory  allocation  functions, or NULL for standard memory allocation).
182       It returns a pointer to an opaque structure of type pcre2_jit_stack, or
183       NULL  if there is an error. The pcre2_jit_stack_free() function is used
184       to free a stack that is no longer needed. If its argument is NULL, this
185       function  returns immediately, without doing anything. (For the techni‐
186       cally minded: the address space is allocated by mmap or  VirtualAlloc.)
187       A  maximum  stack size of 512KiB to 1MiB should be more than enough for
188       any pattern.
189
190       The pcre2_jit_stack_assign() function specifies which  stack  JIT  code
191       should use. Its arguments are as follows:
192
193         pcre2_match_context  *mcontext
194         pcre2_jit_callback    callback
195         void                 *data
196
197       The first argument is a pointer to a match context. When this is subse‐
198       quently passed to a matching function, its information determines which
199       JIT stack is used. If this argument is NULL, the function returns imme‐
200       diately, without doing anything. There are three cases for  the  values
201       of the other two options:
202
203         (1) If callback is NULL and data is NULL, an internal 32KiB block
204             on the machine stack is used. This is the default when a match
205             context is created.
206
207         (2) If callback is NULL and data is not NULL, data must be
208             a pointer to a valid JIT stack, the result of calling
209             pcre2_jit_stack_create().
210
211         (3) If callback is not NULL, it must point to a function that is
212             called with data as an argument at the start of matching, in
213             order to set up a JIT stack. If the return from the callback
214             function is NULL, the internal 32KiB stack is used; otherwise the
215             return value must be a valid JIT stack, the result of calling
216             pcre2_jit_stack_create().
217
218       A  callback function is obeyed whenever JIT code is about to be run; it
219       is not obeyed when pcre2_match() is called with options that are incom‐
220       patible  for JIT matching. A callback function can therefore be used to
221       determine whether a match operation was  executed  by  JIT  or  by  the
222       interpreter.
223
224       You may safely use the same JIT stack for more than one pattern (either
225       by assigning directly or by callback), as  long  as  the  patterns  are
226       matched sequentially in the same thread. Currently, the only way to set
227       up non-sequential matches in one thread is to use callouts: if a  call‐
228       out  function starts another match, that match must use a different JIT
229       stack to the one used for currently suspended match(es).
230
231       In a multithread application, if you do not specify a JIT stack, or  if
232       you  assign  or  pass  back  NULL from a callback, that is thread-safe,
233       because each thread has its own machine stack. However, if  you  assign
234       or  pass  back a non-NULL JIT stack, this must be a different stack for
235       each thread so that the application is thread-safe.
236
237       Strictly speaking, even more is allowed. You can assign the  same  non-
238       NULL  stack  to a match context that is used by any number of patterns,
239       as long as they are not used for matching by multiple  threads  at  the
240       same  time.  For  example, you could use the same stack in all compiled
241       patterns, with a global mutex in the callback to wait until  the  stack
242       is available for use. However, this is an inefficient solution, and not
243       recommended.
244
245       This is a suggestion for how a multithreaded program that needs to  set
246       up non-default JIT stacks might operate:
247
248         During thread initalization
249           thread_local_var = pcre2_jit_stack_create(...)
250
251         During thread exit
252           pcre2_jit_stack_free(thread_local_var)
253
254         Use a one-line callback function
255           return thread_local_var
256
257       All  the  functions  described in this section do nothing if JIT is not
258       available.
259

JIT STACK FAQ

261
262       (1) Why do we need JIT stacks?
263
264       PCRE2 (and JIT) is a recursive, depth-first engine, so it needs a stack
265       where  the local data of the current node is pushed before checking its
266       child nodes.  Allocating real machine stack on some platforms is diffi‐
267       cult. For example, the stack chain needs to be updated every time if we
268       extend the stack on PowerPC.  Although it  is  possible,  its  updating
269       time overhead decreases performance. So we do the recursion in memory.
270
271       (2) Why don't we simply allocate blocks of memory with malloc()?
272
273       Modern  operating  systems  have  a  nice  feature: they can reserve an
274       address space instead of allocating memory. We can safely allocate mem‐
275       ory  pages  inside  this address space, so the stack could grow without
276       moving memory data (this is important because of pointers). Thus we can
277       allocate 1MiB address space, and use only a single memory page (usually
278       4KiB) if that is enough. However, we can still grow up to 1MiB  anytime
279       if needed.
280
281       (3) Who "owns" a JIT stack?
282
283       The owner of the stack is the user program, not the JIT studied pattern
284       or anything else. The user program must ensure that if a stack is being
285       used by pcre2_match(), (that is, it is assigned to a match context that
286       is passed to the pattern currently running), that  stack  must  not  be
287       used  by any other threads (to avoid overwriting the same memory area).
288       The best practice for multithreaded programs is to allocate a stack for
289       each thread, and return this stack through the JIT callback function.
290
291       (4) When should a JIT stack be freed?
292
293       You can free a JIT stack at any time, as long as it will not be used by
294       pcre2_match() again. When you assign the stack to a match context, only
295       a  pointer  is  set. There is no reference counting or any other magic.
296       You can free compiled patterns, contexts, and stacks in any order, any‐
297       time.   Just do not call pcre2_match() with a match context pointing to
298       an already freed stack, as that will cause SEGFAULT. (Also, do not free
299       a  stack  currently  used  by pcre2_match() in another thread). You can
300       also replace the stack in a context at any time when it is not in  use.
301       You should free the previous stack before assigning a replacement.
302
303       (5)  Should  I  allocate/free  a  stack every time before/after calling
304       pcre2_match()?
305
306       No, because this is too costly in  terms  of  resources.  However,  you
307       could  implement  some clever idea which release the stack if it is not
308       used in let's say two minutes. The JIT callback  can  help  to  achieve
309       this without keeping a list of patterns.
310
311       (6)  OK, the stack is for long term memory allocation. But what happens
312       if a pattern causes stack overflow with a stack of 1MiB? Is  that  1MiB
313       kept until the stack is freed?
314
315       Especially  on embedded sytems, it might be a good idea to release mem‐
316       ory sometimes without freeing the stack. There is no API  for  this  at
317       the  moment.  Probably a function call which returns with the currently
318       allocated memory for any stack and another which allows releasing  mem‐
319       ory (shrinking the stack) would be a good idea if someone needs this.
320
321       (7) This is too much of a headache. Isn't there any better solution for
322       JIT stack handling?
323
324       No, thanks to Windows. If POSIX threads were used everywhere, we  could
325       throw out this complicated API.
326

FREEING JIT SPECULATIVE MEMORY

328
329       void pcre2_jit_free_unused_memory(pcre2_general_context *gcontext);
330
331       The JIT executable allocator does not free all memory when it is possi‐
332       ble.  It expects new allocations, and keeps some free memory around  to
333       improve  allocation  speed. However, in low memory conditions, it might
334       be better to free all possible memory. You can cause this to happen  by
335       calling  pcre2_jit_free_unused_memory(). Its argument is a general con‐
336       text, for custom memory management, or NULL for standard memory manage‐
337       ment.
338

EXAMPLE CODE

340
341       This  is  a  single-threaded example that specifies a JIT stack without
342       using a callback. A real program should include  error  checking  after
343       all the function calls.
344
345         int rc;
346         pcre2_code *re;
347         pcre2_match_data *match_data;
348         pcre2_match_context *mcontext;
349         pcre2_jit_stack *jit_stack;
350
351         re = pcre2_compile(pattern, PCRE2_ZERO_TERMINATED, 0,
352           &errornumber, &erroffset, NULL);
353         rc = pcre2_jit_compile(re, PCRE2_JIT_COMPLETE);
354         mcontext = pcre2_match_context_create(NULL);
355         jit_stack = pcre2_jit_stack_create(32*1024, 512*1024, NULL);
356         pcre2_jit_stack_assign(mcontext, NULL, jit_stack);
357         match_data = pcre2_match_data_create(re, 10);
358         rc = pcre2_match(re, subject, length, 0, 0, match_data, mcontext);
359         /* Process result */
360
361         pcre2_code_free(re);
362         pcre2_match_data_free(match_data);
363         pcre2_match_context_free(mcontext);
364         pcre2_jit_stack_free(jit_stack);
365
366

JIT FAST PATH API

368
369       Because the API described above falls back to interpreted matching when
370       JIT is not available, it is convenient for programs  that  are  written
371       for  general  use  in  many  environments.  However,  calling  JIT  via
372       pcre2_match() does have a performance impact. Programs that are written
373       for  use  where  JIT  is known to be available, and which need the best
374       possible performance, can instead use a "fast path"  API  to  call  JIT
375       matching  directly instead of calling pcre2_match() (obviously only for
376       patterns that have been successfully processed by pcre2_jit_compile()).
377
378       The fast path  function  is  called  pcre2_jit_match(),  and  it  takes
379       exactly  the  same  arguments  as  pcre2_match().  However, the subject
380       string must be specified with a length;  PCRE2_ZERO_TERMINATED  is  not
381       supported.   Unsupported  option  bits  (for  example,  PCRE2_ANCHORED,
382       PCRE2_ENDANCHORED and PCRE2_COPY_MATCHED_SUBJECT) are  ignored,  as  is
383       the  PCRE2_NO_JIT  option.  The  return values are also the same as for
384       pcre2_match(), plus PCRE2_ERROR_JIT_BADOPTION if a matching mode  (par‐
385       tial or complete) is requested that was not compiled.
386
387       When  you call pcre2_match(), as well as testing for invalid options, a
388       number of other sanity checks are performed on the arguments. For exam‐
389       ple, if the subject pointer is NULL, an immediate error is given. Also,
390       unless PCRE2_NO_UTF_CHECK is set, a UTF subject string  is  tested  for
391       validity.  In the interests of speed, these checks do not happen on the
392       JIT fast path, and if invalid data is passed, the result is undefined.
393
394       Bypassing the sanity checks and the  pcre2_match()  wrapping  can  give
395       speedups of more than 10%.
396

SEE ALSO

398
399       pcre2api(3)
400

AUTHOR

402
403       Philip Hazel (FAQ by Zoltan Herczeg)
404       University Computing Service
405       Cambridge, England.
406

REVISION

408
409       Last updated: 23 May 2019
410       Copyright (c) 1997-2019 University of Cambridge.
411
412
413
414PCRE2 10.34                       23 May 2019                      PCRE2JIT(3)
Impressum