gofer

Documentation

Overview

Package gofer provides a filesystem implementation that is backed by a 9p server, interchangeably referred to as "gofers" throughout this package.

Lock order:

regularFileFD/directoryFD.mu
  filesystem.renameMu
    dentry.cachingMu
      dentryCache.mu
      dentry.opMu
        dentry.childrenMu
        filesystem.syncMu
        dentry.metadataMu
          *** "memmap.Mappable/MappingIdentity locks" below this point
          dentry.mapsMu
            *** "memmap.Mappable locks taken by Translate" below this point
            dentry.handleMu
              dentry.dataMu
          filesystem.ancestryMu
          filesystem.inoMu
specialFileFD.mu
  specialFileFD.bufMu

Locking dentry.opMu and dentry.metadataMu in multiple dentries requires that either ancestor dentries are locked before descendant dentries, or that filesystem.renameMu is locked for writing.

Index

• Constants
• Variables
• func SetDentryCacheSize(size int)
• type FilesystemType
  • func (fstype FilesystemType) GetFilesystem(ctx context.Context, vfsObj *vfs.VirtualFilesystem, creds *auth.Credentials, ...) (*vfs.Filesystem, *vfs.Dentry, error)
  • func (FilesystemType) Name() string
  • func (FilesystemType) Release(ctx context.Context)
• type InternalFilesystemOptions
• type InteropMode

Constants

const MaxFilenameLen = (1 << 16) - 1

MaxFilenameLen is the maximum length of a filename. This is dictated by 9P's encoding of strings, which uses 2 bytes for the length prefix.

const Name = "9p"

Name is the default filesystem name.

Variables

var SupportedMountOptions = []string{moptOverlayfsStaleRead, moptDisableFileHandleSharing, moptDcache}

SupportedMountOptions is the set of mount options that can be set externally.

Functions

func SetDentryCacheSize

func SetDentryCacheSize(size int)

SetDentryCacheSize sets the size of the global gofer dentry cache.

Types

type FilesystemType

type FilesystemType struct{}

FilesystemType implements vfs.FilesystemType.

+stateify savable

func (FilesystemType) GetFilesystem

func (fstype FilesystemType) GetFilesystem(ctx context.Context, vfsObj *vfs.VirtualFilesystem, creds *auth.Credentials, source string, opts vfs.GetFilesystemOptions) (*vfs.Filesystem, *vfs.Dentry, error)

GetFilesystem implements vfs.FilesystemType.GetFilesystem.

func (FilesystemType) Name

func (FilesystemType) Name() string

Name implements vfs.FilesystemType.Name.

func (FilesystemType) Release

func (FilesystemType) Release(ctx context.Context)

Release implements vfs.FilesystemType.Release.

type InternalFilesystemOptions

type InternalFilesystemOptions struct {
	// If UniqueID is non-empty, it is an opaque string used to reassociate the
	// filesystem with a new server FD during restoration from checkpoint.
	UniqueID vfs.RestoreID

	// If LeakConnection is true, do not close the connection to the server
	// when the Filesystem is released. This is necessary for deployments in
	// which servers can handle only a single client and report failure if that
	// client disconnects.
	LeakConnection bool

	// If OpenSocketsByConnecting is true, silently translate attempts to open
	// files identifying as sockets to connect RPCs.
	//
	// TODO(b/354724938): Remove this option once there are no callers who
	// rely on this behavior.
	OpenSocketsByConnecting bool
}

InternalFilesystemOptions may be passed as vfs.GetFilesystemOptions.InternalData to FilesystemType.GetFilesystem.

+stateify savable

type InteropMode

type InteropMode uint32

InteropMode controls the client's interaction with other remote filesystem users.

+stateify savable

const (
	// InteropModeExclusive is appropriate when the filesystem client is the
	// only user of the remote filesystem.
	//
	//	- The client may cache arbitrary filesystem state (file data, metadata,
	//		filesystem structure, etc.).
	//
	//	- Client changes to filesystem state may be sent to the remote
	//		filesystem asynchronously, except when server permission checks are
	//		necessary.
	//
	//	- File timestamps are based on client clocks. This ensures that users of
	//		the client observe timestamps that are coherent with their own clocks
	//		and consistent with Linux's semantics (in particular, it is not always
	//		possible for clients to set arbitrary atimes and mtimes depending on the
	//		remote filesystem implementation, and never possible for clients to set
	//		arbitrary ctimes.)
	InteropModeExclusive InteropMode = iota

	// InteropModeWritethrough is appropriate when there are read-only users of
	// the remote filesystem that expect to observe changes made by the
	// filesystem client.
	//
	//	- The client may cache arbitrary filesystem state.
	//
	//	- Client changes to filesystem state must be sent to the remote
	//		filesystem synchronously.
	//
	//	- File timestamps are based on client clocks. As a corollary, access
	//		timestamp changes from other remote filesystem users will not be visible
	//		to the client.
	InteropModeWritethrough

	// InteropModeShared is appropriate when there are users of the remote
	// filesystem that may mutate its state other than the client.
	//
	//	- The client must verify ("revalidate") cached filesystem state before
	//		using it.
	//
	//	- Client changes to filesystem state must be sent to the remote
	//		filesystem synchronously.
	//
	//	- File timestamps are based on server clocks. This is necessary to
	//		ensure that timestamp changes are synchronized between remote filesystem
	//		users.
	//
	// Note that the correctness of InteropModeShared depends on the server
	// correctly implementing 9P fids (i.e. each fid immutably represents a
	// single filesystem object), even in the presence of remote filesystem
	// mutations from other users. If this is violated, the behavior of the
	// client is undefined.
	InteropModeShared
)