Documentation
¶
Overview ¶
Package vfs is the operating system layer of SQLite, in Go: the files, locks and shared memory that os_unix.c gives a normal build. SQLite is built with SQLITE_OS_OTHER, and a small C shim turns its sqlite3_vfs and sqlite3_io_methods calls into calls of this package.
It behaves like os_unix.c, and keeps locks the same way: the Files of one database in the process share a node (see inode and shmNode) that counts in memory which File holds what, refuses conflicts between them without asking the kernel, and holds the process's locks on one descriptor. The kernel is asked only when the process's lock changes.
The difference is the kind of kernel lock. os_unix uses POSIX record locks, which belong to the process, and closing any descriptor of a file drops all of them, so os_unix keeps the descriptors of closed connections open until the last lock goes. This package uses locks on open file descriptions (OFD locks), which belong to the node's own descriptor: closing a File's descriptor drops nothing, so it is closed at once. The byte ranges are those of os_unix, so the locks also work against SQLite built from C, as long as that SQLite runs in another process.
One more difference: while no other process has the -shm open, the last reader of the process to leave one of the WAL read slots leaves the lock on the slot for about a millisecond, so that the next reader needs no system call. When another process opens the -shm, this process finds out within about that millisecond and from then on releases read slots at once, as os_unix, so that the other process's checkpoints are not held off (see shmReadSlots).
Results are SQLite result codes, with the values of sqlite3.h.
One File is used by one goroutine at a time. Different Files, also of the same path, may be used at the same time.
Index ¶
- Constants
- func Access(name string, flags int) (bool, int)
- func Delete(name string, syncDir bool) int
- func FullPathname(name string) (string, int)
- func ShmBarrier()
- type File
- func (f *File) CheckReservedLock() (bool, int)
- func (f *File) Close() int
- func (f *File) DeviceCharacteristics() int
- func (f *File) HasMoved() bool
- func (f *File) Lock(level int) int
- func (f *File) LockState() int
- func (f *File) ReadAt(p []byte, off int64) int
- func (f *File) SectorSize() int
- func (f *File) SetChunkSize(n int)
- func (f *File) ShmLock(offset, n, flags int) int
- func (f *File) ShmMap(n, size int, extend bool) (uintptr, int)
- func (f *File) ShmUnmap(remove bool) int
- func (f *File) Size() (int64, int)
- func (f *File) SizeHint(size int64) int
- func (f *File) Sync(flags int) int
- func (f *File) Truncate(size int64) int
- func (f *File) Unlock(level int) int
- func (f *File) WriteAt(p []byte, off int64) int
Constants ¶
const ( OK = 0 Error = 1 Perm = 3 Busy = 5 NoMem = 7 ReadOnly = 8 IOErr = 10 Full = 13 CantOpen = 14 IOErrRead = IOErr | 1<<8 IOErrShortRead = IOErr | 2<<8 IOErrWrite = IOErr | 3<<8 IOErrFsync = IOErr | 4<<8 IOErrDirFsync = IOErr | 5<<8 IOErrTruncate = IOErr | 6<<8 IOErrFstat = IOErr | 7<<8 IOErrUnlock = IOErr | 8<<8 IOErrRdlock = IOErr | 9<<8 IOErrDelete = IOErr | 10<<8 IOErrNoMem = IOErr | 12<<8 IOErrAccess = IOErr | 13<<8 IOErrCheckReservedLock = IOErr | 14<<8 IOErrLock = IOErr | 15<<8 IOErrClose = IOErr | 16<<8 IOErrShmOpen = IOErr | 18<<8 IOErrShmSize = IOErr | 19<<8 IOErrShmLock = IOErr | 20<<8 IOErrShmMap = IOErr | 21<<8 IOErrDeleteNoent = IOErr | 23<<8 IOErrGetTempPath = IOErr | 25<<8 IOErrCorruptFS = IOErr | 33<<8 CantOpenIsDir = CantOpen | 2<<8 ReadOnlyCantInit = ReadOnly | 5<<8 ReadOnlyDirectory = ReadOnly | 6<<8 // OKSymlink is what FullPathname returns when it followed a symbolic // link. SQLite turns it into OK, or into SQLITE_CANTOPEN_SYMLINK when the // database was opened with SQLITE_OPEN_NOFOLLOW. OKSymlink = OK | 2<<8 )
Result codes, with the values of sqlite3.h.
const ( OpenReadOnly = 0x00000001 OpenReadWrite = 0x00000002 OpenCreate = 0x00000004 OpenDeleteOnClose = 0x00000008 OpenExclusive = 0x00000010 OpenAutoProxy = 0x00000020 OpenURI = 0x00000040 OpenMemory = 0x00000080 OpenMainDB = 0x00000100 OpenTempDB = 0x00000200 OpenTransientDB = 0x00000400 OpenMainJournal = 0x00000800 OpenTempJournal = 0x00001000 OpenSubjournal = 0x00002000 OpenSuperJournal = 0x00004000 OpenWAL = 0x00080000 OpenNoFollow = 0x01000000 )
Open flags (SQLITE_OPEN_*).
const ( LockNone = 0 LockReserved = 2 LockPending = 3 LockExclusive = 4 )
Lock levels (SQLITE_LOCK_*).
const ( ShmUnlock = 1 ShmLock = 2 ShmExclusive = 8 ShmNLock = 8 )
Shared memory lock flags (SQLITE_SHM_*).
const ( SyncNormal = 0x00002 SyncFull = 0x00003 SyncDataOnly = 0x00010 )
Sync flags (SQLITE_SYNC_*).
const ( AccessExists = 0 AccessReadWrite = 1 AccessRead = 2 )
Access flags (SQLITE_ACCESS_*).
const ( IOCapPowersafeOverwrite = 0x00001000 IOCapSubpageRead = 0x00008000 )
Device characteristics (SQLITE_IOCAP_*).
const ( // MaxPathname is the size of the buffer FullPathname fills, as // os_unix's MAX_PATHNAME. Give it to SQLite as sqlite3_vfs.mxPathname. MaxPathname = 512 )
Variables ¶
This section is empty.
Functions ¶
func Access ¶
Access tells whether name exists (as os_unix, an empty regular file does not), or can be read and written, or read.
func FullPathname ¶
FullPathname is os_unix's unixFullPathname: the absolute path of name, with ".", ".." and symbolic links resolved one part at a time. The result code is OKSymlink when a link was followed: give it to SQLite as it is. A path that does not fit in MaxPathname bytes is SQLITE_CANTOPEN.
func ShmBarrier ¶
func ShmBarrier()
ShmBarrier is a full memory barrier, as sqlite3MemoryBarrier (__sync_synchronize): MFENCE on amd64, DMB ISH on arm64. No load or store moves across it in either direction. A Go atomic is not enough on arm64: without LSE it is a LDAXR/STLXR loop, which lets an earlier store pass a later load.
Types ¶
type File ¶
type File struct {
// contains filtered or unexported fields
}
File is an open file, as os_unix's unixFile.
func Open ¶
Open opens name with SQLITE_OPEN_* flags, as os_unix's unixOpen. An empty name is a temporary file, deleted when closed. outFlags are the flags the file was opened with: READONLY in place of READWRITE and CREATE when it could only be opened for reading.
func (*File) CheckReservedLock ¶
CheckReservedLock tells whether some File, of this process or another, holds RESERVED or more.
func (*File) Close ¶
Close closes the file, and its shared memory if ShmUnmap was not called. The locks the File holds are released, and those of other Files of the database are kept. Closing twice is harmless.
func (*File) DeviceCharacteristics ¶
DeviceCharacteristics is that of os_unix with powersafe overwrite on, the default of SQLite.
func (*File) HasMoved ¶
HasMoved is SQLITE_FCNTL_HAS_MOVED: the path the main database was opened with no longer names this file (renamed, deleted or replaced).
func (*File) Lock ¶
Lock raises the lock to level: SHARED, RESERVED or EXCLUSIVE. SQLite never asks for PENDING. When EXCLUSIVE fails from RESERVED, the File keeps PENDING, so that the next try does not race new readers.
func (*File) ReadAt ¶
ReadAt reads len(p) bytes at off. When the file ends first, the rest of p is zeroed and the result is SQLITE_IOERR_SHORT_READ.
func (*File) SectorSize ¶
SectorSize is os_unix's SQLITE_DEFAULT_SECTOR_SIZE.
func (*File) SetChunkSize ¶
SetChunkSize is SQLITE_FCNTL_CHUNK_SIZE: Truncate and SizeHint round the size up to whole chunks of n bytes. 0 turns it off.
func (*File) ShmLock ¶
ShmLock locks or unlocks n slots of the wal-index from offset, as os_unix's unixShmLock. flags is SQLITE_SHM_LOCK or SQLITE_SHM_UNLOCK with SQLITE_SHM_SHARED or SQLITE_SHM_EXCLUSIVE. A shared lock is on one slot. SQLite never asks for a lock it holds, nor moves a slot between shared and exclusive without unlocking it first.
func (*File) ShmMap ¶
ShmMap returns the address of region n of the wal-index, each region size bytes. When the region is not there yet, extend makes it, and without extend the address is 0 and the result OK. The memory stays mapped until ShmUnmap. With a -shm that can only be read, the result is SQLITE_READONLY with the address, or SQLITE_READONLY_CANTINIT when no other connection has it open.
func (*File) ShmUnmap ¶
ShmUnmap detaches the File from the wal-index and releases the slots it still holds. The last File of the process unmaps the memory and closes the -shm, which drops the DMS lock. remove then deletes the file: SQLite asks for that only while it holds EXCLUSIVE on the database and no other connection has the -shm open. Without a wal-index it does nothing.
func (*File) Size ¶
Size is the size of the file. As os_unix, a size of 1 is given as 0: a work around for the msdos file system of OS X, kept so that SQLite sees the same sizes it would see with os_unix.
func (*File) SizeHint ¶
SizeHint is SQLITE_FCNTL_SIZE_HINT, as os_unix's fcntlSizeHint: with a chunk size set, make the file at least size bytes, rounded up to whole chunks. Without a chunk size it does nothing, as os_unix when memory mapped I/O is off.
func (*File) Sync ¶
Sync writes the file to disk, and the directory entry of a new journal the first time. See fullFsync for what each system does.
func (*File) Truncate ¶
Truncate sets the size of the file, rounded up to whole chunks when SetChunkSize was called.