fslock

Documentation

Overview

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) (*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

Constants

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

Variables

var (
	ErrLockNotHeld = errors.New("lock not held")
	ErrTimeout     = errors.New("lock timeout exceeded")

	LockWaitDelay = 1 * time.Second
)

Types

type Lock

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

func NewLock

func NewLock(lockDir, name string) (*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 forcably 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.