Make the JNI-internal metrics opt-in rather than opt-out so client builds won't have them by default. Unrelated doc tweaks.

FossilOrigin-Name: aa72d25a22c80a7a376127266b8923f0661147c8bc483baa327230364851a255

ext/jni/GNUmakefile

@@ -177,6 +177,7 @@ $(sqlite3.c): $(sqlite3.h)
 opt.threadsafe ?= 1
 opt.fatal-oom ?= 1
 opt.debug ?= 1
+opt.metrics ?= 1
 SQLITE_OPT = \
   -DSQLITE_ENABLE_RTREE \
   -DSQLITE_ENABLE_EXPLAIN_COMMENTS \
@@ -194,7 +195,8 @@ SQLITE_OPT = \
   -DSQLITE_TEMP_STORE=2 \
   -DSQLITE_USE_URI=1 \
   -DSQLITE_C=$(sqlite3.c) \
-  -DSQLITE_JNI_FATAL_OOM=$(opt.fatal-oom)
+  -DSQLITE_JNI_FATAL_OOM=$(opt.fatal-oom) \
+  -DSQLITE_JNI_ENABLE_METRICS=$(opt.metrics)
 
 ifeq (1,$(opt.debug))
   SQLITE_OPT += -DSQLITE_DEBUG -g -DDEBUG -UNDEBUG

ext/jni/src/c/sqlite3-jni.c

@@ -420,8 +420,8 @@ struct S3JniHook{
   /* We lookup the jObj.xDestroy() method as-needed for contexts which
   ** have custom finalizers. */
   jobject jExtra          /* Global ref to a per-hook-type value */;
-  int doXDestroy          /* If true call jObj->xDestroy() when
-                             this object is S3JniHook_unref()'d. */;
+  int doXDestroy          /* If true then S3JniHook_unref() will call
+                             jObj->xDestroy() if it's available. */;
   S3JniHook * pNext      /* Next entry in S3Global.hooks.aFree */;
 };
 /* For clean bitwise-copy init of local instances. */
@@ -543,10 +543,8 @@ struct S3JniUdf {
   S3JniUdf * pNext       /* Next entry in SJG.udf.aFree. */;
 };
 
-#if !defined(SQLITE_JNI_OMIT_METRICS) && !defined(SQLITE_JNI_ENABLE_METRICS)
-#  ifdef SQLITE_DEBUG
-#    define SQLITE_JNI_ENABLE_METRICS
-#  endif
+#if defined(SQLITE_JNI_ENABLE_METRICS) && 0==SQLITE_JNI_ENABLE_METRICS
+#  undef SQLITE_JNI_ENABLE_METRICS
 #endif
 
 /*
@@ -1105,10 +1103,10 @@ static void s3jni__call_xDestroy(JNIEnv * const env, jobject jObj){
 
 /*
 ** Internal helper for many hook callback impls. Locks the S3JniDb
-** mutex, makes a copy of src into dest, with a some differences: (1) if
-** src->jObj or src->jExtra are not NULL then dest will be a new LOCAL
-** ref to it instead of a copy of the prior GLOBAL ref. (2) dest->doXDestroy
-** is always false.
+** mutex, makes a copy of src into dest, with a some differences: (1)
+** if src->jObj or src->jExtra are not NULL then dest will be a new
+** LOCAL ref to it instead of a copy of the prior GLOBAL ref. (2)
+** dest->doXDestroy is always false.
 **
 ** If dest->jObj is not NULL when this returns then the caller is
 ** obligated to eventually free the new ref by passing *dest to
@@ -1186,8 +1184,8 @@ static S3JniHook *S3JniHook__alloc(JNIEnv  * const env){
 #define S3JniHook_alloc() S3JniHook__alloc(env)
 
 /*
-** The rightful fate of all results from S3JniHook_alloc(). doXDestroy
-** is passed on as-is to S3JniHook_unref(). Locks the global mutex.
+** The rightful fate of all results from S3JniHook_alloc(). Locks the
+** global mutex.
 */
 static void S3JniHook__free(JNIEnv  * const env, S3JniHook * const p){
   if(p){
@@ -1637,7 +1635,7 @@ static int encodingTypeIsValid(int eTextRep){
 }
 
 /* For use with sqlite3_result/value_pointer() */
-#define ResultJavaValuePtrStr "org.sqlite.jni.ResultJavaVal"
+static const char * const ResultJavaValuePtrStr = "org.sqlite.jni.ResultJavaVal";
 
 /*
 ** If v is not NULL, it must be a jobject global reference. Its
@@ -1804,7 +1802,9 @@ typedef struct {
 ** Converts the given (cx, argc, argv) into arguments for the given
 ** UDF, writing the result (Java wrappers for cx and argv) in the
 ** final 2 arguments. Returns 0 on success, SQLITE_NOMEM on allocation
-** error. On error *jCx and *jArgv will be set to 0.
+** error. On error *jCx and *jArgv will be set to 0. The output
+** objects are of type org.sqlite.jni.sqlite3_context and
+** array-of-org.sqlite3.jni.sqlite3_value, respectively.
 */
 static int udf_args(JNIEnv *env,
                     sqlite3_context * const cx,
@@ -2831,8 +2831,10 @@ S3JniApi(sqlite3_context_db_handle(),jobject,1context_1db_1handle)(
   return ps ? ps->jDb : 0;
 }
 
-/**
-   State for CollationCallbacks.
+/*
+** State for CollationCallbacks. This used to be its own separate
+** type, but has since been consolidated with S3JniHook. It retains
+** its own typedef for code legibility and searchability reasons.
 */
 typedef S3JniHook S3JniCollationCallback;
 
@@ -2915,7 +2917,8 @@ S3JniApi(sqlite3_create_collation() sqlite3_create_collation_v2(),
   return (jint)rc;
 }
 
-S3JniApi(sqlite3_create_function() sqlite3_create_function_v2() sqlite3_create_window_function(),
+S3JniApi(sqlite3_create_function() sqlite3_create_function_v2()
+         sqlite3_create_window_function(),
          jint,1create_1function
 )(JniArgsEnvClass, jobject jDb, jstring jFuncName, jint nArg,
   jint eTextRep, jobject jFunctor){

ext/jni/src/org/sqlite/jni/SQLite3Jni.java

@@ -217,13 +217,19 @@ public final class SQLite3Jni {
 
   /**
      Requires that paramName be a NUL-terminated UTF-8 string.
+
+     This overload is private because: (A) to keep users from
+     inadvertently passing non-NUL-terminated byte arrays (an easy
+     thing to do). (B) it is cheaper to NUL-terminate the
+     String-to-byte-array conversion in the public-facing Java-side
+     overload than to do that in C, so that signature is the
+     public-facing one.
   */
   @Canonical
-  public static native int sqlite3_bind_parameter_index(
-    @NotNull sqlite3_stmt stmt, byte[] paramName
+  private static native int sqlite3_bind_parameter_index(
+    @NotNull sqlite3_stmt stmt, @NotNull byte[] paramName
   );
 
-  @Canonical
   public static int sqlite3_bind_parameter_index(
     @NotNull sqlite3_stmt stmt, @NotNull String paramName
   ){
@@ -316,9 +322,9 @@ public final class SQLite3Jni {
   );
 
   /**
-     As for the C-level function of the same name, with a BusyHandlerCallback
-     instance in place of a callback function. Pass it a null handler
-     to clear the busy handler.
+     As for the C-level function of the same name, with a
+     BusyHandlerCallback instance in place of a callback
+     function. Pass it a null handler to clear the busy handler.
   */
   @Canonical
   public static native int sqlite3_busy_handler(
@@ -420,6 +426,8 @@ public final class SQLite3Jni {
      stress that the returned bytes are encoded as UTF-8. It returns
      null if the underlying C-level sqlite3_column_text() returns NULL
      or on allocation error.
+
+     @see #sqlite3_column_text16(sqlite3_stmt,int)
   */
   @Canonical
   public static native byte[] sqlite3_column_text(
@@ -480,7 +488,7 @@ public final class SQLite3Jni {
 
   /**
      This functions like C's sqlite3_collation_needed16() because
-     Java's string type is compatible with that interface.
+     Java's string type is inherently compatible with that interface.
   */
   @Canonical
   public static native int sqlite3_collation_needed(
@@ -1344,7 +1352,7 @@ public final class SQLite3Jni {
 
   /**
      Internal impl of the public sqlite3_strglob() method. Neither
-     argument may be NULL and both MUST be NUL-terminated UTF-8.
+     argument may be null and both must be NUL-terminated UTF-8.
 
      This overload is private because: (A) to keep users from
      inadvertently passing non-NUL-terminated byte arrays (an easy

manifest

@@ -1,5 +1,5 @@
-C Make\sJNI\sinterfaces\sof\ssqlite3_column/value_text()\smatch\sthe\sC\sones\sbetter.\sInternal\sJNI\scleanups\sand\ssimplifications.
-D 2023-09-01T13:27:59.308
+C Make\sthe\sJNI-internal\smetrics\sopt-in\srather\sthan\sopt-out\sso\sclient\sbuilds\swon't\shave\sthem\sby\sdefault.\sUnrelated\sdoc\stweaks.
+D 2023-09-01T14:20:39.576
 F .fossil-settings/empty-dirs dbb81e8fc0401ac46a1491ab34a7f2c7c0452f2f06b54ebb845d024ca8283ef1
 F .fossil-settings/ignore-glob 35175cdfcf539b2318cb04a9901442804be81cd677d8b889fcc9149c21f239ea
 F LICENSE.md df5091916dbb40e6e9686186587125e1b2ff51f022cc334e886c19a0e9982724
@@ -234,10 +234,10 @@ F ext/fts5/tool/showfts5.tcl d54da0e067306663e2d5d523965ca487698e722c
 F ext/icu/README.txt 7ab7ced8ae78e3a645b57e78570ff589d4c672b71370f5aa9e1cd7024f400fc9
 F ext/icu/icu.c c074519b46baa484bb5396c7e01e051034da8884bad1a1cb7f09bbe6be3f0282
 F ext/icu/sqliteicu.h fa373836ed5a1ee7478bdf8a1650689294e41d0c89c1daab26e9ae78a32075a8
-F ext/jni/GNUmakefile bcf386da9510e45034d90b2f7b91ab51adcd2db9e080f3900a1e63caf5999659
+F ext/jni/GNUmakefile 3e0e28c1c451eab31dd4fa9d262951ef67ed3ece3270a2efc8ec66ec57068547
 F ext/jni/README.md 1332b1fa27918bd5d9ca2d0d4f3ac3a6ab86b9e3699dc5bfe32904a027f3d2a9
 F ext/jni/jar-dist.make 030aaa4ae71dd86e4ec5e7c1e6cd86f9dfa47c4592c070d2e35157e42498e1fa
-F ext/jni/src/c/sqlite3-jni.c 2da08d92d1cd858353071a2559a260333425e87a79f3da09d85f07f35930a573
+F ext/jni/src/c/sqlite3-jni.c 0a814e8dbc333ff8a1a8a74aebaece435d2982ed6d4d8e8bf9b7082688b20221
 F ext/jni/src/c/sqlite3-jni.h c22f0189254abe26fad3ba132b484785b19a1aa96d34d30d7d8c5ffe6a9b25d1
 F ext/jni/src/org/sqlite/jni/AbstractCollationCallback.java 95e88ba04f4aac51ffec65693e878e234088b2f21b387f4e4285c8b72b33e436
 F ext/jni/src/org/sqlite/jni/AggregateFunction.java 7312486bc65fecdb91753c0a4515799194e031f45edbe16a6373cea18f404dc4
@@ -262,7 +262,7 @@ F ext/jni/src/org/sqlite/jni/ProgressHandlerCallback.java 7b9ff2218129ece98ba60c
 F ext/jni/src/org/sqlite/jni/ResultCode.java ba701f20213a5f259e94cfbfdd36eb7ac7ce7797f2c6c7fca2004ff12ce20f86
 F ext/jni/src/org/sqlite/jni/RollbackHookCallback.java d12352c0e22840de484ffa9b11ed5058bb0daca2e9f218055d3c54c947a273c4
 F ext/jni/src/org/sqlite/jni/SQLFunction.java 544a875d33fd160467d82e2397ac33157b29971d715a821a4fad3c899113ee8c
-F ext/jni/src/org/sqlite/jni/SQLite3Jni.java 35ead9802bf3b16f9afba663ac73f629b3ebdc5cacad151f38403daee9f1e6b0
+F ext/jni/src/org/sqlite/jni/SQLite3Jni.java 98f8d62492e2d6693336dd42c12267ea7f21eefe219aa85b8dd399bd6b0732bd
 F ext/jni/src/org/sqlite/jni/ScalarFunction.java 6d387bb499fbe3bc13c53315335233dbf6a0c711e8fa7c521683219b041c614c
 F ext/jni/src/org/sqlite/jni/TableColumnMetadata.java 54511b4297fa28dcb3f49b24035e34ced10e3fd44fd0e458e784f4d6b0096dab
 F ext/jni/src/org/sqlite/jni/Tester1.java d4ab6f3f83cbb96e763dd4feb6e5527864d9957eb5e79259bfbe57dcf6d0103e
@@ -2116,8 +2116,8 @@ F vsixtest/vsixtest.tcl 6a9a6ab600c25a91a7acc6293828957a386a8a93
 F vsixtest/vsixtest.vcxproj.data 2ed517e100c66dc455b492e1a33350c1b20fbcdc
 F vsixtest/vsixtest.vcxproj.filters 37e51ffedcdb064aad6ff33b6148725226cd608e
 F vsixtest/vsixtest_TemporaryKey.pfx e5b1b036facdb453873e7084e1cae9102ccc67a0
-P dc0fa76b395c5e352116dc33cc1b455e5e9c9f01c285af52ccba4d37e4453b87
-R 8eeecadbd0aad723daa22691fc77aaf3
+P eb24f97253d9c8e7c728c2ac67a0824b10ca67362ac4f8abb94d5d3c54c58c5b
+R b5c8106325c21efbc360de8a5178bfb9
 U stephan
-Z 2c93c72b42f574b692bce8cc766cb46c
+Z a20aea990735784858db150336da744c
 # Remove this line to create a well-formed Fossil manifest.

manifest.uuid

@@ -1 +1 @@
-eb24f97253d9c8e7c728c2ac67a0824b10ca67362ac4f8abb94d5d3c54c58c5b
+aa72d25a22c80a7a376127266b8923f0661147c8bc483baa327230364851a255