filelock

Documentation

Overview

Package filelock provides a platform-independent API for advisory file locking. Calls to functions in this package on platforms that do not support advisory locks will return errors for which filelock.IsNotSupported returns true.

Index

• Variables
• func IsNotSupported(err error) bool
• func Lock(f File) error
• func RLock(f File) error
• func Unlock(f File) error
• type File
• type Mutex
  • func MutexAt(path string) *Mutex
  • func (mu *Mutex) Lock() (unlock func(), err error)
  • func (mu *Mutex) RLock() (runlock func(), err error)

Variables

var ErrNotSupported = errors.New("operation not supported")

ErrNotSupported is a checkable error (with IsNotSupported(...)) that indicates a given operation is not supported.

Functions

func IsNotSupported

func IsNotSupported(err error) bool

IsNotSupported returns a boolean indicating whether the error is known to report that a function is not supported (possibly for a specific input). It is satisfied by ErrNotSupported as well as some syscall errors.

func Lock

func Lock(f File) error

Lock places an advisory write lock on the file, blocking until it can be locked.

If Lock returns nil, no other process will be able to place a read or write lock on the file until this process exits, closes f, or calls Unlock on it.

If f's descriptor is already read- or write-locked, the behavior of Lock is unspecified.

Closing the file may or may not release the lock promptly. Callers should ensure that Unlock is always called when Lock succeeds.

func RLock

func RLock(f File) error

RLock places an advisory read lock on the file, blocking until it can be locked.

If RLock returns nil, no other process will be able to place a write lock on the file until this process exits, closes f, or calls Unlock on it.

If f is already read- or write-locked, the behavior of RLock is unspecified.

Closing the file may or may not release the lock promptly. Callers should ensure that Unlock is always called if RLock succeeds.

func Unlock

func Unlock(f File) error

Unlock removes an advisory lock placed on f by this process.

The caller must not attempt to unlock a file that is not locked.

Types

type File

type File interface {
	// Name returns the name of the file.
	Name() string

	// Fd returns a valid file descriptor.
	// (If the File is an *os.File, it must not be closed.)
	Fd() uintptr

	// Stat returns the FileInfo structure describing file.
	Stat() (fs.FileInfo, error)
}

A File provides the minimal set of methods required to lock an open file. File implementations must be usable as map keys. The usual implementation is *os.File.

type Mutex

type Mutex struct {

	// Path is the file path to use as the lock.
	Path string
	// contains filtered or unexported fields
}

Mutex manages filehandle based locks that are scoped to the lifetime of a parent process. If you need semi-durable locks that can span for the duration of an action, use `fslock.FSLock` in the github-actions project.

It does not implement `sync.Locker` because file based mutexes can fail to Lock().

func MutexAt

func MutexAt(path string) *Mutex

MutexAt returns a file based mutex at a given path.

func (*Mutex) Lock

func (mu *Mutex) Lock() (unlock func(), err error)

Lock attempts to lock the Mutex.

If successful, Lock returns a non-nil unlock function: it is provided as a return-value instead of a separate method to remind the caller to check the accompanying error. (See https://golang.org/issue/20803.)

func (*Mutex) RLock

func (mu *Mutex) RLock() (runlock func(), err error)

RLock creates a reader lock and returns an unlock function.