Man Pages

pcrejit(3) - phpMan pcrejit(3) - phpMan

Command: man perldoc info search(apropos)  


PCREJIT(3)                                                          PCREJIT(3)



NAME
       PCRE - Perl-compatible regular expressions

PCRE JUST-IN-TIME COMPILER SUPPORT

       Just-in-time  compiling  is  a heavyweight optimization that can greatly speed up pattern matching. However, it
       comes at the cost of extra processing before the match is performed. Therefore, it is of most benefit when  the
       same  pattern  is  going to be matched many times. This does not necessarily mean many calls of pcre_exec(); if
       the pattern is not anchored, matching attempts may take place many times at various positions in  the  subject,
       even for a single call to pcre_exec(). If the subject string is very long, it may still pay to use JIT for one-
       off matches.

       JIT support  applies  only  to  the  traditional  matching  function,  pcre_exec().  It  does  not  apply  when
       pcre_dfa_exec() is being used.  The code for this support was written by Zoltan Herczeg.

AVAILABILITY OF JIT SUPPORT

       JIT  support  is  an optional feature of PCRE. The "configure" option --enable-jit (or equivalent CMake option)
       must be set when PCRE is built if you want to use JIT. The support is limited to the following  hardware  plat-
       forms:

         ARM v5, v7, and Thumb2
         Intel x86 32-bit and 64-bit
         MIPS 32-bit
         Power PC 32-bit and 64-bit (experimental)

       The Power PC support is designated as experimental because it has not been fully tested. If --enable-jit is set
       on an unsupported platform, compilation fails.

       A program that is linked with PCRE 8.20 or later can tell if JIT support is available by calling  pcre_config()
       with the PCRE_CONFIG_JIT option. The result is 1 when JIT is available, and 0 otherwise. However, a simple pro-
       gram does not need to check this in order to use JIT. The API is implemented in a way that falls  back  to  the
       ordinary PCRE code if JIT is not available.

       If your program may sometimes be linked with versions of PCRE that are older than 8.20, but you want to use JIT
       when it is available, you can test the values of PCRE_MAJOR and PCRE_MINOR, or the existence  of  a  JIT  macro
       such as PCRE_CONFIG_JIT, for compile-time control of your code.

SIMPLE USE OF JIT

       You have to do two things to make use of the JIT support in the simplest way:

         (1) Call pcre_study() with the PCRE_STUDY_JIT_COMPILE option for
             each compiled pattern, and pass the resulting pcre_extra block to
             pcre_exec().

         (2) Use pcre_free_study() to free the pcre_extra block when it is
             no longer needed instead of just freeing it yourself. This
             ensures that any JIT data is also freed.

       For a program that may be linked with pre-8.20 versions of PCRE, you can insert

         #ifndef PCRE_STUDY_JIT_COMPILE
         #define PCRE_STUDY_JIT_COMPILE 0
         #endif

       so that no option is passed to pcre_study(), and then use something like this to free the study data:

         #ifdef PCRE_CONFIG_JIT
             pcre_free_study(study_ptr);
         #else
             pcre_free(study_ptr);
         #endif

       In  some  circumstances  you may need to call additional functions. These are described in the section entitled
       "Controlling the JIT stack" below.

       If JIT support is not available, PCRE_STUDY_JIT_COMPILE is ignored, and no JIT data is set up.  Otherwise,  the
       compiled pattern is passed to the JIT compiler, which turns it into machine code that executes much faster than
       the normal interpretive code. When pcre_exec() is passed a pcre_extra block containing a pointer to  JIT  code,
       it obeys that instead of the normal code. The result is identical, but the code runs much faster.

       There  are some pcre_exec() options that are not supported for JIT execution. There are also some pattern items
       that JIT cannot handle. Details are given below. In both cases,  execution  automatically  falls  back  to  the
       interpretive code.

       If  the  JIT compiler finds an unsupported item, no JIT data is generated. You can find out if JIT execution is
       available after studying a pattern by calling pcre_fullinfo() with the PCRE_INFO_JIT  option.  A  result  of  1
       means  that  JIT compilation was successful. A result of 0 means that JIT support is not available, or the pat-
       tern was not studied with PCRE_STUDY_JIT_COMPILE, or the JIT compiler was not able to handle the pattern.

       Once a pattern has been studied, with or without JIT, it can be used as many times as  you  like  for  matching
       different subject strings.

UNSUPPORTED OPTIONS AND PATTERN ITEMS

       The  only  pcre_exec()  options  that  are  supported  for  JIT  execution are PCRE_NO_UTF8_CHECK, PCRE_NOTBOL,
       PCRE_NOTEOL, PCRE_NOTEMPTY, and PCRE_NOTEMPTY_ATSTART. Note in particular that partial  matching  is  not  sup-
       ported.

       The unsupported pattern items are:

         \C             match a single byte; not supported in UTF-8 mode
         (?Cn)          callouts
         (*COMMIT)      )
         (*MARK)        )
         (*PRUNE)       ) the backtracking control verbs
         (*SKIP)        )
         (*THEN)        )

       Support for some of these may be added in future.

RETURN VALUES FROM JIT EXECUTION

       When  a  pattern is matched using JIT execution, the return values are the same as those given by the interpre-
       tive pcre_exec() code, with the addition of one new error code: PCRE_ERROR_JIT_STACKLIMIT. This means that  the
       memory  used  for the JIT stack was insufficient. See "Controlling the JIT stack" below for a discussion of JIT
       stack usage. For compatibility with the interpretive pcre_exec() code, no more than two-thirds of  the  ovector
       argument is used for passing back captured substrings.

       The error code PCRE_ERROR_MATCHLIMIT is returned by the JIT code if searching a very large pattern tree goes on
       for too long, as it is in the same circumstance when JIT is not used,  but  the  details  of  exactly  what  is
       counted are not the same. The PCRE_ERROR_RECURSIONLIMIT error code is never returned by JIT execution.

SAVING AND RESTORING COMPILED PATTERNS

       The  code  that  is generated by the JIT compiler is architecture-specific, and is also position dependent. For
       those reasons it cannot be saved (in a file or database) and restored later like the bytecode and other data of
       a  compiled  pattern. Saving and restoring compiled patterns is not something many people do. More detail about
       this facility is given in the pcreprecompile documentation. It should be possible  to  run  pcre_study()  on  a
       saved  and  restored  pattern,  and thereby recreate the JIT data, but because JIT compilation uses significant
       resources, it is probably not worth doing this; you might as well recompile the original pattern.

CONTROLLING THE JIT STACK

       When the compiled JIT code runs, it needs a block of memory to use as a stack.  By default, it uses 32K on  the
       machine stack. However, some large or complicated patterns need more than this. The error PCRE_ERROR_JIT_STACK-
       LIMIT is given when there is not enough stack. Three functions are provided for managing blocks of  memory  for
       use  as  JIT stacks. There is further discussion about the use of JIT stacks in the section entitled "JIT stack
       FAQ" below.

       The pcre_jit_stack_alloc() function creates a JIT stack. Its arguments are a starting size and a maximum  size,
       and  it  returns  a  pointer  to  an opaque structure of type pcre_jit_stack, or NULL if there is an error. The
       pcre_jit_stack_free() function can be used to free a stack that is  no  longer  needed.  (For  the  technically
       minded: the address space is allocated by mmap or VirtualAlloc.)

       JIT  uses  far  less  memory  for  recursion than the interpretive code, and a maximum stack size of 512K to 1M
       should be more than enough for any pattern.

       The pcre_assign_jit_stack() function specifies which stack JIT code should use. Its arguments are as follows:

         pcre_extra         *extra
         pcre_jit_callback  callback
         void               *data

       The extra argument must be the result of studying a pattern with PCRE_STUDY_JIT_COMPILE. There are three  cases
       for the values of the other two options:

         (1) If callback is NULL and data is NULL, an internal 32K block
             on the machine stack is used.

         (2) If callback is NULL and data is not NULL, data must be
             a valid JIT stack, the result of calling pcre_jit_stack_alloc().

         (3) If callback not NULL, it must point to a function that is called
             with data as an argument at the start of matching, in order to
             set up a JIT stack. If the result is NULL, the internal 32K stack
             is used; otherwise the return value must be a valid JIT stack,
             the result of calling pcre_jit_stack_alloc().

       You may safely assign the same JIT stack to more than one pattern, as long as they are all matched sequentially
       in the same thread. In a multithread application, each thread must use its own JIT stack.

       Strictly speaking, even more is allowed. You can assign the same stack to any number of  patterns  as  long  as
       they are not used for matching by multiple threads at the same time. For example, you can assign the same stack
       to all compiled patterns, and use a global mutex in the callback to wait until the stack is available for  use.
       However, this is an inefficient solution, and not recommended.

       This is a suggestion for how a typical multithreaded program might operate:

         During thread initalization
           thread_local_var = pcre_jit_stack_alloc(...)

         During thread exit
           pcre_jit_stack_free(thread_local_var)

         Use a one-line callback function
           return thread_local_var

       All  the  functions  described  in this section do nothing if JIT is not available, and pcre_assign_jit_stack()
       does nothing unless the extra argument is non-NULL and points to a pcre_extra block that is  the  result  of  a
       successful study with PCRE_STUDY_JIT_COMPILE.

JIT STACK FAQ

       (1) Why do we need JIT stacks?

       PCRE (and JIT) is a recursive, depth-first engine, so it needs a stack where the local data of the current node
       is pushed before checking its child nodes.  Allocating real machine stack on some platforms is  difficult.  For
       example, the stack chain needs to be updated every time if we extend the stack on PowerPC.  Although it is pos-
       sible, its updating time overhead decreases performance. So we do the recursion in memory.

       (2) Why don't we simply allocate blocks of memory with malloc()?

       Modern operating systems have a nice feature: they can reserve an address space instead of  allocating  memory.
       We  can  safely  allocate memory pages inside this address space, so the stack could grow without moving memory
       data (this is important because of pointers). Thus we can allocate 1M address space, and use only a single mem-
       ory page (usually 4K) if that is enough. However, we can still grow up to 1M anytime if needed.

       (3) Who "owns" a JIT stack?

       The owner of the stack is the user program, not the JIT studied pattern or anything else. The user program must
       ensure that if a stack is used by pcre_exec(), (that is, it is assigned to the pattern currently running), that
       stack  must not be used by any other threads (to avoid overwriting the same memory area). The best practice for
       multithreaded programs is to allocate a stack for each thread, and return this stack through the  JIT  callback
       function.

       (4) When should a JIT stack be freed?

       You  can free a JIT stack at any time, as long as it will not be used by pcre_exec() again. When you assign the
       stack to a pattern, only a pointer is set. There is no reference counting or any other magic. You can free  the
       patterns  and  stacks in any order, anytime. Just do not call pcre_exec() with a pattern pointing to an already
       freed stack, as that will cause SEGFAULT. (Also, do not free a stack currently used by pcre_exec()  in  another
       thread).  You can also replace the stack for a pattern at any time. You can even free the previous stack before
       assigning a replacement.

       (5) Should I allocate/free a stack every time before/after calling pcre_exec()?

       No, because this is too costly in terms of resources. However, you  could  implement  some  clever  idea  which
       release  the stack if it is not used in let's say two minutes. The JIT callback can help to achive this without
       keeping a list of the currently JIT studied patterns.

       (6) OK, the stack is for long term memory allocation. But what happens if a pattern causes stack overflow  with
       a stack of 1M? Is that 1M kept until the stack is freed?

       Especially  on  embedded sytems, it might be a good idea to release memory sometimes without freeing the stack.
       There is no API for this at the moment. Probably a function call which returns  with  the  currently  allocated
       memory  for  any  stack and another which allows releasing memory (shrinking the stack) would be a good idea if
       someone needs this.

       (7) This is too much of a headache. Isn't there any better solution for JIT stack handling?

       No, thanks to Windows. If POSIX threads were used everywhere, we could throw out this complicated API.

EXAMPLE CODE

       This is a single-threaded example that specifies a JIT stack without using a callback.

         int rc;
         int ovector[30];
         pcre *re;
         pcre_extra *extra;
         pcre_jit_stack *jit_stack;

         re = pcre_compile(pattern, 0, &error, &erroffset, NULL);
         /* Check for errors */
         extra = pcre_study(re, PCRE_STUDY_JIT_COMPILE, &error);
         jit_stack = pcre_jit_stack_alloc(32*1024, 512*1024);
         /* Check for error (NULL) */
         pcre_assign_jit_stack(extra, NULL, jit_stack);
         rc = pcre_exec(re, extra, subject, length, 0, 0, ovector, 30);
         /* Check results */
         pcre_free(re);
         pcre_free_study(extra);
         pcre_jit_stack_free(jit_stack);


SEE ALSO

       pcreapi(3)

AUTHOR

       Philip Hazel (FAQ by Zoltan Herczeg)
       University Computing Service
       Cambridge CB2 3QH, England.

REVISION

       Last updated: 26 November 2011
       Copyright (c) 1997-2011 University of Cambridge.



                                                                    PCREJIT(3)