lockfile

README

lockfile

Handle locking via pid files.

install

Install Go 1, either from source or with a prepackaged binary. For Windows suport, Go 1.4 or newer is required.

Then run

go get github.com/nightlyone/lockfile

LICENSE

MIT

documentation

package documentation at godoc.org

install

go get github.com/nightlyone/lockfile

contributing

Contributions are welcome. Please open an issue or send me a pull request for a dedicated branch. Make sure the git commit hooks show it works.

git commit hooks

enable commit hooks via

    cd .git ; rm -rf hooks; ln -s ../git-hooks hooks ; cd ..

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. You can also combine sync.Mutex with Lockfile in order to serialize an action between different goroutines in a single program and also multiple invocations of this program.

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")
}