vfs

type File ¶

type File interface {
	io.Reader
	io.Writer
	io.Seeker
	io.Closer

	ReadAt(p []byte, off int64) (n int, err error)
	WriteAt(p []byte, off int64) (n int, err error)

	// Sync commits the file's contents to stable storage. A driver that
	// simulates a power cut discards everything not yet passed to Sync.
	Sync() error

	// Truncate changes the file's size.
	Truncate(size int64) error

	// Name returns the name the file was opened with.
	Name() string
}

File is an open file.

The method set is the intersection of what pkg/wal, pkg/lsm, pkg/btree and pkg/storage actually use, deliberately: a wider interface is harder to implement correctly in a fault driver, and every method here is one a wonky implementation has to get right.

type FileSystem ¶

type FileSystem interface {
	// Open opens a file with the semantics of os.OpenFile.
	Open(name string, flag int, perm os.FileMode) (File, error)

	// Remove deletes a file, with the semantics of os.Remove.
	Remove(name string) error

	// Rename moves a file, with the semantics of os.Rename. graphdb relies on
	// this being atomic on POSIX for snapshot and WAL rotation, so an
	// implementation that cannot offer atomicity must say so in its docs.
	Rename(oldpath, newpath string) error

	// Stat returns file metadata, with the semantics of os.Stat.
	Stat(name string) (os.FileInfo, error)

	// MkdirAll creates a directory tree, with the semantics of os.MkdirAll.
	MkdirAll(path string, perm os.FileMode) error

	// ReadDir lists a directory, with the semantics of os.ReadDir.
	//
	// Added when pkg/lsm became the second caller: it enumerates its SSTables,
	// and a driver that cannot fail a directory listing cannot test what
	// happens when that listing fails. The method set is the intersection of
	// what callers actually use, so the intersection grew.
	ReadDir(name string) ([]os.DirEntry, error)

	// Name identifies the driver, for diagnostics and for tests that assert
	// which driver is installed. "os" is the default.
	Name() string
}

FileSystem is the set of filesystem operations graphdb performs.

An implementation must be safe for concurrent use: graphdb opens and syncs files from several goroutines.

func Default() FileSystem

func Get(name string) (FileSystem, bool)

func OS() FileSystem

func Resolve(name string) (FileSystem, error)

type Locker ¶ added in v1.10.0

type Locker interface {
	// Lock takes the lock on name, creating the file if it does not exist. It
	// does not wait: a lock another holder has returns ErrLocked at once.
	// release drops the lock and must be called exactly once.
	Lock(name string) (release func() error, err error)
}

Locker is an OPTIONAL capability: an exclusive, non-blocking lock on a file, which the operating system releases when the holder dies.

It is optional for the reason Mapper is: FileSystem is a published interface, and a new method on it breaks every driver outside this repository. A fault or in-memory driver has no second process to exclude, so it has nothing to implement.

Why not File.Fd ¶

The OS driver needs a descriptor for flock, and File has no Fd method for the reason Mapper documents. Locking is the operation the caller needs, so that is what the interface exposes.

type Mapper ¶

type Mapper interface {
	// Map returns the file's entire contents and a function that releases them.
	//
	// The bytes stay valid until release is called, and the caller must not
	// retain them afterwards. Callers must call release exactly once, even
	// when they only read part of the data.
	//
	// A driver that cannot map returns ErrMapUnsupported, and the caller falls
	// back to reading the file through Open.
	Map(name string) (data []byte, release func() error, err error)
}

Mapper is an OPTIONAL capability. A FileSystem may implement it to expose a file's whole contents as one byte slice.

It is deliberately not a method on FileSystem. FileSystem is a published interface, and adding a method to it breaks every implementation outside this repository (see the Stability note on this package). An optional interface costs a driver that does not want it nothing.

Why graphdb needs it ¶

The mmap snapshot reader calls syscall.Mmap on a file descriptor. File has no Fd method and should not grow one: a fault driver has no descriptor to give, so an Fd-shaped seam would let the OS driver through and lock every other driver out — which is the same test-only seam this package exists to remove.

Mapping is the operation the reader actually needs, so that is what the interface exposes. The OS driver satisfies it with mmap. A fault driver satisfies it by returning a buffer it chose, which is how a truncated or corrupt snapshot reaches the production read path without a corrupt file ever existing on disk. SQLite makes the same move with xFetch on sqlite3_io_methods.