distlock

Documentation

Overview

Package distlock provides access to distributed locking mechanisms for the purpose of locking resources across a distributed system. Locker provides the standard interface for locking. To use a specific lock service, you must import a locking implementation from a subdirectory. Note: If faking the interfaces here, you MUST embed the interface in your fakes. Otherwise future changes will break your code.

Index

• Variables
• func Register(namespace string, entry RegEntry) error
• type Cancel
• type Handler
• type Info
  • func (i Info) IsZero() bool
• type Infoer
• type Lock
• type LockOption
  • func TTL(d time.Duration) LockOption
• type LockOptions
• type Locker
  • func New() (Locker, error)
• type Reader
• type RegEntry
• type Releaser
• type UnlockOption
• type UnlockOptions
• type Watcher

Variables

var (
	LockAcquireTimeoutErr = fmt.Errorf("Timeout trying to acquire lock")
)

Functions

func Register

func Register(namespace string, entry RegEntry) error

Register registers a Locker for a namespace. A namespace must be: [a-z_]*://, like etcd:// .

Types

type Cancel

type Cancel func()

Cancel cancels a background function.

type Handler

type Handler interface {
	// Lock locks a resource at service location. Implementations will receive
	// the service without the namespace (whatever://).
	TryLock(ctx context.Context, service, resource string, options ...LockOption) (Lock, error)
	// Unlock unlocks a resource at service location.  Implemntations will receive
	// the service without the namespace (whatever://).
	Release(ctx context.Context, service, resource string, options ...UnlockOption) error
}

Handler provides for locking and unlocking resources.

type Info

type Info struct {
	// LockTime is the time the lock was taken out.
	LockTime time.Time
	// ExpireTime is the time the lock expires if not updated.
	ExpireTime time.Time
	// Owner is the identitiy of who owns the lock.  This is lock type specific.
	Owner interface{}
}

Info provides information about a lock.

func (Info) IsZero

func (i Info) IsZero() bool

IsZero indicates if Info is the zero value.

type Infoer

type Infoer interface {
	// Info returns information about a Lock.
	Info(ctx context.Context, service, resource string) (Info, error)
}

Infoer allows getting information about a lock.

type Lock

type Lock struct {
	// Lost is closed when the lock is lost.
	Lost chan struct{}

	// Release can be called to release a lock.
	Release Releaser
}

Lock provides information and operations for a lock that has been taken out.

type LockOption

type LockOption func(o *LockOptions)

LockOption provides an optional argument for locking a resource.

func TTL

func TTL(d time.Duration) LockOption

TTL sets the minimum time the lock will be held. If set below 5 seconds, will panic.

type LockOptions

type LockOptions struct {
	// TTL is the minimum time to hold the lock. This can be no less than 5 seconds.
	// TTL only counts as a minimum time in case lock renewal fails.  A lock
	// can expire imediately by calling Release() or Unlocker().
	// TTLs have upper limits that can prevent the TTL being set from being implemented.
	TTL time.Duration
}

LockOptions provides options to various Locker implementations. This is not set directly but constructed by using implementations of LockOption.

type Locker

type Locker interface {
	Handler
	Infoer
	Reader
	Watcher
}

Locker provides access to all functions for interfacing with locks. Not all Locker methods may be provided by all implementations. Only Lock()/Unlock() are guaranteed.

func New

func New() (Locker, error)

New constructs a new Locker. The Locker returned can access any Locker registered with this module.

type Reader

type Reader interface {
	// Read reads the data in the lock into i.
	Read(ctx context.Context, service, resource string) ([]byte, error)
}

Reader allows reading data held in a lock, if the lock can hold data.

type RegEntry

type RegEntry struct {
	Locker  Locker
	Infoer  Infoer
	Reader  Reader
	Watcher Watcher
}

RegEntry describes a Locker entry in the internal registry.

type Releaser

type Releaser func(options ...UnlockOption) error

Releaser unlocks a resource.

type UnlockOption

type UnlockOption func(o *LockOptions)

UnlockOption provides an optional argument for unlocking a resource.

type UnlockOptions

type UnlockOptions struct{}

UnlockOptions provides options to various Locker implementations. This is not set directly but constructed by using implementations of UnlockOption.

type Watcher

type Watcher interface {
	Watch(ctx context.Context, service, resource string) (chan []byte, Cancel, error)
}

Watcher watches the content held in a lock and returns the content whenever it changes. Watch will return immediately any content in the lock.