Revision: 126
http://www.exim.org/viewvc/pcre2?view=rev&revision=126
Author: ph10
Date: 2014-10-27 10:13:57 +0000 (Mon, 27 Oct 2014)
Log Message:
-----------
Document pcre2_jit_free_unused_memory().
Modified Paths:
--------------
code/trunk/doc/pcre2_jit_free_unused_memory.3
code/trunk/doc/pcre2jit.3
Modified: code/trunk/doc/pcre2_jit_free_unused_memory.3
===================================================================
--- code/trunk/doc/pcre2_jit_free_unused_memory.3 2014-10-26 18:00:19 UTC (rev 125)
+++ code/trunk/doc/pcre2_jit_free_unused_memory.3 2014-10-27 10:13:57 UTC (rev 126)
@@ -1,4 +1,4 @@
-.TH PCRE2_JIT_FREE_UNUSED_MEMORY 3 "24 October 2014" "PCRE2 10.00"
+.TH PCRE2_JIT_FREE_UNUSED_MEMORY 3 "27 October 2014" "PCRE2 10.00"
.SH NAME
PCRE2 - Perl-compatible regular expressions (revised API)
.SH SYNOPSIS
@@ -15,7 +15,10 @@
.sp
This function frees unused JIT executable memory. The argument is a general
context, for custom memory management, or NULL for standard memory management.
-FIXME: more detail needed.
+JIT memory allocation retains some memory in order to improve future JIT
+compilation speed. In low memory conditions,
+\fBpcre2_jit_free_unused_memory()\fB can be used to cause this memory to be
+freed.
.P
There is a complete description of the PCRE2 native API in the
.\" HREF
Modified: code/trunk/doc/pcre2jit.3
===================================================================
--- code/trunk/doc/pcre2jit.3 2014-10-26 18:00:19 UTC (rev 125)
+++ code/trunk/doc/pcre2jit.3 2014-10-27 10:13:57 UTC (rev 126)
@@ -1,11 +1,9 @@
-.TH PCRE2JIT 3 "21 October 2014" "PCRE2 10.00"
+.TH PCRE2JIT 3 "27 October 2014" "PCRE2 10.00"
.SH NAME
PCRE2 - Perl-compatible regular expressions (revised API)
.SH "PCRE2 JUST-IN-TIME COMPILER SUPPORT"
.rs
.sp
-FIXME: This needs checking over once JIT support is implemented.
-.P
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
@@ -55,9 +53,12 @@
second is a set of option bits, which must include at least one of
PCRE2_JIT_COMPLETE, PCRE2_JIT_PARTIAL_HARD, or PCRE2_JIT_PARTIAL_SOFT.
.P
-The returned value from \fBpcre2_jit_compile()\fP is zero on success, or a
-negative error code. In particular, PCRE2_ERROR_JIT_BADOPTION is returned if
-JIT is not supported or if an unknown options bit is set.
+If JIT support is not available, a call to \fBpcre2_jit_comple()\fP does
+nothing and returns PCRE2_ERROR_JIT_BADOPTION. 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, but yields exactly the same
+results. The returned value from \fBpcre2_jit_compile()\fP is zero on success,
+or a negative error code.
.P
PCRE2_JIT_COMPLETE requests the JIT compiler to generate code for complete
matches. If you want to run partial matches using the PCRE2_PARTIAL_HARD or
@@ -76,11 +77,6 @@
.\"
below.
.P
-If JIT support is not available, a call to \fBpcre2_jit_comple()\fP does
-nothing and returns FIXME. 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, but yields exactly the same results.
-.P
There are some \fBpcre2_match()\fP options that are not supported by JIT, and
there are also some pattern items that JIT cannot handle. Details are given
below. In both cases, matching automatically falls back to the interpretive
@@ -296,6 +292,21 @@
out this complicated API.
.
.
+.SH "FREEING JIT SPECULATIVE MEMORY"
+.rs
+.sp
+.nf
+.B void pcre2_jit_free_unused_memory(pcre2_general_context *\fIgcontext\fP);
+.fi
+.P
+The JIT executable allocator does not free all memory when it is possible.
+It expects new allocations, and keeps some free memory around to improve
+allocation speed. However, in low memory conditions, it might be better to free
+all possible memory. You can cause this to happen by calling
+pcre2_jit_free_unused_memory(). Its argument is a general context, for custom
+memory management, or NULL for standard memory management.
+.
+.
.SH "EXAMPLE CODE"
.rs
.sp
@@ -375,6 +386,6 @@
.rs
.sp
.nf
-Last updated: 21 October 2014
+Last updated: 27 October 2014
Copyright (c) 1997-2014 University of Cambridge.
.fi
