store

func Lock ¶

func Lock(ctx context.Context, f OSFile) error

Lock acquires (or promotes an already acquired lock to) an exclusive lock, i.e. a lock used for writing, on the specified file.

Lock is not re-entrant. Calling Lock on an exclusive lock is a no-op.

NOTE: On Windows, Lock always releases any lock that was previously held when called. This means that callers must not assume that the lock is still held if Lock returns with an error.

f, err := os.Open("/tmp")
if err != nil {
	log.Fatal(err)
}
defer f.Close()

// Acquire an exclusive lock
if err := store.Lock(context.Background(), f); err != nil {
	log.Fatal(err)
}

if err := store.Unlock(f); err != nil {
	log.Fatal(err)
}

// Closing the underlying file also releases the lock.
if err := f.Close(); err != nil {
	log.Fatal(err)
}

Output:

// Open and exclusive-lock /tmp
f, err := os.Open("/tmp")
if err != nil {
	log.Fatal(err)
}
defer f.Close()

if err := store.Lock(context.Background(), f); err != nil {
	log.Fatal(err)
}

ctx, cancel := context.WithCancel(context.Background())

// Try to do the same in a goroutine
done := make(chan struct{})
go func() {
	defer close(done)

	f, err := os.Open("/tmp")
	if err != nil {
		log.Fatal(err)
	}
	defer f.Close()

	// This hangs until the context cancels
	err = store.Lock(ctx, f)
	if err != nil {
		log.Print(err)
	} else {
		log.Fatal("should not have succeeded locking")
	}
}()

// Cancel the context to abort the Lock operation
cancel()
<-done

Output:

func RLock ¶

func RLock(ctx context.Context, f OSFile) error

RLock acquires (or demotes an already acquired lock to) a shared lock, i.e. a lock used for reading, on the specified file.

RLock is not re-entrant. Calling RLock on a shared lock is a no-op.

NOTE: On Windows, RLock always releases any lock that was previously held when called. This means that callers must not assume that the lock is still held if RLock returns with an error.

func TryLock ¶

func TryLock(f OSFile) error

TryLock attempts to acquire (or promote an already acquired lock to) an exclusive lock, i.e. a lock used for writing, on the specified file.

If the attempt would block, TryLock returns an error wrapping ErrWouldBlock.

NOTE: On Windows, TryLock always releases any lock that was previously held when called. This means that callers must not assume that the lock is still held if TryLock returns with an error.

func TryRLock ¶

func TryRLock(f OSFile) error

TryRLock attempts to acquire (or demote an already acquired lock to) a shared lock, i.e. a lock used for reading.

If the attempt would block, TryRLock returns an error wrapping ErrWouldBlock.

NOTE: On Windows, TryRLock always releases any lock that was previously held when called. This means that callers must not assume that the lock is still held if TryRLock returns with an error.

func Unlock ¶

func Unlock(f OSFile) error

Unlock releases the lock on the specified file.

Note that in almost all scenarios, closing the file is better. This is because if the underlying file handle has been duplicated (say, via dup(2) on Unix-like systems), then calling Unlock will release the underlying lock for _all_ of these file descriptors, whereas closing the file ensures that the lock gets released automatically once all file descriptors are closed.