fslock

Documentation

Overview

Package fslock provides an on-disk mutex protecting a resource

A lock is represented on disk by a directory of a particular name, containing an information file. Taking a lock is done by renaming a temporary directory into place. We use temporary directories because for all filesystems we believe that exactly one attempt to claim the lock will succeed and the others will fail.

Index

• Constants
• Variables
• type Lock
  • func NewLock(lockDir, name string, cfg LockConfig) (*Lock, error)
  • func (lock *Lock) BreakLock() error
  • func (lock *Lock) IsLockHeld() bool
  • func (lock *Lock) IsLocked() bool
  • func (lock *Lock) Lock(message string) error
  • func (lock *Lock) LockWithFunc(message string, continueFunc func() error) error
  • func (lock *Lock) LockWithTimeout(duration time.Duration, message string) error
  • func (lock *Lock) Message() string
  • func (lock *Lock) Unlock() error
• type LockConfig
  • func Defaults() LockConfig

Constants

const (
	// NameRegexp specifies the regular expression used to identify valid lock names.
	NameRegexp = "^[a-z]+[a-z0-9.-]*$"
)

Variables

var (

	// ErrLockNotHeld is returned by Unlock if the lock file is not held by this lock
	ErrLockNotHeld = errors.New("lock not held")
	// ErrTimeout is returned by LockWithTimeout if the lock could not be obtained before the given deadline
	ErrTimeout = errors.New("lock timeout exceeded")
)

Types

type Lock

type Lock struct {
	PID int
	// contains filtered or unexported fields
}

Lock is a file system lock

func NewLock

func NewLock(lockDir, name string, cfg LockConfig) (*Lock, error)

NewLock returns a new lock with the given name within the given lock directory, without acquiring it. The lock name must match the regular expression defined by NameRegexp.

func (*Lock) BreakLock

func (lock *Lock) BreakLock() error

BreakLock forcibly breaks the lock that is currently being held.

func (*Lock) IsLockHeld

func (lock *Lock) IsLockHeld() bool

IsLockHeld returns whether the lock is currently held by the receiver.

func (*Lock) IsLocked

func (lock *Lock) IsLocked() bool

IsLocked returns true if the lock is currently held by anyone.

func (*Lock) Lock

func (lock *Lock) Lock(message string) error

Lock blocks until it is able to acquire the lock. Since we are dealing with sharing and locking using the filesystem, it is good behaviour to provide a message that is saved with the lock. This is output in debugging information, and can be queried by any other Lock dealing with the same lock name and lock directory.

func (*Lock) LockWithFunc

func (lock *Lock) LockWithFunc(message string, continueFunc func() error) error

LockWithFunc blocks until it is able to acquire the lock. If the lock is failed to be acquired, the continueFunc is called prior to the sleeping. If the continueFunc returns an error, that error is returned from LockWithFunc.

func (*Lock) LockWithTimeout

func (lock *Lock) LockWithTimeout(duration time.Duration, message string) error

LockWithTimeout tries to acquire the lock. If it cannot acquire the lock within the given duration, it returns ErrTimeout. See `Lock` for information about the message.

func (*Lock) Message

func (lock *Lock) Message() string

Message returns the saved message, or the empty string if there is no saved message.

func (*Lock) Unlock

func (lock *Lock) Unlock() error

Unlock releases a held lock. If the lock is not held ErrLockNotHeld is returned.

type LockConfig

type LockConfig struct {
	// Clock is used to generate delays
	Clock clock.Clock
	// WaitDelay is how long to wait after trying to aquire a lock before trying again
	WaitDelay time.Duration
	// LividityTimeout is how old a lock can be without us considering its
	// parent process dead.
	LividityTimeout time.Duration
	// ReadRetryTimeout is how long to wait after trying to examine a lock
	// and not finding it before trying again.
	ReadRetryTimeout time.Duration
}

LockConfig defines the configuration of the new lock. Sensible defaults can be obtained from Defaults().

func Defaults

func Defaults() LockConfig

Defaults generates a LockConfig pre-filled with sensible defaults.