filelock

README

Filelock

Filelock provides helpful utility functions around using flock to take locks on filesystem paths in go.

This code was extracted from the rkt project after it was archived.

License

Apache 2.0.

Copyright The rkt authors

Documentation

Overview

Package filelock implements simple locking primitives on a regular file or directory using flock

Index

• Variables
• func CleanKeyLocks(lockDir string) error
• type FileLock
  • func ExclusiveLock(path string, lockType LockType) (*FileLock, error)
  • func NewLock(path string, lockType LockType) (*FileLock, error)
  • func SharedLock(path string, lockType LockType) (*FileLock, error)
  • func TryExclusiveLock(path string, lockType LockType) (*FileLock, error)
  • func TrySharedLock(path string, lockType LockType) (*FileLock, error)
  • func (l *FileLock) Close() error
  • func (l *FileLock) ExclusiveLock() error
  • func (l *FileLock) Fd() (int, error)
  • func (l *FileLock) SharedLock() error
  • func (l *FileLock) TryExclusiveLock() error
  • func (l *FileLock) TrySharedLock() error
  • func (l *FileLock) Unlock() error
• type KeyLock
  • func ExclusiveKeyLock(lockDir string, key string) (*KeyLock, error)
  • func NewKeyLock(lockDir string, key string) (*KeyLock, error)
  • func SharedKeyLock(lockDir string, key string) (*KeyLock, error)
  • func TryExclusiveKeyLock(lockDir string, key string) (*KeyLock, error)
  • func TrySharedKeyLock(lockDir string, key string) (*KeyLock, error)
  • func (l *KeyLock) Close()
  • func (l *KeyLock) ExclusiveKeyLock() error
  • func (l *KeyLock) SharedKeyLock() error
  • func (l *KeyLock) TryExclusiveKeyLock() error
  • func (l *KeyLock) TrySharedKeyLock() error
  • func (l *KeyLock) Unlock() error
• type LockType

Variables

var (
	ErrLocked     = errors.New("file already locked")
	ErrNotExist   = errors.New("file does not exist")
	ErrPermission = errors.New("permission denied")
	ErrNotRegular = errors.New("not a regular file")
)

Functions

func CleanKeyLocks

func CleanKeyLocks(lockDir string) error

CleanKeyLocks remove lock files from the lockDir. For every key it tries to take an Exclusive lock on it and skip it if it fails with ErrLocked

Types

type FileLock

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

FileLock represents a lock on a regular file or a directory

func ExclusiveLock

func ExclusiveLock(path string, lockType LockType) (*FileLock, error)

ExclusiveLock takes an exclusive lock on a file/directory. It will block if an exclusive lock is already held on the file/directory.

func NewLock

func NewLock(path string, lockType LockType) (*FileLock, error)

NewLock opens a new lock on a file without acquisition. Consumers are responsible for calling close on FileLock after they are done with it.

func SharedLock

func SharedLock(path string, lockType LockType) (*FileLock, error)

SharedLock takes a co-operative (shared) lock on a file/directory. It will block if an exclusive lock is already held on the file/directory.

func TryExclusiveLock

func TryExclusiveLock(path string, lockType LockType) (*FileLock, error)

TryExclusiveLock takes an exclusive lock on a file/directory without blocking. It will return ErrLocked if any lock is already held on the file/directory.

func TrySharedLock

func TrySharedLock(path string, lockType LockType) (*FileLock, error)

TrySharedLock takes a co-operative (shared) lock on a file/directory without blocking. It will return ErrLocked if an exclusive lock already exists on the file/directory.

func (*FileLock) Close

func (l *FileLock) Close() error

Close closes the lock which implicitly unlocks it as well

func (*FileLock) ExclusiveLock

func (l *FileLock) ExclusiveLock() error

ExclusiveLock takes an exclusive lock. This is idempotent when the Lock already represents an exclusive lock, and promotes a shared lock to exclusive atomically. It will block if an exclusive lock is already held.

func (*FileLock) Fd

func (l *FileLock) Fd() (int, error)

Fd returns the lock's file descriptor, or an error if the lock is closed

func (*FileLock) SharedLock

func (l *FileLock) SharedLock() error

SharedLock takes a co-operative (shared) lock on. This is idempotent when the Lock already represents a shared lock, and demotes an exclusive lock to shared atomically. It will block if an exclusive lock is already held.

func (*FileLock) TryExclusiveLock

func (l *FileLock) TryExclusiveLock() error

TryExclusiveLock takes an exclusive lock without blocking. This is idempotent when the Lock already represents an exclusive lock, and tries promote a shared lock to exclusive atomically. It will return ErrLocked if any lock is already held.

func (*FileLock) TrySharedLock

func (l *FileLock) TrySharedLock() error

TrySharedLock takes a co-operative (shared) lock without blocking. This is idempotent when the Lock already represents a shared lock, and tries demote an exclusive lock to shared atomically. It will return ErrLocked if an exclusive lock already exists.

func (*FileLock) Unlock

func (l *FileLock) Unlock() error

Unlock unlocks the lock

type KeyLock

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

KeyLock is a lock for a specific key. The lock file is created inside a directory using the key name. This is useful when multiple processes want to take a lock but cannot use FileLock as they don't have a well defined file on the filesystem. key value must be a valid file name (as the lock file is named after the key value).

func ExclusiveKeyLock

func ExclusiveKeyLock(lockDir string, key string) (*KeyLock, error)

ExclusiveLock takes an exclusive lock on a key. lockDir is the directory where the lock file will be created. It will block if an exclusive lock is already held on the key.

func NewKeyLock

func NewKeyLock(lockDir string, key string) (*KeyLock, error)

NewKeyLock returns a KeyLock for the specified key without acquisition. lockdir is the directory where the lock file will be created. If lockdir doesn't exists it will be created. key value must be a valid file name (as the lock file is named after the key value).

func SharedKeyLock

func SharedKeyLock(lockDir string, key string) (*KeyLock, error)

SharedLock takes a co-operative (shared) lock on a key. lockDir is the directory where the lock file will be created. It will block if an exclusive lock is already held on the key.

func TryExclusiveKeyLock

func TryExclusiveKeyLock(lockDir string, key string) (*KeyLock, error)

TryExclusiveLock takes an exclusive lock on the key without blocking. lockDir is the directory where the lock file will be created. It will return ErrLocked if any lock is already held.

func TrySharedKeyLock

func TrySharedKeyLock(lockDir string, key string) (*KeyLock, error)

TrySharedLock takes a co-operative (shared) lock on a key without blocking. lockDir is the directory where the lock file will be created. It will return ErrLocked if an exclusive lock already exists on the key.

func (*KeyLock) Close

func (l *KeyLock) Close()

Close closes the key lock which implicitly unlocks it as well

func (*KeyLock) ExclusiveKeyLock

func (l *KeyLock) ExclusiveKeyLock() error

ExclusiveLock takes an exclusive lock on a key. This is idempotent when the KeyLock already represents an exclusive lock, and promotes a shared lock to exclusive atomically. It will block if an exclusive lock is already held on the key.

func (*KeyLock) SharedKeyLock

func (l *KeyLock) SharedKeyLock() error

SharedLock takes a co-operative (shared) lock on a key. This is idempotent when the KeyLock already represents a shared lock, and demotes an exclusive lock to shared atomically. It will block if an exclusive lock is already held on the key.

func (*KeyLock) TryExclusiveKeyLock

func (l *KeyLock) TryExclusiveKeyLock() error

TryExclusiveLock takes an exclusive lock on a key without blocking. This is idempotent when the KeyLock already represents an exclusive lock, and tries promote a shared lock to exclusive atomically. It will return ErrLocked if any lock is already held on the key.

func (*KeyLock) TrySharedKeyLock

func (l *KeyLock) TrySharedKeyLock() error

TrySharedLock takes a co-operative (shared) lock on the key without blocking. This is idempotent when the KeyLock already represents a shared lock, and tries demote an exclusive lock to shared atomically. It will return ErrLocked if an exclusive lock already exists on the key.

func (*KeyLock) Unlock

func (l *KeyLock) Unlock() error

Unlock unlocks the key lock.

type LockType

type LockType int

const (
	Dir LockType = iota
	RegFile
)