QRegularExpression: add ways to force an immediate optimization

The fact that we kick in a pattern study and possibly a JIT compilation
after an undocumented number of usages is suboptimal, for a number
or reasons: users may want to JIT compile a pattern immediately,
and at the same time they may not want a random delay in the program
(due to the pattern getting optimized at a random usage).

So: add an optimize() call to force an immediate pattern optimization,
and a pattern option to force an optimization on the first usage.

Change-Id: I95efdecfd31f11ca7cceb9c05037df613601a11c
Reviewed-by: Lars Knoll <lars.knoll@digia.com>
Reviewed-by: Thiago Macieira <thiago.macieira@intel.com>

2 files changed, 51 insertions, 5 deletions

diff --git a/src/corelib/tools/qregularexpression.cpp b/src/corelib/tools/qregularexpression.cpp
index daa6765dcc..26988a4420 100644
--- a/src/corelib/tools/qregularexpression.cpp
+++ b/src/corelib/tools/qregularexpression.cpp
@@ -699,6 +699,12 @@ QT_BEGIN_NAMESPACE
         \c{\w} to match any character with either the Unicode L (letter) or N
         (digit) property, plus underscore, and so on. This option corresponds
         to the \c{/u} modifier in Perl regular expressions.
+
+    \value OptimizeOnFirstUsageOption
+        The regular expression will be optimized (and possibly
+        JIT-compiled) on its first usage, instead of after a certain (undefined)
+        number of usages. See also \l{QRegularExpression::}{optimize()}.
+        This enum value has been introduced in Qt 5.4.
 */
 
 /*!
@@ -802,7 +808,13 @@ struct QRegularExpressionPrivate : QSharedData
     void cleanCompiledPattern();
     void compilePattern();
     void getPatternInfo();
-    void optimizePattern();
+
+    enum OptimizePatternOption {
+        LazyOptimizeOption,
+        ImmediateOptimizeOption
+    };
+
+    void optimizePattern(OptimizePatternOption option);
 
     QRegularExpressionMatchPrivate *doMatch(const QString &subject,
                                             int offset,
@@ -1107,13 +1119,16 @@ static bool isJitEnabled()
     (localStudyData) before using storeRelease on studyData. In doMatch there's
     the corresponding loadAcquire.
 */
-void QRegularExpressionPrivate::optimizePattern()
+void QRegularExpressionPrivate::optimizePattern(OptimizePatternOption option)
 {
     Q_ASSERT(compiledPattern);
 
     QMutexLocker lock(&mutex);
 
-    if (studyData.load() || (++usedCount != qt_qregularexpression_optimize_after_use_count))
+    if (studyData.load()) // already optimized
+        return;
+
+    if ((option == LazyOptimizeOption) && (++usedCount != qt_qregularexpression_optimize_after_use_count))
         return;
 
     static const bool enableJit = isJitEnabled();
@@ -1233,8 +1248,13 @@ QRegularExpressionMatchPrivate *QRegularExpressionPrivate::doMatch(const QString
                                                                               matchType, matchOptions,
                                                                               capturingCount + 1);
 
+    const OptimizePatternOption optimizePatternOption =
+            (patternOptions & QRegularExpression::OptimizeOnFirstUsageOption)
+                ? ImmediateOptimizeOption
+                : LazyOptimizeOption;
+
     // this is mutex protected
-    const_cast<QRegularExpressionPrivate *>(this)->optimizePattern();
+    const_cast<QRegularExpressionPrivate *>(this)->optimizePattern(optimizePatternOption);
 
     // work with a local copy of the study data, as we are running pcre_exec
     // potentially more than once, and we don't want to run call it
@@ -1667,6 +1687,27 @@ QRegularExpressionMatchIterator QRegularExpression::globalMatch(const QString &s
 }
 
 /*!
+    \since 5.4
+
+    Forces an immediate optimization of the pattern, including
+    JIT-compiling it (if the JIT compiler is enabled).
+
+    Patterns are normally optimized only after a certain number of usages.
+    If you can predict that this QRegularExpression object is going to be
+    used for several matches, it may be convenient to optimize it in
+    advance by calling this function.
+
+    \sa QRegularExpression::OptimizeOnFirstUsageOption
+*/
+void QRegularExpression::optimize()
+{
+    if (!isValid()) // will compile the pattern
+        return;
+
+    d->optimizePattern(QRegularExpressionPrivate::ImmediateOptimizeOption);
+}
+
+/*!
     Returns \c true if the regular expression is equal to \a re, or false
     otherwise. Two QRegularExpression objects are equal if they have
     the same pattern string and the same pattern options.
@@ -2327,6 +2368,8 @@ QDebug operator<<(QDebug debug, QRegularExpression::PatternOptions patternOption
             flags.append("DontCaptureOption|");
         if (patternOptions & QRegularExpression::UseUnicodePropertiesOption)
             flags.append("UseUnicodePropertiesOption|");
+        if (patternOptions & QRegularExpression::OptimizeOnFirstUsageOption)
+            flags.append("OptimizeOnFirstUsageOption|");
         flags.chop(1);
     }
 
diff --git a/src/corelib/tools/qregularexpression.h b/src/corelib/tools/qregularexpression.h
index 5059ea6431..6154ea7c51 100644
--- a/src/corelib/tools/qregularexpression.h
+++ b/src/corelib/tools/qregularexpression.h
@@ -69,7 +69,8 @@ public:
         ExtendedPatternSyntaxOption    = 0x0008,
         InvertedGreedinessOption       = 0x0010,
         DontCaptureOption              = 0x0020,
-        UseUnicodePropertiesOption     = 0x0040
+        UseUnicodePropertiesOption     = 0x0040,
+        OptimizeOnFirstUsageOption     = 0x0080
     };
     Q_DECLARE_FLAGS(PatternOptions, PatternOption)
 
@@ -122,6 +123,8 @@ public:
                                                 MatchType matchType       = NormalMatch,
                                                 MatchOptions matchOptions = NoMatchOption) const;
 
+    void optimize();
+
     static QString escape(const QString &str);
 
     bool operator==(const QRegularExpression &re) const;