diff --git a/ext/wasm/jaccwabyt/jaccwabyt.js b/ext/wasm/jaccwabyt/jaccwabyt.js
index 7c8d42b331..960aae7936 100644
--- a/ext/wasm/jaccwabyt/jaccwabyt.js
+++ b/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){
diff --git a/ext/wasm/jaccwabyt/jaccwabyt.md b/ext/wasm/jaccwabyt/jaccwabyt.md
index 73f6bfa947..855a1d16a0 100644
--- a/ext/wasm/jaccwabyt/jaccwabyt.md
+++ b/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.
+- 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. 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)`
+- `instanceForPointer(pointer)` (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)`
+- `instanceForPointer(pointer)` (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)`
+- `instanceForPointer(pointer)` (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`
diff --git a/manifest b/manifest
index 8345aa2237..0a6cf576d7 100644
--- a/manifest
+++ b/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.
diff --git a/manifest.uuid b/manifest.uuid
index 3aea11316b..a3e46a1ef5 100644
--- a/manifest.uuid
+++ b/manifest.uuid
@@ -1 +1 @@
-44659ad32a9fe6363badfc5dbb0bd51d6fb2ee1c8aa47b71e9cf3dbd631fde9e
\ No newline at end of file
+a329a809b5da135a9c251e4d5f637d45d01d0248110ac05f2ad8f01d9df38c64
\ No newline at end of file