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()\fP 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
126 When a pattern is compiled with the PCRE2_UTF option, subject strings are
127 normally expected to be a valid sequence of UTF code units. By default, this is
128 checked at the start of matching and an error is generated if invalid UTF is
131 is valid. If this option is used with an invalid string, the result is
135 sequences is available. Calling \fBpcre2_compile()\fP with the
139 support works, in both the JIT and the interpretive cases, is given in the
145 There is also an obsolete option for \fBpcre2_jit_compile()\fP called
147 It is superseded by the \fBpcre2_compile()\fP option PCRE2_MATCH_INVALID_UTF
160 If the PCRE2_NO_JIT option is passed to \fBpcre2_match()\fP it disables the
171 When a pattern is matched using JIT matching, the return values are the same
181 The error code PCRE2_ERROR_MATCHLIMIT is returned by the JIT code if searching
182 a very large pattern tree goes on for too long, as it is in the same
183 circumstance when JIT is not used, but the details of exactly what is counted
184 are not the same. The PCRE2_ERROR_DEPTHLIMIT error code is never returned
185 when JIT matching is used.
195 is given when there is not enough stack. Three functions are provided for
196 managing blocks of memory for use as JIT stacks. There is further discussion
208 is an error. The \fBpcre2_jit_stack_free()\fP function is used to free a stack
209 that is no longer needed. If its argument is NULL, this function returns
211 space is allocated by mmap or VirtualAlloc.) A maximum stack size of 512KiB to
221 The first argument is a pointer to a match context. When this is subsequently
222 passed to a matching function, its information determines which JIT stack is
223 used. If this argument is NULL, the function returns immediately, without doing
226   (1) If \fIcallback\fP is NULL and \fIdata\fP is NULL, an internal 32KiB block
227       on the machine stack is used. This is the default when a match
228       context is created.
230   (2) If \fIcallback\fP is NULL and \fIdata\fP is not NULL, \fIdata\fP must be
234   (3) If \fIcallback\fP is not NULL, it must point to a function that is
237       function is NULL, the internal 32KiB stack is used; otherwise the
241 A callback function is obeyed whenever JIT code is about to be run; it is not
242 obeyed when \fBpcre2_match()\fP is called with options that are incompatible
249 non-sequential matches in one thread is to use callouts: if a callout function
257 each thread so that the application is thread-safe.
259 Strictly speaking, even more is allowed. You can assign the same non-NULL stack
260 to a match context that is used by any number of patterns, as long as they are
263 callback to wait until the stack is available for use. However, this is an
266 This is a suggestion for how a multithreaded program that needs to set up
278 All the functions described in this section do nothing if JIT is not available.
287 PCRE2 (and JIT) is a recursive, depth-first engine, so it needs a stack where
288 the local data of the current node is pushed before checking its child nodes.
289 Allocating real machine stack on some platforms is difficult. For example, the
291 Although it is possible, its updating time overhead decreases performance. So
298 address space, so the stack could grow without moving memory data (this is
300 use only a single memory page (usually 4KiB) if that is enough. However, we can
305 The owner of the stack is the user program, not the JIT studied pattern or
306 anything else. The user program must ensure that if a stack is being used by
307 \fBpcre2_match()\fP, (that is, it is assigned to a match context that is passed
310 multithreaded programs is to allocate a stack for each thread, and return this
317 pointer is set. There is no reference counting or any other magic. You can free
322 the stack in a context at any time when it is not in use. You should free the
328 No, because this is too costly in terms of resources. However, you could
329 implement some clever idea which release the stack if it is not used in let's
333 (6) OK, the stack is for long term memory allocation. But what happens if a
334 pattern causes stack overflow with a stack of 1MiB? Is that 1MiB kept until the
335 stack is freed?
338 sometimes without freeing the stack. There is no API for this at the moment.
343 (7) This is too much of a headache. Isn't there any better solution for JIT
357 The JIT executable allocator does not free all memory when it is possible.
361 pcre2_jit_free_unused_memory(). Its argument is a general context, for custom
368 This is a single-threaded example that specifies a JIT stack without using a
398 Because the API described above falls back to interpreted matching when JIT is
399 not available, it is convenient for programs that are written for general use
401 performance impact. Programs that are written for use where JIT is known to be
407 The fast path function is called \fBpcre2_jit_match()\fP, and it takes exactly
409 specified with a length; PCRE2_ZERO_TERMINATED is not supported. Unsupported
411 PCRE2_COPY_MATCHED_SUBJECT) are ignored, as is the PCRE2_NO_JIT option. The
413 PCRE2_ERROR_JIT_BADOPTION if a matching mode (partial or complete) is requested
418 the subject pointer is NULL, an immediate error is given. Also, unless
419 PCRE2_NO_UTF_CHECK is set, a UTF subject string is tested for validity. In the
421 invalid data is passed, the result is undefined.