lock

Documentation

Overview

Package lock is the API for POSIX-style advisory regional file locks and BSD-style full file locks.

Callers needing to enforce these types of locks, like sys_fcntl, can call LockRegion and UnlockRegion on a thread-safe set of Locks. Locks are specific to a unique file (unique device/inode pair) and for this reason should not be shared between files.

A Lock has a set of holders identified by UniqueID. Normally this is the pid of the thread attempting to acquire the lock.

Since these are advisory locks, they do not need to be integrated into Reads/Writes and for this reason there is no way to *check* if a lock is held. One can only attempt to take a lock or unlock an existing lock.

A Lock in a set of Locks is typed: it is either a read lock with any number of readers and no writer, or a write lock with no readers.

As expected from POSIX, any attempt to acquire a write lock on a file region when there already exits a write lock held by a different uid will fail. Any attempt to acquire a write lock on a file region when there is more than one reader will fail. Any attempt to acquire a read lock on a file region when there is already a writer will fail.

In special cases, a read lock may be upgraded to a write lock and a write lock can be downgraded to a read lock. This can only happen if:

• read lock upgrade to write lock: There can be only one reader and the reader must be the same as the requested write lock holder.

• write lock downgrade to read lock: The writer must be the same as the requested read lock holder.

UnlockRegion always succeeds. If LockRegion fails the caller should normally interpret this as "try again later".

Index

• Constants
• type Blocker
• type Lock
• type LockType
• type Locks
  • func (l *Locks) LockRegion(uid UniqueID, t LockType, r LockRange, block Blocker) bool
  • func (l *Locks) UnlockRegion(uid UniqueID, r LockRange)
• type UniqueID

Constants

const (
	// EventMaskAll is the mask we will always use for locks, by using the
	// same mask all the time we can wake up everyone anytime the lock
	// changes state.
	EventMaskAll waiter.EventMask = 0xFFFF
)

const LockEOF = math.MaxUint64

LockEOF is the maximal possible end of a regional file lock.

Types

type Blocker

type Blocker interface {
	Block(C <-chan struct{}) error
}

Blocker is the interface used for blocking locks. Passing a nil Blocker will be treated as non-blocking.

type Lock

type Lock struct {
	// Readers are the set of read lock holders identified by UniqueID.
	// If len(Readers) > 0 then HasWriter must be false.
	Readers map[UniqueID]bool

	// HasWriter indicates that this is a write lock held by a single
	// UniqueID.
	HasWriter bool

	// Writer is only valid if HasWriter is true.  It identifies a
	// single write lock holder.
	Writer UniqueID
}

Lock is a regional file lock. It consists of either a single writer or a set of readers.

A Lock may be upgraded from a read lock to a write lock only if there is a single reader and that reader has the same uid as the write lock.

A Lock may be downgraded from a write lock to a read lock only if the write lock's uid is the same as the read lock.

+stateify savable

type LockType

type LockType int

LockType is a type of regional file lock.

const (
	// ReadLock describes a POSIX regional file lock to be taken
	// read only.  There may be multiple of these locks on a single
	// file region as long as there is no writer lock on the same
	// region.
	ReadLock LockType = iota

	// WriteLock describes a POSIX regional file lock to be taken
	// write only.  There may be only a single holder of this lock
	// and no read locks.
	WriteLock
)

type Locks

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

Locks is a thread-safe wrapper around a LockSet.

+stateify savable

func (*Locks) LockRegion

func (l *Locks) LockRegion(uid UniqueID, t LockType, r LockRange, block Blocker) bool

LockRegion attempts to acquire a typed lock for the uid on a region of a file. Returns true if successful in locking the region. If false is returned, the caller should normally interpret this as "try again later" if acquiring the lock in a non-blocking mode or "interrupted" if in a blocking mode. Blocker is the interface used to provide blocking behavior, passing a nil Blocker will result in non-blocking behavior.

func (*Locks) UnlockRegion

func (l *Locks) UnlockRegion(uid UniqueID, r LockRange)

UnlockRegion attempts to release a lock for the uid on a region of a file. This operation is always successful, even if there did not exist a lock on the requested region held by uid in the first place.

type UniqueID

type UniqueID uint64

UniqueID is a unique identifier of the holder of a regional file lock.