lockfile

README

lockfile

Handle locking via pid files.

Attention: This is a fork of Ingo Oeser's amazing work whose behavior differs a bit. While the original package allows a process to obtain the same lock twice, this fork forbids this behavior.

Install

Install one of the two latest major releases of Go. Then run

go get github.com/tus/lockfile

Documentation

Package documentation at pkg.go.dev.

Contributing

Contributions are welcome. Please open an issue or send me a pull request for a dedicated branch.

License

MIT

Documentation

Overview

Package lockfile handles pid file based locking. While a sync.Mutex helps against concurrency issues within a single process, this package is designed to help against concurrency issues between cooperating processes or serializing multiple invocations of the same process.

Index

• Variables
• type Lockfile
  • func New(path string) (Lockfile, error)
  • func (l Lockfile) GetOwner() (*os.Process, error)
  • func (l Lockfile) TryLock() error
  • func (l Lockfile) Unlock() error
• type TemporaryError
  • func (t TemporaryError) Error() string
  • func (t TemporaryError) Temporary() bool

Examples

• Lockfile

Variables

var (
	ErrBusy          = TemporaryError("Locked by other process")             // If you get this, retry after a short sleep might help
	ErrNotExist      = TemporaryError("Lockfile created, but doesn't exist") // If you get this, retry after a short sleep might help
	ErrNeedAbsPath   = errors.New("Lockfiles must be given as absolute path names")
	ErrInvalidPid    = errors.New("Lockfile contains invalid pid for system")
	ErrDeadOwner     = errors.New("Lockfile contains pid of process not existent on this system anymore")
	ErrRogueDeletion = errors.New("Lockfile owned by me has been removed unexpectedly")
)

Various errors returned by this package

Types

type Lockfile

type Lockfile string

Lockfile is a pid file which can be locked

Example

lock, err := New(filepath.Join(os.TempDir(), "lock.me.now.lck"))
if err != nil {
	fmt.Printf("Cannot init lock. reason: %v", err)
	panic(err) // handle properly please!
}

// Error handling is essential, as we only try to get the lock.
if err = lock.TryLock(); err != nil {
	fmt.Printf("Cannot lock %q, reason: %v", lock, err)
	panic(err) // handle properly please!
}

defer func() {
	if err := lock.Unlock(); err != nil {
		fmt.Printf("Cannot unlock %q, reason: %v", lock, err)
		panic(err) // handle properly please!
	}
}()

fmt.Println("Do stuff under lock")

Output:

Do stuff under lock

func New

func New(path string) (Lockfile, error)

New describes a new filename located at the given absolute path.

func (Lockfile) GetOwner

func (l Lockfile) GetOwner() (*os.Process, error)

GetOwner returns who owns the lockfile.

func (Lockfile) TryLock

func (l Lockfile) TryLock() error

TryLock tries to own the lock. It Returns nil, if successful and and error describing the reason, it didn't work out. Please note, that existing lockfiles containing pids of dead processes and lockfiles containing no pid at all are simply deleted.

func (Lockfile) Unlock

func (l Lockfile) Unlock() error

Unlock a lock again, if we owned it. Returns any error that happened during release of lock.

type TemporaryError

type TemporaryError string

TemporaryError is a type of error where a retry after a random amount of sleep should help to mitigate it.

func (TemporaryError) Error

func (t TemporaryError) Error() string

func (TemporaryError) Temporary

func (t TemporaryError) Temporary() bool

Temporary returns always true. It exists, so you can detect it via

if te, ok := err.(interface{ Temporary() bool }); ok {
	fmt.Println("I am a temporary error situation, so wait and retry")
}