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
38 If --enable-jit is set on an unsupported platform, compilation fails.
40 A program can tell if JIT support is available by calling \fBpcre2_config()\fP
41 with the PCRE2_CONFIG_JIT option. The result is 1 when JIT is available, and 0
43 use JIT. The API is implemented in a way that falls back to the interpretive
44 code if JIT is not available. For programs that need the best possible
45 performance, there is also a "fast path" API that is JIT-specific.
51 To make use of the JIT support in the simplest way, all you have to do is to
53 \fBpcre2_compile()\fP. This function has two arguments: the first is the
55 second is zero or more of the following option bits: PCRE2_JIT_COMPLETE,
58 If JIT support is not available, a call to \fBpcre2_jit_compile()\fP does
62 results. The returned value from \fBpcre2_jit_compile()\fP is zero on success,
65 There is a limit to the size of pattern that JIT supports, imposed by the size
68 If a pattern is too big, a call to \fBpcre2_jit_compile()\fP returns
76 (normal, soft partial, hard partial). When \fBpcre2_match()\fP is called, the
77 appropriate code is run if it is available. Otherwise, the pattern is matched
86 \fBpcre2_jit_compile()\fP is called with no option bits set, it immediately
87 returns zero. This is an alternative way of testing whether JIT is available.
89 At present, it is not possible to free JIT compiled code except when the entire
90 compiled pattern is freed by calling \fBpcre2_code_free()\fP.
111 callback function is called whenever JIT code is about to be obeyed. If the
112 match-time options are not right for JIT execution, the callback function is
115 If the JIT compiler finds an unsupported item, no JIT data is generated. You
116 can find out if JIT matching is available after compiling a pattern by calling
119 support is not available, or the pattern was not processed by
127 When a pattern is compiled with the PCRE2_UTF option, subject strings are
128 normally expected to be a valid sequence of UTF code units. By default, this is
129 checked at the start of matching and an error is generated if invalid UTF is
132 is valid. If this option is used with an invalid string, the result is
136 sequences is available. Calling \fBpcre2_compile()\fP with the
140 support works, in both the JIT and the interpretive cases, is given in the
146 There is also an obsolete option for \fBpcre2_jit_compile()\fP called
148 It is superseded by the \fBpcre2_compile()\fP option PCRE2_MATCH_INVALID_UTF
161 If the PCRE2_NO_JIT option is passed to \fBpcre2_match()\fP it disables the
172 When a pattern is matched using JIT matching, the return values are the same
182 The error code PCRE2_ERROR_MATCHLIMIT is returned by the JIT code if searching
183 a very large pattern tree goes on for too long, as it is in the same
184 circumstance when JIT is not used, but the details of exactly what is counted
185 are not the same. The PCRE2_ERROR_DEPTHLIMIT error code is never returned
186 when JIT matching is used.
196 is given when there is not enough stack. Three functions are provided for
197 managing blocks of memory for use as JIT stacks. There is further discussion
209 is an error. The \fBpcre2_jit_stack_free()\fP function is used to free a stack
210 that is no longer needed. If its argument is NULL, this function returns
212 space is allocated by mmap or VirtualAlloc.) A maximum stack size of 512KiB to
222 The first argument is a pointer to a match context. When this is subsequently
223 passed to a matching function, its information determines which JIT stack is
224 used. If this argument is NULL, the function returns immediately, without doing
227   (1) If \fIcallback\fP is NULL and \fIdata\fP is NULL, an internal 32KiB block
228       on the machine stack is used. This is the default when a match
229       context is created.
231   (2) If \fIcallback\fP is NULL and \fIdata\fP is not NULL, \fIdata\fP must be
235   (3) If \fIcallback\fP is not NULL, it must point to a function that is
238       function is NULL, the internal 32KiB stack is used; otherwise the
242 A callback function is obeyed whenever JIT code is about to be run; it is not
243 obeyed when \fBpcre2_match()\fP is called with options that are incompatible
250 non-sequential matches in one thread is to use callouts: if a callout function
255 assign or pass back NULL from a callback, that is thread-safe, because each
258 application is thread-safe.
260 Strictly speaking, even more is allowed. You can assign the same non-NULL stack
261 to a match context that is used by any number of patterns, as long as they are
264 callback to wait until the stack is available for use. However, this is an
267 This is a suggestion for how a multithreaded program that needs to set up
279 All the functions described in this section do nothing if JIT is not available.
288 PCRE2 (and JIT) is a recursive, depth-first engine, so it needs a stack where
289 the local data of the current node is pushed before checking its child nodes.
290 Allocating real machine stack on some platforms is difficult. For example, the
292 Although it is possible, its updating time overhead decreases performance. So
299 address space, so the stack could grow without moving memory data (this is
301 use only a single memory page (usually 4KiB) if that is enough. However, we can
306 The owner of the stack is the user program, not the JIT studied pattern or
307 anything else. The user program must ensure that if a stack is being used by
308 \fBpcre2_match()\fP, (that is, it is assigned to a match context that is passed
311 multithreaded programs is to allocate a stack for each thread, and return this
318 pointer is set. There is no reference counting or any other magic. You can free
323 the stack in a context at any time when it is not in use. You should free the
329 No, because this is too costly in terms of resources. However, you could
330 implement some clever idea which release the stack if it is not used in let's
334 (6) OK, the stack is for long term memory allocation. But what happens if a
335 pattern causes stack overflow with a stack of 1MiB? Is that 1MiB kept until the
336 stack is freed?
339 sometimes without freeing the stack. There is no API for this at the moment.
344 (7) This is too much of a headache. Isn't there any better solution for JIT
358 The JIT executable allocator does not free all memory when it is possible. It
362 pcre2_jit_free_unused_memory(). Its argument is a general context, for custom
369 This is a single-threaded example that specifies a JIT stack without using a
399 Because the API described above falls back to interpreted matching when JIT is
400 not available, it is convenient for programs that are written for general use
402 performance impact. Programs that are written for use where JIT is known to be
408 The fast path function is called \fBpcre2_jit_match()\fP, and it takes exactly
410 specified with a length; PCRE2_ZERO_TERMINATED is not supported. Unsupported
412 PCRE2_COPY_MATCHED_SUBJECT) are ignored, as is the PCRE2_NO_JIT option. The
414 PCRE2_ERROR_JIT_BADOPTION if a matching mode (partial or complete) is requested
419 the subject pointer is NULL but the length is non-zero, an immediate error is
420 given. Also, unless PCRE2_NO_UTF_CHECK is set, a UTF subject string is tested
422 fast path, and if invalid data is passed, the result is undefined.