Internal JNI doc tweaks.

FossilOrigin-Name: f4aa2c82882cb6be1fd52977de19fd03c2e38abb857b520f951b32d610972ab6

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

@@ -367,8 +367,8 @@ struct BusyHandlerJni{
 */
 typedef struct PerDbStateJni PerDbStateJni;
 struct PerDbStateJni {
-  JNIEnv *env;
-  sqlite3 * pDb;
+  JNIEnv *env   /* The associated JNIEnv handle */;
+  sqlite3 *pDb /* The associated db handle */;
   jobject jDb /* a global ref of the object which was passed to
                  sqlite3_open(_v2)(). We need this in order to have an
                  object to pass to sqlite3_collation_needed()'s
@@ -377,8 +377,8 @@ struct PerDbStateJni {
                  would be a different instance (and maybe even a
                  different class) than the one the user expects to
                  receive. */;
-  PerDbStateJni * pNext;
-  PerDbStateJni * pPrev;
+  PerDbStateJni * pNext /* Next entry in the available/free list */;
+  PerDbStateJni * pPrev /* Previous entry in the available/free list */;
   JniHookState trace;
   JniHookState progress;
   JniHookState commitHook;
@@ -941,10 +941,13 @@ static int CollationState_xCompare(void *pArg, int nLhs, const void *lhs,
                                    int nRhs, const void *rhs){
   CollationState * const cs = pArg;
   JNIEnv * env = cs->env;
-  jint rc;
+  jint rc = 0;
   jbyteArray jbaLhs = (*env)->NewByteArray(env, (jint)nLhs);
-  jbyteArray jbaRhs = (*env)->NewByteArray(env, (jint)nRhs);
+  jbyteArray jbaRhs = jbaLhs ? (*env)->NewByteArray(env, (jint)nRhs) : NULL;
   //MARKER(("native xCompare nLhs=%d nRhs=%d\n", nLhs, nRhs));
+  if(!jbaRhs){
+    (*env)->FatalError(env, "Out of memory. Cannot allocate arrays for collation.");
+  }
   (*env)->SetByteArrayRegion(env, jbaLhs, 0, (jint)nLhs, (const jbyte*)lhs);
   (*env)->SetByteArrayRegion(env, jbaRhs, 0, (jint)nRhs, (const jbyte*)rhs);
   rc = (*env)->CallIntMethod(env, cs->oCollation, cs->midCompare,
@@ -965,12 +968,21 @@ static void CollationState_xDestroy(void *pArg){
 /* State for sqlite3_result_java_object() and
    sqlite3_value_java_object(). */
 typedef struct {
-  /* POTENTIAL bug: the JNI docs say that the JNIEnv pointer
-     is guaranteed to resolve the same for the same contexts,
-     but the docs are unclear as to whether it's the (JNIEnv *env)
-     or (*env) which resolves consistently.
+  /* The JNI docs say:
 
-     This posts claims it's unsave to cache JNIEnv at all, even when
+     https://docs.oracle.com/javase/8/docs/technotes/guides/jni/spec/design.html
+
+     > The VM is guaranteed to pass the same interface pointer to a
+       native method when it makes multiple calls to the native method
+       from the same Java thread.
+
+     Per the accompanying diagram, the "interface pointer" is the
+     pointer-to-pointer which is passed to all JNI calls
+     (`JNIEnv *env`), implying that we need to be caching that. The
+     verbiage "interface pointer" implies, however, that we should be
+     storing the dereferenced `(*env)` pointer.
+
+     This posts claims it's unsafe to cache JNIEnv at all, even when
      it's always used in the same thread:
 
      https://stackoverflow.com/questions/12420463

manifest

@@ -1,5 +1,5 @@
-C Consolidate\striplicated\sxDestroy()-calling\scode.\sRemove\ssome\sunnecessary\scasts.
-D 2023-07-31T07:15:25.615
+C Internal\sJNI\sdoc\stweaks.
+D 2023-07-31T09:28:15.075
 F .fossil-settings/empty-dirs dbb81e8fc0401ac46a1491ab34a7f2c7c0452f2f06b54ebb845d024ca8283ef1
 F .fossil-settings/ignore-glob 35175cdfcf539b2318cb04a9901442804be81cd677d8b889fcc9149c21f239ea
 F LICENSE.md df5091916dbb40e6e9686186587125e1b2ff51f022cc334e886c19a0e9982724
@@ -232,7 +232,7 @@ F ext/icu/icu.c c074519b46baa484bb5396c7e01e051034da8884bad1a1cb7f09bbe6be3f0282
 F ext/icu/sqliteicu.h fa373836ed5a1ee7478bdf8a1650689294e41d0c89c1daab26e9ae78a32075a8
 F ext/jni/GNUmakefile 56a014dbff9516774d895ec1ae9df0ed442765b556f79a0fc0b5bc438217200d
 F ext/jni/README.md c0e6e80935e7761acead89b69c87765b23a6bcb2858c321c3d05681fd338292a
-F ext/jni/src/c/sqlite3-jni.c 2d61ba074e851ad010307fd901581030a3f234771c266306ff9ccf33ae1a5542
+F ext/jni/src/c/sqlite3-jni.c d92a945e490d05878da10449fcb8a1d50f04357557d409a85d53bbe27cb5c532
 F ext/jni/src/c/sqlite3-jni.h 28def286ee305c1c89a43ac5918a6862d985d0534f7ccbbd74df4885d3918b73
 F ext/jni/src/org/sqlite/jni/BusyHandler.java 1b1d3e5c86cd796a0580c81b6af6550ad943baa25e47ada0dcca3aff3ebe978c
 F ext/jni/src/org/sqlite/jni/Collation.java 8dffbb00938007ad0967b2ab424d3c908413af1bbd3d212b9c9899910f1218d1
@@ -2071,8 +2071,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 fcfc070673cef2f657f4737f096678439ed7c011fb2e5391e0721f82f5d8af51
-R cfdb6b4bc4a7852f0b4b2fc4d64b3f33
+P 24c0763d0e025187c74002ffee11fd48d3cd7b40e01469d28484bb67f701884b
+R 7bd2b6ba1e43d037c3e290268c0148cb
 U stephan
-Z 7456fbe378da7eba9d869800225a0ec8
+Z 1e5d7f469bee5667fa6677ac776d2be7
 # Remove this line to create a well-formed Fossil manifest.

manifest.uuid

@@ -1 +1 @@
-24c0763d0e025187c74002ffee11fd48d3cd7b40e01469d28484bb67f701884b
+f4aa2c82882cb6be1fd52977de19fd03c2e38abb857b520f951b32d610972ab6