lock

Documentation

Index

• type FileLock
  • func (l *FileLock) Free() error
  • func (l *FileLock) ID() uint32
  • func (l *FileLock) Lock()
  • func (l *FileLock) Unlock()
• type FileLockManager
  • func (m *FileLockManager) AllocateAndRetrieveLock(id uint32) (Locker, error)
  • func (m *FileLockManager) AllocateLock() (Locker, error)
  • func (m *FileLockManager) AvailableLocks() (*uint32, error)
  • func (m *FileLockManager) FreeAllLocks() error
  • func (m *FileLockManager) LocksHeld() ([]uint32, error)
  • func (m *FileLockManager) RetrieveLock(id uint32) (Locker, error)
• type InMemoryManager
  • func (m *InMemoryManager) AllocateAndRetrieveLock(id uint32) (Locker, error)
  • func (m *InMemoryManager) AllocateLock() (Locker, error)
  • func (m *InMemoryManager) AvailableLocks() (*uint32, error)
  • func (m *InMemoryManager) FreeAllLocks() error
  • func (m *InMemoryManager) LocksHeld() ([]uint32, error)
  • func (m *InMemoryManager) RetrieveLock(id uint32) (Locker, error)
• type Locker
• type Manager
  • func NewFileLockManager(lockPath string) (Manager, error)
  • func NewInMemoryManager(numLocks uint32) (Manager, error)
  • func NewSHMLockManager(path string, numLocks uint32) (Manager, error)
  • func OpenFileLockManager(path string) (Manager, error)
  • func OpenSHMLockManager(path string, numLocks uint32) (Manager, error)
• type Mutex
  • func (m *Mutex) Free() error
  • func (m *Mutex) ID() uint32
  • func (m *Mutex) Lock()
  • func (m *Mutex) Unlock()
• type SHMLock
  • func (l *SHMLock) Free() error
  • func (l *SHMLock) ID() uint32
  • func (l *SHMLock) Lock()
  • func (l *SHMLock) Unlock()
• type SHMLockManager
  • func (m *SHMLockManager) AllocateAndRetrieveLock(id uint32) (Locker, error)
  • func (m *SHMLockManager) AllocateLock() (Locker, error)
  • func (m *SHMLockManager) AvailableLocks() (*uint32, error)
  • func (m *SHMLockManager) FreeAllLocks() error
  • func (m *SHMLockManager) LocksHeld() ([]uint32, error)
  • func (m *SHMLockManager) RetrieveLock(id uint32) (Locker, error)

Types

type FileLock

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

FileLock is an individual shared memory lock.

func (*FileLock) Free

func (l *FileLock) Free() error

Free releases the lock, allowing it to be reused.

func (*FileLock) ID

func (l *FileLock) ID() uint32

ID returns the ID of the lock.

func (*FileLock) Lock

func (l *FileLock) Lock()

Lock acquires the lock.

func (*FileLock) Unlock

func (l *FileLock) Unlock()

Unlock releases the lock.

type FileLockManager

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

FileLockManager manages shared memory locks.

func (*FileLockManager) AllocateAndRetrieveLock

func (m *FileLockManager) AllocateAndRetrieveLock(id uint32) (Locker, error)

AllocateAndRetrieveLock allocates the lock with the given ID and returns it. If the lock is already allocated, error.

func (*FileLockManager) AllocateLock

func (m *FileLockManager) AllocateLock() (Locker, error)

AllocateLock allocates a new lock from the manager.

func (*FileLockManager) AvailableLocks

func (m *FileLockManager) AvailableLocks() (*uint32, error)

AvailableLocks returns the number of available locks. Since this is not limited in the file lock implementation, nil is returned.

func (*FileLockManager) FreeAllLocks

func (m *FileLockManager) FreeAllLocks() error

FreeAllLocks frees all locks in the manager. This function is DANGEROUS. Please read the full comment in locks.go before trying to use it.

func (*FileLockManager) LocksHeld

func (m *FileLockManager) LocksHeld() ([]uint32, error)

LocksHeld returns any locks that are presently locked. It is not implemented for the file lock backend. It ought to be possible, but my motivation to dig into c/storage and add trylock semantics to the filelocker implementation for an uncommonly-used lock backend is lacking.

func (*FileLockManager) RetrieveLock

func (m *FileLockManager) RetrieveLock(id uint32) (Locker, error)

RetrieveLock retrieves a lock from the manager given its ID.

type InMemoryManager

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

InMemoryManager is a lock manager that allocates and retrieves local-only locks - that is, they are not multiprocess. This lock manager is intended purely for unit and integration testing and should not be used in production deployments.

func (*InMemoryManager) AllocateAndRetrieveLock

func (m *InMemoryManager) AllocateAndRetrieveLock(id uint32) (Locker, error)

AllocateAndRetrieveLock allocates a lock with the given ID (if not already in use) and returns it.

func (*InMemoryManager) AllocateLock

func (m *InMemoryManager) AllocateLock() (Locker, error)

AllocateLock allocates a lock from the manager.

func (*InMemoryManager) AvailableLocks

func (m *InMemoryManager) AvailableLocks() (*uint32, error)

Get number of available locks

func (*InMemoryManager) FreeAllLocks

func (m *InMemoryManager) FreeAllLocks() error

FreeAllLocks frees all locks. This function is DANGEROUS. Please read the full comment in locks.go before trying to use it.

func (*InMemoryManager) LocksHeld

func (m *InMemoryManager) LocksHeld() ([]uint32, error)

Get any locks that are presently being held. Useful for debugging deadlocks.

func (*InMemoryManager) RetrieveLock

func (m *InMemoryManager) RetrieveLock(id uint32) (Locker, error)

RetrieveLock retrieves a lock from the manager.

type Locker

type Locker interface {
	// ID retrieves the lock's ID.
	// ID is guaranteed to uniquely identify the lock within the
	// Manager - that is, calling RetrieveLock with this ID will return
	// another instance of the same lock.
	ID() uint32
	// Lock locks the lock.
	// This call MUST block until it successfully acquires the lock or
	// encounters a fatal error.
	// All errors must be handled internally, as they are not returned. For
	// the most part, panicking should be appropriate.
	// Some lock implementations may require that Lock() and Unlock() occur
	// within the same goroutine (SHM locking, for example). The usual Go
	// Lock()/defer Unlock() pattern will still work fine in these cases.
	Lock()
	// Unlock unlocks the lock.
	// All errors must be handled internally, as they are not returned. For
	// the most part, panicking should be appropriate.
	// This includes unlocking locks which are already unlocked.
	Unlock()
	// Free deallocates the underlying lock, allowing its reuse by other
	// pods and containers.
	// The lock MUST still be usable after a Free() - some libpod instances
	// may still retain Container structs with the old lock. This simply
	// advises the manager that the lock may be reallocated.
	Free() error
}

Locker is similar to sync.Locker, but provides a method for freeing the lock to allow its reuse. All Locker implementations must maintain mutex semantics - the lock only allows one caller in the critical section at a time. All locks with the same ID must refer to the same underlying lock, even if they are within multiple processes.

type Manager

type Manager interface {
	// AllocateLock returns an unallocated lock.
	// It is guaranteed that the same lock will not be returned again by
	// AllocateLock until the returned lock has Free() called on it.
	// If all available locks are allocated, AllocateLock will return an
	// error.
	AllocateLock() (Locker, error)
	// RetrieveLock retrieves a lock given its UUID.
	// The underlying lock MUST be the same as another other lock with the
	// same UUID.
	RetrieveLock(id uint32) (Locker, error)
	// AllocateAndRetrieveLock marks the lock with the given UUID as in use
	// and retrieves it.
	// RetrieveAndAllocateLock will error if the lock in question has
	// already been allocated.
	// This is mostly used after a system restart to repopulate the list of
	// locks in use.
	AllocateAndRetrieveLock(id uint32) (Locker, error)
	// PLEASE READ FULL DESCRIPTION BEFORE USING.
	// FreeAllLocks frees all allocated locks, in preparation for lock
	// reallocation.
	// As this deallocates all presently-held locks, this can be very
	// dangerous - if there are other processes running that might be
	// attempting to allocate new locks and free existing locks, we may
	// encounter races leading to an inconsistent state.
	// (This is in addition to the fact that FreeAllLocks instantly makes
	// the state inconsistent simply by using it, and requires a full
	// lock renumbering to restore consistency!).
	// In short, this should only be used as part of unit tests, or lock
	// renumbering, where reasonable guarantees about other processes can be
	// made.
	FreeAllLocks() error
	// NumAvailableLocks gets the number of remaining locks available to be
	// allocated.
	// Some lock managers do not have a maximum number of locks, and can
	// allocate an unlimited number. These implementations should return
	// a nil uin32.
	AvailableLocks() (*uint32, error)
	// Get a list of locks that are currently locked.
	// This may not be supported by some drivers, depending on the exact
	// backend implementation in use.
	LocksHeld() ([]uint32, error)
}

Manager provides an interface for allocating multiprocess locks. Locks returned by Manager MUST be multiprocess - allocating a lock in process A and retrieving that lock's ID in process B must return handles for the same lock, and locking the lock in A should exclude B from the lock until it is unlocked in A. All locks must be identified by a UUID (retrieved with Locker's ID() method). All locks with a given UUID must refer to the same underlying lock, and it must be possible to retrieve the lock given its UUID. Each UUID should refer to a unique underlying lock. Calls to AllocateLock() must return a unique, unallocated UUID. AllocateLock() must fail once all available locks have been allocated. Locks are returned to use by calls to Free(), and can subsequently be reallocated.

func NewFileLockManager

func NewFileLockManager(lockPath string) (Manager, error)

NewFileLockManager makes a new FileLockManager at the specified directory.

func NewInMemoryManager

func NewInMemoryManager(numLocks uint32) (Manager, error)

NewInMemoryManager creates a new in-memory lock manager with the given number of locks.

func NewSHMLockManager

func NewSHMLockManager(path string, numLocks uint32) (Manager, error)

NewSHMLockManager makes a new SHMLockManager with the given number of locks. Due to the underlying implementation, the exact number of locks created may be greater than the number given here.

func OpenFileLockManager

func OpenFileLockManager(path string) (Manager, error)

OpenFileLockManager opens an existing FileLockManager at the specified directory.

func OpenSHMLockManager

func OpenSHMLockManager(path string, numLocks uint32) (Manager, error)

OpenSHMLockManager opens an existing SHMLockManager with the given number of locks.

type Mutex

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

Mutex holds a single mutex and whether it has been allocated.

func (*Mutex) Free

func (m *Mutex) Free() error

Free deallocates the mutex to allow its reuse

func (*Mutex) ID

func (m *Mutex) ID() uint32

ID retrieves the ID of the mutex

func (*Mutex) Lock

func (m *Mutex) Lock()

Lock locks the mutex

func (*Mutex) Unlock

func (m *Mutex) Unlock()

Unlock unlocks the mutex

type SHMLock

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

SHMLock is an individual shared memory lock.

func (*SHMLock) Free

func (l *SHMLock) Free() error

Free releases the lock, allowing it to be reused.

func (*SHMLock) ID

func (l *SHMLock) ID() uint32

ID returns the ID of the lock.

func (*SHMLock) Lock

func (l *SHMLock) Lock()

Lock acquires the lock.

func (*SHMLock) Unlock

func (l *SHMLock) Unlock()

Unlock releases the lock.

type SHMLockManager

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

SHMLockManager manages shared memory locks.

func (*SHMLockManager) AllocateAndRetrieveLock

func (m *SHMLockManager) AllocateAndRetrieveLock(id uint32) (Locker, error)

AllocateAndRetrieveLock allocates the lock with the given ID and returns it. If the lock is already allocated, error.

func (*SHMLockManager) AllocateLock

func (m *SHMLockManager) AllocateLock() (Locker, error)

AllocateLock allocates a new lock from the manager.

func (*SHMLockManager) AvailableLocks

func (m *SHMLockManager) AvailableLocks() (*uint32, error)

AvailableLocks returns the number of free locks in the manager.

func (*SHMLockManager) FreeAllLocks

func (m *SHMLockManager) FreeAllLocks() error

FreeAllLocks frees all locks in the manager. This function is DANGEROUS. Please read the full comment in locks.go before trying to use it.

func (*SHMLockManager) LocksHeld

func (m *SHMLockManager) LocksHeld() ([]uint32, error)

func (*SHMLockManager) RetrieveLock

func (m *SHMLockManager) RetrieveLock(id uint32) (Locker, error)

RetrieveLock retrieves a lock from the manager given its ID.