*/
const __ptrMap = new WeakMap();
/**
- A Set of oo1.DB objects which are proxies for (A) (sqlite3*) or
- another oo1.DB object or (B) oo1.Stmt objects which are proxies
- for (sqlite3_stmt*) pointers. Such objects do not own their
- underlying handle and that handle must be guaranteed (by the
- client) to outlive the proxy. These proxies are primarily
- intended as a way to briefly wrap an (sqlite3[_stmt]*) object as
- an oo1.DB/Stmt without taking over ownership.
+ A Set of oo1.DB or oo1.Stmt objects which are proxies for
+ (sqlite3*) resp. (sqlite3_stmt*) pointers. Such objects
+ optionally do not own their underlying handle and that handle
+ must be guaranteed (by the client) to outlive the proxy. These
+ proxies are primarily intended as a way to briefly wrap an
+ (sqlite3[_stmt]*) object as an oo1.DB/Stmt without taking over
+ ownership.
+
+ See DB.wrapHandle() and Stmt.wrapHandle().
*/
const __doesNotOwnHandle = new Set();
/**
}/*DB.prototype*/;
/**
- Returns a new oo1.DB instance which wraps the given db.
+ Returns a new oo1.DB instance which wraps the given (sqlite3*)
+ WASM pointer, optionally with or without taking over ownership of
+ that pointer.
The first argument must be either a non-NULL (sqlite3*) WASM
- pointer or a non-close()d instance of oo1.DB.
-
- The second argument, defaulting to false, only applies if the
- first argument is a (sqlite3*). If it is, the returned object
- will pass that pointer to sqlite3_close() when its close() method
- is called, otherwise it will not.
+ pointer.
- If the first argument is a oo1.DB object, the second argument is
- disregarded and the returned object will be created as a
- sqlite3.oo1.DB object (as opposed to the concrete derived DB
- subclass from the first argument), so will not include any
- derived-type behaviors,
- e.g. JsStorageDb.prototype.clearStorage().
+ The second argument, defaulting to false, specifies ownership of
+ the first argument. If it is truthy, the returned object will
+ pass that pointer to sqlite3_close() when its close() method is
+ called, otherwise it will not.
Throws if db cannot be resolved to one of the legal options.
DB instance, including the requirement of calling close() on
it. close() will free up internal resources owned by the proxy,
and disassociate the proxy from that handle, but will not
- actually close the proxied db handle.
+ actually close the proxied db handle unless this function is
+ passed a thruthy second argument.
The following quirks and requirements apply when proxying another
DB instance, as opposed to a (sqlite3*):
- - DO NOT call close() on the being-proxied instance while a proxy
- is active.
-
- - ALWAYS eventually call close() on the returned object BEFORE
- the being-proxied handle is closed.
-
- - For historical reasons, the filename property of the returned
- object is captured at the time of this call, as opposed to being
- dynamically proxied. e.g., if the filename property of the
- being-proxied object is changed, this object will not reflect
- that change. There is no good reason to ever modify that
- property, so this distinction is not truly significant but it's
- noted here because it's a client-visible discrepancy between the
- proxy and its partner. (Sidebar: the filename property _should_
- be a property access interceptor for sqlite3_db_filename(),
- but making it so now may break existing code.)
+ - DO NOT call sqlite3_close() (or similar) on the being-proxied
+ instance while a proxy is active.
+
+ - ALWAYS eventually call close() on the returned object. If the
+ proxy does not own the underlying handle then its MUST be
+ closed BEFORE the being-proxied handle is closed.
+
+ Design notes:
+
+ - wrapHandle() "could" accept a DB object instance as its first
+ argument and proxy thatDb.pointer but there is currently no use
+ case where doing so would be useful, so it does not allow
+ that. That restriction may be lifted in a future version.
*/
- DB.wrapHandle = function(db, takeOwnership=false){
- let ptr, ctor = DB;
- const oo1db = (db instanceof DB) ? db : undefined;
- if( wasm.isPtr(db) ){
- ptr = db;
- }else if( oo1db ){
- takeOwnership = false;
- ptr = db.pointer;
- //ctor = db.constructor;
- // ^^^ that doesn't work, resulting in an Object-type value
- }
- //sqlite3.config.debug("wrapHandle()",'db',db,'ctor',ctor,
- //'arguments',arguments,'db.constructor',db.constructor);
- if( !ptr ){
- throw new sqlite3.SQLite3Error(sqlite3.SQLITE_MISUSE,
- "Argument must be a WASM sqlite3 "+
- "pointer or an sqlite3.oo1.DB instance");
+ DB.wrapHandle = function(pDb, takeOwnership=false){
+ if( !pDb || !wasm.isPtr(pDb) ){
+ throw new sqlite3.SQLite3Error(capi.SQLITE_MISUSE,
+ "Argument must be a WASM sqlite3 pointer");
}
- const dc = new ctor({
- "sqlite3*": ptr,
+ return new DB({
+ /* This ctor call style is very specifically internal-use-only.
+ It is not documented and may change at any time. */
+ "sqlite3*": pDb,
"sqlite3*:takeOwnership": !!takeOwnership
});
- if( oo1db ){
- dc.filename = oo1db.filename;
- }//else dc.filename was captured by the ctor for legacy consistency
- //sqlite3.config.debug("wrapHandle() dc",dc);
- return dc;
- }/*DB.wrapHandle()*/;
+ };
/** Throws if the given Stmt has been finalized, else stmt is
returned. */
/**
The Stmt counterpart of oo1.DB.wrapHandle(), this creates a Stmt
- instance which wraps a WASM (sqlite3_stmt*) in the oo1 API with
- or without taking over ownership of that pointer.
+ instance which wraps a WASM (sqlite3_stmt*) in the oo1 API,
+ optionally with or without taking over ownership of that pointer.
The first argument must be an oo1.DB instance[^1].
returned Stmt object takes over ownership of the underlying
(sqlite3_stmt*). If true, the returned object's finalize() method
will finalize that handle, else it will not. If it is false,
- ownership of stmtPtr is unchanged and stmtPtr MUST outlive the
+ ownership of pStmt is unchanged and pStmt MUST outlive the
returned object or results are undefined.
This function throws if the arguments are invalid. On success it
determined whether it would be of general benefit to refactor the
DB/Stmt pair internals to communicate in terms of the underlying
(sqlite3*) rather than a DB object. If so, we could laxen the
- first argument's requirement and allow an (sqlite3*).
+ first argument's requirement and allow an (sqlite3*). Because
+ DB.wrapHandle() enables multiple DB objects to proxy the same
+ (sqlite3*), we cannot unambiguously translate the first arugment
+ from (sqlite3*) to DB instances for us with this function's first
+ argument.
*/
- Stmt.wrapHandle = function(oo1db, stmtPtr, takeOwnership=false){
+ Stmt.wrapHandle = function(oo1db, pStmt, takeOwnership=false){
let ctor = Stmt;
if( !(oo1db instanceof DB) || !oo1db.pointer ){
throw new sqlite3.SQLite3Error(sqlite3.SQLITE_MISUSE,
"First argument must be an opened "+
"sqlite3.oo1.DB instance");
}
- if( !stmtPtr || !wasm.isPtr(stmtPtr) ){
+ if( !pStmt || !wasm.isPtr(pStmt) ){
throw new sqlite3.SQLite3Error(sqlite3.SQLITE_MISUSE,
"Second argument must be a WASM "+
"sqlite3_stmt pointer");
}
- return new Stmt(oo1db, stmtPtr, BindTypes, !!takeOwnership);
+ return new Stmt(oo1db, pStmt, BindTypes, !!takeOwnership);
}
/** The OO API's public namespace. */
-C wasm:\sadd\sa\sfew\stests\sdemonstrating\sthat\soo1.Stmt.paramaterCount's\snew\simpl\sdoes\snot\schange\svisible\sbehaviors.\sAdd\sthe\sc-pp-filtered\sfiles\sto\s'make\sclean'.
-D 2025-07-09T13:13:01.736
+C wasm:\sDB.wrapHandle()\sno\slonger\saccepts\sa\sDB\sobject\sas\sits\sfirst\sargument,\sas\sthere's\sno\sapparent\suse\scase\sfor\sproxying\sone\sDB\sobject\swith\sanother.\sDoc\simprovements\sfor\sthe\snew\scode.
+D 2025-07-09T13:43:53.471
F .fossil-settings/binary-glob 61195414528fb3ea9693577e1980230d78a1f8b0a54c78cf1b9b24d0a409ed6a x
F .fossil-settings/empty-dirs dbb81e8fc0401ac46a1491ab34a7f2c7c0452f2f06b54ebb845d024ca8283ef1
F .fossil-settings/ignore-glob 35175cdfcf539b2318cb04a9901442804be81cd677d8b889fcc9149c21f239ea
F ext/wasm/api/pre-js.c-pp.js a614a2c82b12c4d96d8e3ba77330329efc53c4d56a8a7e60ade900f341866cfb
F ext/wasm/api/sqlite3-api-cleanup.js 3ac1786e461ada63033143be8c3b00b26b939540661f3e839515bb92f2e35359
F ext/wasm/api/sqlite3-api-glue.c-pp.js 0b76510f3650053bac67ca8947cb6ab9d050ad2218118a2e7796dd37be832ffa
-F ext/wasm/api/sqlite3-api-oo1.c-pp.js 33203352e067d3dbb569c5ec3c247b356f61a8d320bf8551fdf18ff25c0ff862
+F ext/wasm/api/sqlite3-api-oo1.c-pp.js 972e0aa2f6f3ad9d9530edfc5c18a56e55ab5bec728ce6ca9b89ce1df463f740
F ext/wasm/api/sqlite3-api-prologue.js 8708570165f5b4bce9a78ccd91bc9ddf8735970ac1c4d659e36c9a7d9a644bb4
F ext/wasm/api/sqlite3-api-worker1.c-pp.js f646a65257973b8c4481f8a6a216370b85644f23e64b126e7ae113570587c0ab
F ext/wasm/api/sqlite3-license-version-header.js 0c807a421f0187e778dc1078f10d2994b915123c1223fe752b60afdcd1263f89
F ext/wasm/test-opfs-vfs.js 1618670e466f424aa289859fe0ec8ded223e42e9e69b5c851f809baaaca1a00c
F ext/wasm/tester1-worker.html ebc4b820a128963afce328ecf63ab200bd923309eb939f4110510ab449e9814c
F ext/wasm/tester1.c-pp.html 1c1bc78b858af2019e663b1a31e76657b73dc24bede28ca92fbe917c3a972af2
-F ext/wasm/tester1.c-pp.js 1c4fdb32e10c92e2595939b1b6f6588cd3a30a2691ba2dc4a42893db99e0648b
+F ext/wasm/tester1.c-pp.js 830749ee21bde538f52e150878c0078a3f6d294ba183900efd8488a9e6debf4f
F ext/wasm/tests/opfs/concurrency/index.html 657578a6e9ce1e9b8be951549ed93a6a471f4520a99e5b545928668f4285fb5e
F ext/wasm/tests/opfs/concurrency/test.js d08889a5bb6e61937d0b8cbb78c9efbefbf65ad09f510589c779b7cc6a803a88
F ext/wasm/tests/opfs/concurrency/worker.js 0a8c1a3e6ebb38aabbee24f122693f1fb29d599948915c76906681bb7da1d3d2
F tool/warnings-clang.sh bbf6a1e685e534c92ec2bfba5b1745f34fb6f0bc2a362850723a9ee87c1b31a7
F tool/warnings.sh 1ad0169b022b280bcaaf94a7fa231591be96b514230ab5c98fbf15cd7df842dd
F tool/win/sqlite.vsix deb315d026cc8400325c5863eef847784a219a2f
-P 6e73770a7f3845055e0130012d844c32c4a1bfdb87e8379c161e1a266a808143
-R 275bf35e86e01e823d3a78eac9fe64ed
+P 3fe61545967f82190011edb90b1be6a448b590555c7ba5f8e96494aeea8f88ce
+R 7d3270f820abddff176885a6dceb6626
U stephan
-Z 5ade71be55c22a5952ee210feb5c3747
+Z 4ed976109c5d88084cce8c9c03b32258
# Remove this line to create a well-formed Fossil manifest.
projects / thirdparty / sqlite.git / commitdiff
