wasm32-wasi-vfs.c

Overview

This file implements a minimal and simplified Virtual File System (VFS) interface designed for use with SQLite on Unix-like operating systems. The implementation is tailored to embedded environments where complex VFS features such as file locking, dynamic extensions, temporary files, and file truncation are either unnecessary or unsupported.

A key feature of this VFS is the buffering of writes to journal files to optimize write performance on devices that do not cache writes efficiently in the OS. Instead of performing many small writes, the VFS coalesces writes into aligned blocks before flushing them to disk.

The file exposes a custom sqlite3_vfs named "demo" that can be registered with SQLite using the function sqlite3_demovfs().

Data Structures

DemoFile

Constants and Macros

Functions and Methods

demoDirectWrite(DemoFile *p, const void *zBuf, int iAmt, sqlite_int64 iOfst)

demoFlushBuffer(DemoFile *p)

demoClose(sqlite3_file *pFile)

demoRead(sqlite3_file *pFile, void *zBuf, int iAmt, sqlite_int64 iOfst)

demoWrite(sqlite3_file *pFile, const void *zBuf, int iAmt, sqlite_int64 iOfst)

demoTruncate(sqlite3_file *pFile, sqlite_int64 size)

demoSync(sqlite3_file *pFile, int flags)

demoFileSize(sqlite3_file *pFile, sqlite_int64 *pSize)

Locking Functions (demoLock, demoUnlock, demoCheckReservedLock)

demoFileControl(sqlite3_file *pFile, int op, void *pArg)

demoSectorSize(sqlite3_file *pFile) and demoDeviceCharacteristics(sqlite3_file *pFile)

demoOpen(sqlite3_vfs *pVfs, const char *zName, sqlite3_file *pFile, int flags, int *pOutFlags)

demoDelete(sqlite3_vfs *pVfs, const char *zPath, int dirSync)

demoAccess(sqlite3_vfs *pVfs, const char *zPath, int flags, int *pResOut)

demoFullPathname(sqlite3_vfs *pVfs, const char *zPath, int nPathOut, char *zPathOut)

Dynamic Loading Functions (demoDlOpen, demoDlError, demoDlSym, demoDlClose)

demoRandomness(sqlite3_vfs *pVfs, int nByte, char *zByte)

demoSleep(sqlite3_vfs *pVfs, int nMicro)

demoCurrentTime(sqlite3_vfs *pVfs, double *pTime)

sqlite3_demovfs(void)

Test and Initialization Functions (Conditional on SQLITE_TEST)

Implementation Details and Algorithms

Interaction with Other System Components

Visual Diagram: Function Flow and File Operation Relationships

flowchart TD
A[sqlite3_demovfs] -->|Register VFS| B[demoOpen]
B --> C[Allocate buffer if journal]
B --> D["open() system call"]
B --> E[Assign method pointers]
E --> F[demoRead]
E --> G[demoWrite]
E --> H[demoClose]
E --> I[demoSync]
E --> J[demoFileSize]
E --> K[demoDelete]
E --> L[demoAccess]
E --> M[demoFullPathname]
G --> N{Has buffer?}
N -->|Yes| O[Buffer writes]
N -->|No| P["Direct write (demoDirectWrite)"]
O --> Q{Buffer full or non-sequential?}
Q -->|Yes| R["Flush buffer (demoFlushBuffer)"]
Q -->|No| S[Copy data to buffer]
H --> T[Flush buffer]
H --> U[free buffer]
H --> V[close file descriptor]
K --> W["unlink()"]
W --> X{dirSync?}
X -->|Yes| Y[fsync directory]
X -->|No| Z[Return]
subgraph File Operations
F
G
H
I
J
K
L
M
end

Usage Examples

Registering the VFS with SQLite

sqlite3_vfs *pVfs = sqlite3_demovfs();
sqlite3_vfs_register(pVfs, 0);

After registration, SQLite can open and use files through this VFS by specifying "demo" as the VFS name.

Opening a Journal File with Buffered Writes

sqlite3_file file;
int flags = SQLITE_OPEN_MAIN_JOURNAL | SQLITE_OPEN_READWRITE | SQLITE_OPEN_CREATE;
int rc = demoOpen(pVfs, "journalfile", &file, flags, NULL);
if (rc == SQLITE_OK) {
    // Writes to this file will be buffered for performance
}

Writing Data with the Buffering Logic

When SQLite writes to the journal, the VFS buffers the data in memory and flushes it only when the buffer is full or on sync, improving efficiency on embedded systems without OS write caching.

References to Related Topics