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
PCRE_STUDY_JIT_COMPILE requests the JIT compiler to generate code
for complete matches. If you want to run partial matches using
the PCRE_PARTIAL_HARD or PCRE_PARTIAL_SOFT options of
pcre_exec(), you should set one or both of the following options
in addition to, or instead of, PCRE_STUDY_JIT_COMPILE when you
call pcre_study():
PCRE_STUDY_JIT_PARTIAL_HARD_COMPILE
PCRE_STUDY_JIT_PARTIAL_SOFT_COMPILE
If using pcre_jit_exec() and supporting a pre-8.32 version of
PCRE, you can insert:
#if PCRE_MAJOR >= 8 && PCRE_MINOR >= 32
pcre_jit_exec(...);
#else
pcre_exec(...)
#endif
but as described in the "JIT FAST PATH API" section below this
assumes version 8.32 and later are compiled with --enable-jit,
which may break.
The JIT compiler generates different optimized code for each of
the three modes (normal, soft partial, hard partial). When
pcre_exec() is called, the appropriate code is run if it is
available. Otherwise, the pattern is matched using interpretive
code.
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 etc. are
ignored, and no JIT data is created. 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 of the appropriate mode (normal
or hard/soft partial), it obeys that code instead of running the
interpreter. The result is identical, but the compiled JIT 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 you want to
know whether JIT was actually used for a particular match, you
should arrange for a JIT callback function to be set up as
described in the section entitled "Controlling the JIT stack"
below, even if you do not need to supply a non-default JIT stack.
Such a callback function is called whenever JIT code is about to
be obeyed. If the execution options are not right for JIT
execution, the callback function is not obeyed.
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 pattern was not studied with
PCRE_STUDY_JIT_COMPILE etc., 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.
