package flock

import "github.com/gofrs/flock"

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 ¶

• 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) TryLockContext(ctx context.Context, retryDelay time.Duration) (bool, error)
• func (f *Flock) Unlock() error

Examples ¶

• Flock.Locked
• Flock.TryLock
• Flock.TryLockContext

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).

{
	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
}

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.

{
	// 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
}

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

func (*Flock) TryLockContext ¶

func (f *Flock) TryLockContext(ctx context.Context, retryDelay time.Duration) (bool, error)

TryLockContext repeatedly tries locking until one of the conditions is met: TryLock succeeds, TryLock fails with error, or Context Done channel is closed.

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

	lockCtx, cancel := context.WithTimeout(context.Background(), 30*time.Second)
	defer cancel()
	locked, err := fileLock.TryLockContext(lockCtx, 678*time.Millisecond)

	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
}

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.

Source Files ¶

flock.go flock_unix.go