lockfile

Documentation

Index

• type LastWrite
• type LockFile
  • func GetLockFile(path string) (*LockFile, error)
  • func GetROLockFile(path string) (*LockFile, error)
  • func (l *LockFile) AssertLocked()
  • func (l *LockFile) AssertLockedForWriting()
  • func (l *LockFile) GetLastWrite() (LastWrite, error)
  • func (l *LockFile) IsReadWrite() bool
  • func (l *LockFile) Lock()
  • func (l *LockFile) Modified() (bool, error)
  • func (l *LockFile) ModifiedSince(previous LastWrite) (LastWrite, bool, error)
  • func (l *LockFile) RLock()
  • func (l *LockFile) RecordWrite() (LastWrite, error)
  • func (l *LockFile) Touch() error
  • func (l *LockFile) TouchedSince(when time.Time) bool
  • func (l *LockFile) Unlock()
• type Locker
  • func GetLockfile(path string) (Locker, error)
  • func GetROLockfile(path string) (Locker, error)

Types

type LastWrite

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

LastWrite is an opaque identifier of the last write to some *LockFile. It can be used by users of a *LockFile to determine if the lock indicates changes since the last check.

Never construct a LastWrite manually; only accept it from *LockFile methods, and pass it back.

type LockFile

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

LockFile represents a file lock where the file is used to cache an identifier of the last party that made changes to whatever's being protected by the lock.

It MUST NOT be created manually. Use GetLockFile or GetROLockFile instead.

func GetLockFile

func GetLockFile(path string) (*LockFile, error)

GetLockFile opens a read-write lock file, creating it if necessary. The *LockFile object may already be locked if the path has already been requested by the current process.

func GetROLockFile

func GetROLockFile(path string) (*LockFile, error)

GetROLockFile opens a read-only lock file, creating it if necessary. The *LockFile object may already be locked if the path has already been requested by the current process.

func (*LockFile) AssertLocked

func (l *LockFile) AssertLocked()

func (*LockFile) AssertLockedForWriting

func (l *LockFile) AssertLockedForWriting()

func (*LockFile) GetLastWrite

func (l *LockFile) GetLastWrite() (LastWrite, error)

GetLastWrite returns a LastWrite value corresponding to current state of the lock. This is typically called before (_not after_) loading the state when initializing a consumer of the data protected by the lock. During the lifetime of the consumer, the consumer should usually call ModifiedSince instead.

The caller must hold the lock (for reading or writing).

func (*LockFile) IsReadWrite

func (l *LockFile) IsReadWrite() bool

IsReadWrite indicates if the lock file is a read-write lock.

func (*LockFile) Lock

func (l *LockFile) Lock()

Lock locks the lockfile as a writer. Panic if the lock is a read-only one.

func (*LockFile) Modified

func (l *LockFile) Modified() (bool, error)

Modified indicates if the lockfile has been updated since the last time it was loaded. NOTE: Unlike ModifiedSince, this returns true the first time it is called on a *LockFile. Callers cannot, in general, rely on this, because that might have happened for some other owner of the same *LockFile who created it previously.

Deprecated: Use *LockFile.ModifiedSince.

func (*LockFile) ModifiedSince

func (l *LockFile) ModifiedSince(previous LastWrite) (LastWrite, bool, error)

ModifiedSince checks if the lock has been changed since a provided LastWrite value, and returns the one to record instead.

If ModifiedSince reports no modification, the previous LastWrite value is still valid and can continue to be used.

If this function fails, the LastWriter value of the lock is indeterminate; the caller should fail and keep using the previously-recorded LastWrite value, so that it continues failing until the situation is resolved. Similarly, it should only update the recorded LastWrite value after processing the update:

lw2, modified, err := state.lock.ModifiedSince(state.lastWrite)
if err != nil { /* fail */ }
state.lastWrite = lw2
if modified {
	if err := reload(); err != nil { /* fail */ }
	state.lastWrite = lw2
}

The caller must hold the lock (for reading or writing).

func (*LockFile) RLock

func (l *LockFile) RLock()

LockRead locks the lockfile as a reader.

func (*LockFile) RecordWrite

func (l *LockFile) RecordWrite() (LastWrite, error)

RecordWrite updates the lock with a new LastWrite value, and returns the new value.

If this function fails, the LastWriter value of the lock is indeterminate; the caller should keep using the previously-recorded LastWrite value, and possibly detecting its own modification as an external one:

lw, err := state.lock.RecordWrite()
if err != nil { /* fail */ }
state.lastWrite = lw

The caller must hold the lock for writing.

func (*LockFile) Touch

func (l *LockFile) Touch() error

Touch updates the lock file with to record that the current lock holder has modified the lock-protected data.

Deprecated: Use *LockFile.RecordWrite.

func (*LockFile) TouchedSince

func (l *LockFile) TouchedSince(when time.Time) bool

TouchedSince indicates if the lock file has been touched since the specified time

func (*LockFile) Unlock

func (l *LockFile) Unlock()

Unlock unlocks the lockfile.

type Locker

type Locker interface {
	// Acquire a writer lock.
	// The default unix implementation panics if:
	// - opening the lockfile failed
	// - tried to lock a read-only lock-file
	Lock()

	// Unlock the lock.
	// The default unix implementation panics if:
	// - unlocking an unlocked lock
	// - if the lock counter is corrupted
	Unlock()

	// Acquire a reader lock.
	RLock()

	// Touch records, for others sharing the lock, that the caller was the
	// last writer.  It should only be called with the lock held.
	//
	// Deprecated: Use *LockFile.RecordWrite.
	Touch() error

	// Modified() checks if the most recent writer was a party other than the
	// last recorded writer.  It should only be called with the lock held.
	// Deprecated: Use *LockFile.ModifiedSince.
	Modified() (bool, error)

	// TouchedSince() checks if the most recent writer modified the file (likely using Touch()) after the specified time.
	TouchedSince(when time.Time) bool

	// IsReadWrite() checks if the lock file is read-write
	IsReadWrite() bool

	// AssertLocked() can be used by callers that _know_ that they hold the lock (for reading or writing), for sanity checking.
	// It might do nothing at all, or it may panic if the caller is not the owner of this lock.
	AssertLocked()

	// AssertLockedForWriting() can be used by callers that _know_ that they hold the lock locked for writing, for sanity checking.
	// It might do nothing at all, or it may panic if the caller is not the owner of this lock for writing.
	AssertLockedForWriting()
}

A Locker represents a file lock where the file is used to cache an identifier of the last party that made changes to whatever's being protected by the lock.

Deprecated: Refer directly to *LockFile, the provided implementation, instead.

func GetLockfile

func GetLockfile(path string) (Locker, error)

GetLockfile opens a read-write lock file, creating it if necessary. The Locker object may already be locked if the path has already been requested by the current process.

Deprecated: Use GetLockFile

func GetROLockfile

func GetROLockfile(path string) (Locker, error)

GetROLockfile opens a read-only lock file, creating it if necessary. The Locker object may already be locked if the path has already been requested by the current process.

Deprecated: Use GetROLockFile