破壞性變更：AccessHandle 的同步處理方法

Thomas Steiner

來源私人檔案系統可提供特殊類型的檔案存取權，這些檔案經過高度最佳化，可提升效能，例如提供檔案內容的內建及專屬寫入權限。開發人員可以呼叫 createSyncAccessHandle() 來取得這類檔案的存取權，這是在 FileSystemFileHandle 物件上公開的方法。這項呼叫會產生 FileSystemSyncAccessHandle。

FileSystemSyncAccessHandle 是檔案基元，可提供對本機檔案的有效存取。其中一個主要用途是將 C/C++ 程式碼移植至 Wasm 的應用程式；不過，Wasm 尚未完全支援非同步呼叫，而且使用 Asyncify 程式庫做為替代方案，會大幅降低效能。讓 FileSystemSyncAccessHandle 的所有方法同步，以符合以 Wasm 為基礎的應用程式預期的同步 POSIX 類型檔案 API，讓 API 更符合人體工學，同時大幅提升效能。

新功能

FileSystemSyncAccessHandle 會公開以下方法，這些方法原本為非同步，但自 Chromium 108 起為同步。

  • truncate(newSize)：將與存取句柄相關聯的檔案大小調整為 newSize 位元組長度。如果 newSize 大於目前的檔案大小，則會使用空字節填充檔案；否則會截斷檔案。
  • getSize()：傳回與存取句柄相關聯的檔案大小，以位元組為單位。
  • flush()：確保與存取帳號相關聯的檔案內容包含透過 write() 完成的所有修改。
  • close()：會先刷新存取句柄，然後關閉該句柄。關閉存取句柄會停用對其進行的任何後續作業，並釋放與存取句柄相關聯的項目鎖定。
// In a `Worker`:
const root = await navigator.storage.getDirectory();
const fileHandle = await root.getFileHandle('test', { create: true });
// `createSyncAccessHandle()` is still async.
const accessHandle = await fileHandle.createSyncAccessHandle();
// Both `read()` and `write()` were sync before.
accessHandle.read(/* ... */);
accessHandle.write(/* ... */);

// New: synchronous as of Chromium 108.
console.log(accessHandle.getSize());
accessHandle.truncate(123);
accessHandle.flush();
accessHandle.close();

我需要做些什麼？

請注意，將方法從非同步變更為同步是網路公開的變更，可能會導致中斷。雖然在同步方法中使用 await 不會造成任何影響，但任何 Promise.then() 用途都會中斷。如果您在先前非同步 (現在為同步) 方法的結果上連結 then() 呼叫，就需要變更程式碼。

// (✅) This won't break, but you better remove the superfluous `await`:
await accessHandle.flush();
// ✅ Correct:
accessHandle.flush();

// ⛔️ This will break, and you need to restructure your code:
accessHandle.flush().then(/* Follow-up code */);
// ✅ Correct:
accessHandle.flush();
/* Follow-up code */