currently-opened client-specified filenames. */
getFileNames(){
const rc = [];
- const iter = this.#mapFilenameToSAH.keys();
- for(const n of iter) rc.push(n);
+ for(const n of this.#mapFilenameToSAH.keys()) rc.push(n);
return rc;
}
-// #createFileObject(sah,clientName,opaqueName){
-// const f = Object.assign(Object.create(null),{
-// clientName, opaqueName
-// });
-// this.#mapSAHToMeta.set(sah, f);
-// return f;
-// }
-// #unmapFileObject(sah){
-// this.#mapSAHToMeta.delete(sah);
-// }
-
/**
Adds n files to the pool's capacity. This change is
persistent across settings. Returns a Promise which resolves
}
/**
- Releases all currently-opened SAHs. The only legal
- operation after this is acquireAccessHandles().
+ Releases all currently-opened SAHs. The only legal operation
+ after this is acquireAccessHandles() or (if this is called from
+ pauseVfs()) either of isPaused() or unpauseVfs().
*/
releaseAccessHandles(){
for(const ah of this.#mapSAHToName.keys()) ah.close();
}
/**
- Opens all files under this.vfsDir/this.#dhOpaque and acquires
- a SAH for each. returns a Promise which resolves to no value
- but completes once all SAHs are acquired. If acquiring an SAH
- throws, SAHPool.$error will contain the corresponding
- exception.
+ Opens all files under this.vfsDir/this.#dhOpaque and acquires a
+ SAH for each. Returns a Promise which resolves to no value but
+ completes once all SAHs are acquired. If acquiring an SAH
+ throws, this.$error will contain the corresponding Error
+ object.
+
+ If it throws, it releases any SAHs which it may have
+ acquired before the exception was thrown, leaving the VFS in a
+ well-defined but unusable state.
If clearFiles is true, the client-stored state of each file is
cleared when its handle is acquired, including its name, flags,
and any data stored after the metadata block.
*/
- async acquireAccessHandles(clearFiles){
+ async acquireAccessHandles(clearFiles=false){
const files = [];
for await (const [name,h] of this.#dhOpaque){
if('file'===h.kind){
);
this.#dhVfsRoot = this.#dhVfsParent = undefined;
}catch(e){
- sqlite3.config.error(this.vfsName,"removeVfs() failed:",e);
+ sqlite3.config.error(this.vfsName,"removeVfs() failed with no recovery strategy:",e);
/*otherwise ignored - there is no recovery strategy*/
}
return true;
intact. If this object is already paused, this is a
no-op. Returns this object.
- This function throws if any database handles are active, as the
- alternative would be to invoke Undefined Behavior by closing
- that file handle out from under the database. Similarly,
- automatically closing any database handles opened by this VFS
- would invoke Undefined Behavior in downstream code which is
- holding those pointers.
+ This function throws if SQLite has any opened file handles
+ hosted by this VFS, as the alternative would be to invoke
+ Undefined Behavior by closing file handles out from under any
+ the library. Similarly, automatically closing any database
+ handles opened by this VFS would invoke Undefined Behavior in
+ downstream code which is holding those pointers.
+
+ If this function throws due to open file handles then it has
+ no side effects. If the OPFS API throws while closing handles
+ then the VFS is left in an undefined state.
@see isPaused()
@see unpauseVfs()
*/
pauseVfs(){
if(this.#mapS3FileToOFile_.size>0){
- toss("Cannot pause a VFS which has an opened database.")
+ sqlite3.SQLite3Error.toss(
+ capi.SQLITE_MISUSE, "Cannot pause VFS",
+ this.vfsName,"because it has opened files."
+ );
}
if(this.#mapSAHToName.size>0){
capi.sqlite3_vfs_unregister(this.vfsName);
re-registering it with SQLite. This is a no-op if the VFS is
not currently paused.
- The returned Promise resolves to this object.
+ The returned Promise resolves to this object. See
+ acquireAccessHandles() for how it behaves if it throws due to
+ SAH acquisition failure.
@see isPaused()
@see pauseVfs()
Clears all client-defined state of all SAHs and makes all of them
available for re-use by the pool. Results are undefined if any such
handles are currently in use, e.g. by an sqlite3 db.
+
+ APIs specific to the "pause" capability (added in version 3.49):
+
+ Summary: "pausing" the VFS disassociates it from SQLite and
+ relinquishes its SAHs so that they may be opened by another
+ instance of this VFS (running in a separate tab/page or Worker).
+ "Unpausing" it takes back control, if able.
+
+ - pauseVfs()
+
+ "Pauses" this VFS by unregistering it from SQLite and
+ relinquishing all open SAHs, leaving the associated files intact.
+ This enables pages/tabs to coordinate semi-concurrent usage of
+ this VFS. If this object is already paused, this is a
+ no-op. Returns this object. Throws if SQLite has any opened file
+ handles hosted by this VFS. If this function throws due to open
+ file handles then it has no side effects. If the OPFS API throws
+ while closing handles then the VFS is left in an undefined state.
+
+ - isPaused()
+
+ Returns true if this VFS is paused, else false.
+
+ - [async] unpauseVfs()
+
+ Restores the VFS to an active state after having called
+ pauseVfs() on it. This is a no-op if the VFS is not paused. The
+ returned Promise resolves to this object on success. A rejected
+ Promise means there was a problem reacquiring the SAH handles
+ (possibly because they're in use by another instance or have
+ since been removed). Generically speaking, there is recovery
+ strategy for that type of error, but if the problem is simply
+ that the OPFS files are locked, then a later attempt to unpause
+ it, made after the concurrent instance releases the SAHs, may
+ recover from the situation.
*/
sqlite3.installOpfsSAHPoolVfs = async function(options=Object.create(null)){
options = Object.assign(Object.create(null), optionDefaults, (options||{}));
-C Merge\strunk\sinto\sopfs-sahpool-pause\sbranch.
-D 2025-01-31T12:39:07.019
+C Cleanups\sin\sthe\sopfs-sahpool\sVFS\spause/unpause\sfeature\sand\sits\stests.
+D 2025-01-31T14:25:38.298
F .fossil-settings/empty-dirs dbb81e8fc0401ac46a1491ab34a7f2c7c0452f2f06b54ebb845d024ca8283ef1
F .fossil-settings/ignore-glob 35175cdfcf539b2318cb04a9901442804be81cd677d8b889fcc9149c21f239ea
F LICENSE.md e108e1e69ae8e8a59e93c455654b8ac9356a11720d3345df2a4743e9590fb20d
F ext/wasm/api/sqlite3-license-version-header.js 0c807a421f0187e778dc1078f10d2994b915123c1223fe752b60afdcd1263f89
F ext/wasm/api/sqlite3-opfs-async-proxy.js 3774befd97cd1a5e2895c8225a894aad946848c6d9b4028acc988b5d123475af
F ext/wasm/api/sqlite3-vfs-helper.c-pp.js 3f828cc66758acb40e9c5b4dcfd87fd478a14c8fb7f0630264e6c7fa0e57515d
-F ext/wasm/api/sqlite3-vfs-opfs-sahpool.c-pp.js c8d6f02d834224290009d25876d2ec011cb9b8dc425e3a0761b7e55d9a67c24f
+F ext/wasm/api/sqlite3-vfs-opfs-sahpool.c-pp.js 4878cf2a19577093ea82b505f0b052147ca11d27575106c1bb30d2f58efc80a4
F ext/wasm/api/sqlite3-vfs-opfs.c-pp.js 9b86ca2d8276cf919fbc9ba2a10e9786033b64f92c2db844d951804dee6c4b4e
F ext/wasm/api/sqlite3-vtab-helper.c-pp.js e809739d71e8b35dfe1b55d24d91f02d04239e6aef7ca1ea92a15a29e704f616
F ext/wasm/api/sqlite3-wasm.c 83f5e9f998e9fa4261eb84e9f092210e3ffe03895119f5ded0429eb34ab9d2be
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 7f239383c06078fe67919509f7e1691d3b970a5f6cd4dc4adab71bc8e6cf6fe8
+F ext/wasm/tester1.c-pp.js 0cda9a3180e743f4a42500cbcde1a14da920b34697eb4b05adedac0dab5381de
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 49a486c5069de041aedcbde4de178293e0463ae9918ecad7539eedf0ec77a139
F tool/win/sqlite.vsix deb315d026cc8400325c5863eef847784a219a2f
-P d651b8da5a84cd54d71f15bd34e4db685674ef73f26f5cc26b7af5321a2ec05e 56b618da9073db8b8d5dafa177a3c9e4c4d927bf512e14b0e6d23937f91ce4cf
-R 0de3f6553f08e8afe4528e7b192214df
+P 775a547eca2b0b3dbb6c03990236128a095cc34d28caec44b9a5072510c75b63
+R af1dcaea4b1a4f1eb6d1dba2bd937843
U stephan
-Z 411d369a110121e7891ed7e96e9dfba9
+Z 577676d1355d687b76945b6366664411
# Remove this line to create a well-formed Fossil manifest.
projects / thirdparty / sqlite.git / commitdiff
