lockfile

README

go-lockfile

A Linux go library to lock cooperating processes based on syscall flock.

Install

go get github.com/ucloud/go-lockfile

Usage

A simple example:

package main

import (
	"errors"
	"fmt"
	"os"
	"time"

	"github.com/ucloud/go-lockfile"
)

func main() {
	fl := lockfile.New("busy.lock")
	var err error
	for i := 0; i < 20; i++ {
		err = fl.TryLock()
		if err == nil {
			break
		}
		time.Sleep(time.Millisecond * 50)
	}
	if err != nil {
		if errors.Is(err, lockfile.ErrBusy) {
			fmt.Println("The lock is busy")
		} else {
			fmt.Printf("Unexpected error: %v\n", err)
		}
		os.Exit(1)
	}

	fmt.Println("lock!")
	// Handle your logic
	time.Sleep(time.Second)

	err = fl.Unlock()
	if err != nil {
		fmt.Printf("failed to unlock: %v\n", err)
		os.Exit(1)
	}
}

Documentation

Documentation

Overview

Package lockfile is a Linux tool to lock cooperating processes based on syscall `flock`. While a sync.Mutex helps against concurrency issues within a single process, this package is designed to help against concurrency issues between cooperating processes. This package can be only used in Linux, and cannot be used as a `sync.Mutex` in a single process.

Index

• Variables
• type Lockfile
  • func New(path string) *Lockfile
  • func (lf *Lockfile) Lock() error
  • func (lf *Lockfile) TryLock() error
  • func (lf *Lockfile) Unlock() error
• type TemporaryError
  • func (t TemporaryError) Error() string
  • func (t TemporaryError) Temporary() bool

Variables

var (
	// ErrBusy means that the lock is being acquired by anthor process.
	// If you get this, retry after a short sleep might help.
	ErrBusy = TemporaryError("locked by other process")
)

Types

type Lockfile

type Lockfile struct {
	// Path represents the file lock path. It should be shared between different process.
	// Each path can represent an independent lock file.
	Path string
	// contains filtered or unexported fields
}

Lockfile is a Linux signal file to implement cross-process locks. The file content does not contain anything, it will be always overwritten.

The Lockfile should be used in different process, it cannot be used as a mutex lock in a single process. If you use it in a single process, the Lock and TryLock will always success.

If the process crashed, all its Lockfile will be released automatically, you donot need to handle the deadlock situation.

func New

func New(path string) *Lockfile

New creates a new Lockfile.

func (*Lockfile) Lock

func (lf *Lockfile) Lock() error

Lock blocks until the lock is acquired successfully.

func (*Lockfile) TryLock

func (lf *Lockfile) TryLock() error

TryLock tries to acquire the lock. If the current process successful acquire the lock, this will return nil. If the lock is busy, this will return ErrBusy. In this case, you should do some retries.

func (*Lockfile) Unlock

func (lf *Lockfile) Unlock() error

Unlock actively releases the lock.

You donot need to call this if your lock works on the whole process, because the lock will be automatic released by Linux after process ends. This method only needs to be called if you want to release the lock before process ends.

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