flock

README

go-flock

flock implements a thread-safe sync.Locker interface for file locking. It also includes a non-blocking TryLock() function to allow locking without blocking execution.

License

flock is released under the BSD 3-Clause License. See the LICENSE file for more details.

Intsallation

go get -u github.com/theckman/go-flock

Usage

import "github.com/theckman/go-flock"

fileLock := flock.NewFlock("/var/lock/go-lock.lock")

locked, err := fileLock.TryLock()

if err != nil {
	// handle locking error
}

if locked {
	// do work
	fileLock.Unlock()
}

For more detailed usage information take a look at the package API docs on GoDoc.

Documentation

Overview

Package flock implements a thread-safe sync.Locker interface for file locking. It also includes a non-blocking TryLock() function to allow locking without blocking execution.

Package flock is released under the BSD 3-Clause License. See the LICENSE file for more details.

Index

• Constants
• type Flock
  • func NewFlock(path string) *Flock
  • func (f *Flock) Lock() error
  • func (f *Flock) Locked() bool
  • func (f *Flock) Path() string
  • func (f *Flock) String() string
  • func (f *Flock) TryLock() (bool, error)
  • func (f *Flock) Unlock() error

Examples

• Flock.Locked
• Flock.TryLock

Constants

const (
	LOCKFILE_FAIL_IMMEDIATELY = 0x00000001
	LOCKFILE_EXCLUSIVE_LOCK   = 0x00000002
)

Types

type Flock

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

Flock is the struct type to handle file locking. All fields are unexported, with access to some of the fields provided by getter methods (Path() and Locked()).

func NewFlock

func NewFlock(path string) *Flock

NewFlock is a function to return a new instance of *Flock. The only parameter it takes is the path to the desired lockfile.

func (*Flock) Lock

func (f *Flock) Lock() error

Lock is a blocking call to try and take the file lock. It will wait until it is able to obtain the exclusive file lock. It's recommended that TryLock() be used over this function. This function may block the ability to query the current Locked() status due to a RW-mutex lock.

If we are already locked, this function short-circuits and returns immediately assuming it can take the mutex lock.

func (*Flock) Locked

func (f *Flock) Locked() bool

Locked is a function to return the current lock state (locked: true, unlocked: false).

Example

f := flock.NewFlock("/tmp/go-lock.lock")
f.TryLock() // unchecked errors here

fmt.Printf("locked: %v\n", f.Locked())

f.Unlock()

fmt.Printf("locked: %v\n", f.Locked())

Output:

locked: true
locked: false

func (*Flock) Path

func (f *Flock) Path() string

Path is a function to return the path as provided in NewFlock().

func (*Flock) String

func (f *Flock) String() string

func (*Flock) TryLock

func (f *Flock) TryLock() (bool, error)

TryLock is the preferred function for taking a file lock. This function does take a RW-mutex lock before it tries to lock the file, so there is the possibility that this function may block for a short time if another goroutine is trying to take any action.

The actual file lock is non-blocking. If we are unable to get the exclusive file lock, the function will return false instead of waiting for the lock. If we get the lock, we also set the *Flock instance as being locked.

Example

// should probably put these in /var/lock
fileLock := flock.NewFlock("/tmp/go-lock.lock")

locked, err := fileLock.TryLock()

if err != nil {
	// handle locking error
}

if locked {
	fmt.Printf("path: %s; locked: %v\n", fileLock.Path(), fileLock.Locked())

	if err := fileLock.Unlock(); err != nil {
		// handle unlock error
	}
}

fmt.Printf("path: %s; locked: %v\n", fileLock.Path(), fileLock.Locked())

Output:

path: /tmp/go-lock.lock; locked: true
path: /tmp/go-lock.lock; locked: false

func (*Flock) Unlock

func (f *Flock) Unlock() error

Unlock is a function to unlock the file. This file takes a RW-mutex lock, so while it is running the Locked() function will be blocked.

This function short-circuits if we are unlocked already. If not, it calls syscall.LOCK_UN on the file and closes the file descriptor It does not remove the file from disk. It's up to your application to do.