Lines Matching full:is

7 Just-in-time compiling is a heavyweight optimization that can greatly speed up
9 match is performed, so it is of most benefit when the same pattern is going to
11 function; if the pattern is not anchored, matching attempts may take place many
13 if the subject string is very long, it may still pay to use JIT even for
14 one-off matches. JIT support is available for all of the 8-bit, 16-bit and
18 It does not apply when the DFA matching function is being used. The code for
25 JIT support is an optional feature of PCRE2. The "configure" option
26 --enable-jit (or equivalent CMake option) must be set when PCRE2 is built if
27 you want to use JIT. The support is limited to the following hardware
37 If --enable-jit is set on an unsupported platform, compilation fails.
39 A program can tell if JIT support is available by calling \fBpcre2_config()\fP
40 with the PCRE2_CONFIG_JIT option. The result is 1 when JIT is available, and 0
42 use JIT. The API is implemented in a way that falls back to the interpretive
43 code if JIT is not available. For programs that need the best possible
44 performance, there is also a "fast path" API that is JIT-specific.
50 To make use of the JIT support in the simplest way, all you have to do is to
52 \fBpcre2_compile()\fP. This function has two arguments: the first is the
54 second is zero or more of the following option bits: PCRE2_JIT_COMPLETE,
57 If JIT support is not available, a call to \fBpcre2_jit_compile()\fP does
61 results. The returned value from \fBpcre2_jit_compile()\fP is zero on success,
64 There is a limit to the size of pattern that JIT supports, imposed by the size
67 If a pattern is too big, a call to \fBpcre2_jit_compile()\fB returns
75 (normal, soft partial, hard partial). When \fBpcre2_match()\fP is called, the
76 appropriate code is run if it is available. Otherwise, the pattern is matched
85 \fBpcre2_jit_compile()\fP is called with no option bits set, it immediately
86 returns zero. This is an alternative way of testing whether JIT is available.
88 At present, it is not possible to free JIT compiled code except when the entire
89 compiled pattern is freed by calling \fBpcre2_code_free()\fP.
110 callback function is called whenever JIT code is about to be obeyed. If the
111 match-time options are not right for JIT execution, the callback function is
114 If the JIT compiler finds an unsupported item, no JIT data is generated. You
115 can find out if JIT matching is available after compiling a pattern by calling
118 support is not available, or the pattern was not processed by
129 PCRE2_ANCHORED option is not supported at match time.
131 If the PCRE2_NO_JIT option is passed to \fBpcre2_match()\fP it disables the
142 When a pattern is matched using JIT matching, the return values are the same
152 The error code PCRE2_ERROR_MATCHLIMIT is returned by the JIT code if searching
153 a very large pattern tree goes on for too long, as it is in the same
154 circumstance when JIT is not used, but the details of exactly what is counted
155 are not the same. The PCRE2_ERROR_DEPTHLIMIT error code is never returned
156 when JIT matching is used.
166 is given when there is not enough stack. Three functions are provided for
167 managing blocks of memory for use as JIT stacks. There is further discussion
179 is an error. The \fBpcre2_jit_stack_free()\fP function is used to free a stack
180 that is no longer needed. If its argument is NULL, this function returns
182 space is allocated by mmap or VirtualAlloc.) A maximum stack size of 512KiB to
192 The first argument is a pointer to a match context. When this is subsequently
193 passed to a matching function, its information determines which JIT stack is
194 used. If this argument is NULL, the function returns immediately, without doing
197   (1) If \fIcallback\fP is NULL and \fIdata\fP is NULL, an internal 32KiB block
198       on the machine stack is used. This is the default when a match
199       context is created.
201   (2) If \fIcallback\fP is NULL and \fIdata\fP is not NULL, \fIdata\fP must be
205   (3) If \fIcallback\fP is not NULL, it must point to a function that is
208       function is NULL, the internal 32KiB stack is used; otherwise the
212 A callback function is obeyed whenever JIT code is about to be run; it is not
213 obeyed when \fBpcre2_match()\fP is called with options that are incompatible
220 non-sequential matches in one thread is to use callouts: if a callout function
228 each thread so that the application is thread-safe.
230 Strictly speaking, even more is allowed. You can assign the same non-NULL stack
231 to a match context that is used by any number of patterns, as long as they are
234 callback to wait until the stack is available for use. However, this is an
237 This is a suggestion for how a multithreaded program that needs to set up
249 All the functions described in this section do nothing if JIT is not available.
258 PCRE2 (and JIT) is a recursive, depth-first engine, so it needs a stack where
259 the local data of the current node is pushed before checking its child nodes.
260 Allocating real machine stack on some platforms is difficult. For example, the
262 Although it is possible, its updating time overhead decreases performance. So
269 address space, so the stack could grow without moving memory data (this is
271 use only a single memory page (usually 4KiB) if that is enough. However, we can
276 The owner of the stack is the user program, not the JIT studied pattern or
277 anything else. The user program must ensure that if a stack is being used by
278 \fBpcre2_match()\fP, (that is, it is assigned to a match context that is passed
281 multithreaded programs is to allocate a stack for each thread, and return this
288 pointer is set. There is no reference counting or any other magic. You can free
293 in a context at any time when it is not in use. You should free the previous
299 No, because this is too costly in terms of resources. However, you could
300 implement some clever idea which release the stack if it is not used in let's
304 (6) OK, the stack is for long term memory allocation. But what happens if a
305 pattern causes stack overflow with a stack of 1MiB? Is that 1MiB kept until the
306 stack is freed?
309 sometimes without freeing the stack. There is no API for this at the moment.
314 (7) This is too much of a headache. Isn't there any better solution for JIT
328 The JIT executable allocator does not free all memory when it is possible.
332 pcre2_jit_free_unused_memory(). Its argument is a general context, for custom
339 This is a single-threaded example that specifies a JIT stack without using a
369 Because the API described above falls back to interpreted matching when JIT is
370 not available, it is convenient for programs that are written for general use
372 performance impact. Programs that are written for use where JIT is known to be
378 The fast path function is called \fBpcre2_jit_match()\fP, and it takes exactly
380 plus PCRE2_ERROR_JIT_BADOPTION if a matching mode (partial or complete) is
382 PCRE2_ANCHORED) are ignored, as is the PCRE2_NO_JIT option.
386 the subject pointer is NULL, an immediate error is given. Also, unless
387 PCRE2_NO_UTF_CHECK is set, a UTF subject string is tested for validity. In the
389 invalid data is passed, the result is undefined.