flock

package module
v0.12.1 Latest Latest
Warning

This package is not in the latest version of its module.

Go to latest
Published: Jul 22, 2024 License: BSD-3-Clause Imports: 8 Imported by: 1,089

README

flock

Go Reference License Go Report Card

flock implements a thread-safe file lock.

It also includes a non-blocking TryLock() function to allow locking without blocking execution.

Installation

go get -u github.com/gofrs/flock

Usage

import "github.com/gofrs/flock"

fileLock := flock.New("/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.

License

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

Project History

This project was originally github.com/theckman/go-flock, it was transferred to Gofrs by the original author Tim Heckman .

Documentation

Overview

Package flock implements a thread-safe 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.

While using this library, remember that the locking behaviors are not guaranteed to be the same on each platform. For example, some UNIX-like operating systems will transparently convert a shared lock to an exclusive lock. If you Unlock() the flock from a location where you believe that you have the shared lock, you may accidentally drop the exclusive lock.

Index

Examples

Constants

This section is empty.

Variables

This section is empty.

Functions

This section is empty.

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 New added in v0.7.0

func New(path string, opts ...Option) *Flock

New returns a new instance of *Flock. The only parameter it takes is the path to the desired lockfile.

func NewFlock deprecated

func NewFlock(path string) *Flock

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

Deprecated: Use New instead.

func (*Flock) Close added in v0.6.0

func (f *Flock) Close() error

Close is equivalent to calling Unlock.

This will release the lock and close the underlying file descriptor. It will not remove the file from disk, that's up to your application.

func (*Flock) Lock

func (f *Flock) Lock() error

Lock is a blocking call to try and take an exclusive 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() or RLocked() status due to a RW-mutex lock.

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

If the *Flock has a shared lock (RLock), this may transparently replace the shared lock with an exclusive lock on some UNIX-like operating systems. Be careful when using exclusive locks in conjunction with shared locks (RLock()), because calling Unlock() may accidentally release the exclusive lock that was once a shared lock.

func (*Flock) Locked

func (f *Flock) Locked() bool

Locked returns the lock state (locked: true, unlocked: false).

Warning: by the time you use the returned value, the state may have changed.

Example
package main

import (
	"fmt"
	"os"
	"path/filepath"

	"github.com/gofrs/flock"
)

func main() {
	f := flock.New(filepath.Join(os.TempDir(), "go-lock.lock"))

	_, err := f.TryLock()
	if err != nil {
		// handle locking error
		panic(err)
	}

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

	err = f.Unlock()
	if err != nil {
		// handle locking error
		panic(err)
	}

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

}
Output:

locked: true
locked: false

func (*Flock) Path

func (f *Flock) Path() string

Path returns the path as provided in NewFlock().

func (*Flock) RLock added in v0.4.0

func (f *Flock) RLock() error

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

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

func (*Flock) RLocked added in v0.4.0

func (f *Flock) RLocked() bool

RLocked returns the read lock state (locked: true, unlocked: false).

Warning: by the time you use the returned value, the state may have changed.

func (*Flock) String

func (f *Flock) String() string

func (*Flock) TryLock

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

TryLock is the preferred function for taking an exclusive file lock. This function takes an 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 exclusive-locked.

Example
package main

import (
	"fmt"
	"os"
	"path/filepath"

	"github.com/gofrs/flock"
)

func main() {
	// should probably put these in /var/lock
	f := flock.New(filepath.Join(os.TempDir(), "go-lock.lock"))

	locked, err := f.TryLock()
	if err != nil {
		// handle locking error
		panic(err)
	}

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

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

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

func (*Flock) TryLockContext added in v0.2.0

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

TryLockContext repeatedly tries to take an exclusive lock until one of the conditions is met: - TryLock succeeds - TryLock fails with error - Context Done channel is closed.

Example
package main

import (
	"context"
	"fmt"
	"os"
	"path/filepath"
	"time"

	"github.com/gofrs/flock"
)

func main() {
	// should probably put these in /var/lock
	f := flock.New(filepath.Join(os.TempDir(), "go-lock.lock"))

	lockCtx, cancel := context.WithTimeout(context.Background(), 30*time.Second)
	defer cancel()

	locked, err := f.TryLockContext(lockCtx, 678*time.Millisecond)
	if err != nil {
		// handle locking error
		panic(err)
	}

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

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

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

func (*Flock) TryRLock added in v0.4.0

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

TryRLock is the preferred function for taking a shared file lock. This function takes an 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 shared 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 share-locked.

func (*Flock) TryRLockContext added in v0.4.0

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

TryRLockContext repeatedly tries to take a shared lock until one of the conditions is met: - TryRLock succeeds - TryRLock fails with error - Context Done channel is closed.

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() and RLocked() functions will be blocked.

This function short-circuits if we are unlocked already. If not, it calls unix.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.

Please note, if your shared lock became an exclusive lock, this may unintentionally drop the exclusive lock if called by the consumer that believes they have a shared lock. Please see Lock() for more details.

type Option added in v0.11.0

type Option func(f *Flock)

func SetFlag added in v0.11.0

func SetFlag(flag int) Option

SetFlag sets the flag used to create/open the file.

func SetPermissions added in v0.11.0

func SetPermissions(perm fs.FileMode) Option

SetPermissions sets the OS permissions to set on the file.

Jump to

Keyboard shortcuts

? : This menu
/ : Search site
f or F : Jump to
y or Y : Canonical URL