Jaccwabyt (JS) doc updates.

FossilOrigin-Name: a329a809b5da135a9c251e4d5f637d45d01d0248110ac05f2ad8f01d9df38c64

ext/wasm/jaccwabyt/jaccwabyt.js

@@ -598,10 +598,13 @@ self.Jaccwabyt = function StructBinderFactory(config){
         new DataView(heap().buffer, this.pointer + descr.offset, descr.sizeof)
       )[f._.getters[sigGlyph]](0, isLittleEndian);
       if(dbg.getter) log("debug.getter:",xPropName,"result =",rc);
-      if(rc && isAutoPtrSig(descr.signature)){
+      /* // Removed: it is legal for multiple StructType instances to
+         // proxy the same pointer, and instanceForPointer() cannot account
+         // for that.
+        if(rc && isAutoPtrSig(descr.signature)){
         rc = StructType.instanceForPointer(rc) || rc;
         if(dbg.getter) log("debug.getter:",xPropName,"resolved =",rc);
-      }                
+      }*/               
       return rc;
     };
     if(descr.readOnly){

ext/wasm/jaccwabyt/jaccwabyt.md

@@ -281,8 +281,8 @@ supported letters are:
   signature entry.
 - **`f`** = `float` (4 bytes)
 - **`d`** = `double` (8 bytes)
-- **`c`** = `int8` (char - see notes below!)
-- **`C`** = `int8` (unsigned char - see notes below!)
+- **`c`** = `int8` (1 byte) char - see notes below!
+- **`C`** = `uint8` (1 byte) unsigned char - see notes below!
 - **`p`** = `int32` (see notes below!)
 - **`P`** = Like `p` but with extra handling. Described below.
 - **`s`** = like `int32` but is a _hint_ that it's a pointer to a
@@ -295,10 +295,10 @@ supported letters are:
 
 Noting that:
 
-- All of these types are numeric. Attempting to set any struct-bound
-  property to a non-numeric value will trigger an exception except in
-  cases explicitly noted otherwise.
-- "Char" types: WASM does not define an `int8` type, nor does it
+- **All of these types are numeric**. Attempting to set any
+  struct-bound property to a non-numeric value will trigger an
+  exception except in cases explicitly noted otherwise.
+- **"Char" types**: WASM does not define an `int8` type, nor does it
   distinguish between signed and unsigned. This API treats `c` as
   `int8` and `C` as `uint8` for purposes of getting and setting values
   when using the `DataView` class. It is _not_ recommended that client
@@ -345,12 +345,15 @@ special use of unsigned numbers). A capital `P` changes the semantics
 of plain member pointers (but not, as of this writing, function
 pointer members) as follows:
 
-- When a `P`-type member is **fetched** via `myStruct.x` and its value is
-  a non-0 integer, [`StructBinder.instanceForPointer()`][StructBinder]
-  is used to try to map that pointer to a struct instance. If a match
-  is found, the "get" operation returns that instance instead of the
-  integer. If no match is found, it behaves exactly as for `p`, returning
-  the integer value.
+- <s>When a `P`-type member is **fetched** via `myStruct.x` and its
+  value is a non-0 integer,
+  [`StructBinder.instanceForPointer()`][StructBinder] is used to try
+  to map that pointer to a struct instance. If a match is found, the
+  "get" operation returns that instance instead of the integer. If no
+  match is found, it behaves exactly as for `p`, returning the integer
+  value.</s> Removed because it's legal and possible to for multiple
+  instances to proxy the same pointer and this infrastructure cannot
+  account for that.
 - When a `P`-type member is **set** via `myStruct.x=y`, if
   [`(y instanceof StructType)`][StructType] then the value of `y.pointer` is
   stored in `myStruct.x`. If `y` is neither a number nor
@@ -403,7 +406,6 @@ instances which have not been manually disposed.
 The following usage pattern offers one way to easily ensure proper
 cleanup of struct instances:
 
-
 >  
 ```javascript
 const my = new MyStruct();
@@ -417,11 +419,6 @@ try {
      from the byte array. */
   // Pass the struct to C code which takes a MyStruct pointer:
   aCFunction( my.pointer );
-  // Type-safely check if a pointer returned from C is a MyStruct:
-  const x = MyStruct.instanceForPointer( anotherCFunction() );
-  // If it is a MyStruct, x now refers to that object. Note, however,
-  // that this only works for instances created in JS, as the
-  // pointer mapping only exists in JS space.
 } finally {
   my.dispose();
 }
@@ -434,6 +431,15 @@ to use `try`/`finally` without a `catch`, and doing so is an ideal
 match for the memory management requirements of Jaccwaby-bound struct
 instances.
 
+It is often useful to wrap an existing instance of a C-side struct
+without taking over ownership of its memory. That can be achieved by
+simply passing a pointer to the constructor. For example:
+
+```js
+const m = new MyStruct( functionReturningASharedPtr() );
+// calling m.dispose() will _not_ free the wrapped C-side instance.
+```
+
 Now that we have struct instances, there are a number of things we
 can do with them, as covered in the rest of this document.
 
@@ -557,7 +563,10 @@ The Struct Binder has the following members:
   any of its "significant" configuration values may have undefined
   results.
 
-- `instanceForPointer(pointer)`  
+- <s>`instanceForPointer(pointer)`</s> (DEPRECATED)  
+  *Do not use this - it will be removed* because it is legal for
+  multiple StructType instances to proxy the same pointer, and
+  instanceForPointer() cannot account for that.\  
   Given a pointer value relative to `config.memory`, if that pointer
   resolves to a struct of _any type_ generated via the same Struct
   Binder, this returns the struct instance associated with it, or
@@ -599,7 +608,7 @@ individual instances via `theInstance.constructor`.):
   [struct's constructor][StructCtors]. If true, the memory is owned by
   someone other than the object and must outlive the object.
 
-- `instanceForPointer(pointer)`  
+- <s>`instanceForPointer(pointer)`</s> (DEPRECATED)  
   Works identically to the [StructBinder][] method of the same name.
 
 - `isA(value)`  
@@ -752,7 +761,7 @@ These constructors have the following "static" members:
   with _all_ instances and clears the `instanceForPointer()`
   mappings. Returns `this`.
 
-- `instanceForPointer(pointer)`  
+- <s>`instanceForPointer(pointer)`</s> (DEPRECATED)  
   Given a pointer value (accessible via the `pointer` property of all
   struct instances) which ostensibly refers to an instance of this
   class, this returns the instance associated with it, or `undefined`

manifest

@@ -1,5 +1,5 @@
-C Expose\ssqlite3_get/set_auxdata()\sto\swasm.\sMinor\stest\sapp\sCSS\stweaks.
-D 2022-12-05T14:13:55.858
+C Jaccwabyt\s(JS)\sdoc\supdates.
+D 2022-12-05T14:32:35.107
 F .fossil-settings/empty-dirs dbb81e8fc0401ac46a1491ab34a7f2c7c0452f2f06b54ebb845d024ca8283ef1
 F .fossil-settings/ignore-glob 35175cdfcf539b2318cb04a9901442804be81cd677d8b889fcc9149c21f239ea
 F LICENSE.md df5091916dbb40e6e9686186587125e1b2ff51f022cc334e886c19a0e9982724
@@ -539,8 +539,8 @@ F ext/wasm/fiddle/fiddle.js 974b995119ac443685d7d94d3b3c58c6a36540e9eb3fed7069d5
 F ext/wasm/fiddle/index.html 5daf54e8f3d7777cbb1ca4f93affe28858dbfff25841cb4ab81d694efed28ec2
 F ext/wasm/index-dist.html c806b6005145b71d64240606e9c6e0bf56878ee8829c66fe7486cebf34b0e6b1
 F ext/wasm/index.html f151b7c7b5cfdc066567d556acd168e769efd4e982286dc5f849a5ee69ecd0ff
-F ext/wasm/jaccwabyt/jaccwabyt.js 292d37ad3b5fcef420db7b449813c38f1656f490f43e214ea4895793158e7fce
-F ext/wasm/jaccwabyt/jaccwabyt.md 50df3ccb7a773634000496a2ccb805dd25cf8cd963696a7deec3209a68c6093b
+F ext/wasm/jaccwabyt/jaccwabyt.js 199f3a0a7513692dac8e843fed210d4e7da12b1e3f168aff6b796e941424e8da
+F ext/wasm/jaccwabyt/jaccwabyt.md c0172c0795522a137a5591ccc63703e5fc0410d7d7677884edfa8d6a9ab093f4
 F ext/wasm/module-symbols.html 980680c8acfa3c8ae6a5aa223512d1b8e78040ced20f8ba2c382129bc73ec028
 F ext/wasm/scratchpad-wasmfs-main.html 20cf6f1a8f368e70d01e8c17200e3eaa90f1c8e1029186d836d14b83845fbe06
 F ext/wasm/scratchpad-wasmfs-main.js 4c140457f4d6da9d646a49addd91edb6e9ad1643c6c48e3258b5bce24725dc18
@@ -2065,8 +2065,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 c3c56d9b944fd0d806d8dad9f0c7be3d7a5441765310908872cc525d82ab6a33
-R 585ea2dfb36f1f8d84b5d643e3dc1f7a
+P 44659ad32a9fe6363badfc5dbb0bd51d6fb2ee1c8aa47b71e9cf3dbd631fde9e
+R b435a2d94f66e49b4a6802642705f112
 U stephan
-Z 583c0236badf6d39ab9de3ab68428681
+Z 58b6d11303c3251b731643b22a0a2877
 # Remove this line to create a well-formed Fossil manifest.

manifest.uuid

@@ -1 +1 @@
-44659ad32a9fe6363badfc5dbb0bd51d6fb2ee1c8aa47b71e9cf3dbd631fde9e
+a329a809b5da135a9c251e4d5f637d45d01d0248110ac05f2ad8f01d9df38c64