redislock

README

Redislock

Redislock provides a gredis-based distributed mutual exclusion lock implementation for Go

Installation

Install Redislock using the go get command:

$ go get github.com/jxo-me/redislock

Two driver implementations will be installed; however, only the one used will be included in your project.

• GRedis

See the examples folder for usage of each driver.

Usage

Error handling is simplified to panic for shorter example.

package main

import (
	"context"
	glib "github.com/gogf/gf/v2/database/gredis"
	"github.com/jxo-me/redislock"
	"github.com/jxo-me/redislock/redis/gredis"
)

func main() {
	// Create a pool with gredis which is the pool redislock will
	// use while communicating with Redis. This can also be any pool that
	// implements the `redis.Pool` interface.
	c := &glib.Config{
		Address: "127.0.0.1:6379",
	}
	ctx := context.Background()
	r, err := glib.New(c)
	if err != nil {
		panic(err)
	}
	defer r.Close(ctx)

	// Create an instance of redislock to be used to obtain a mutual exclusion
	// lock.
	rs := redislock.New(gredis.NewPool(r))
	mutex := rs.NewMutex("test-redisLock")

	// Obtain a lock for our given mutex. After this is successful, no one else
	// can obtain the same lock (the same mutex name) until we unlock it.
	if err := mutex.Lock(); err != nil {
		panic(err)
	}
	// Do your work that requires the lock.

	// Release the lock so other processes or threads can obtain a lock.
	if _, err := mutex.Unlock(); err != nil {
		panic(err)
	}
}

Contributing

Contributions are welcome.

Documentation

Index

• Variables
• type DelayFunc
• type ErrNodeTaken
  • func (err ErrNodeTaken) Error() string
• type ErrTaken
  • func (err ErrTaken) Error() string
• type Lock
  • func New(pools ...redis.Pool) *Lock
  • func (r *Lock) NewMutex(name string, options ...Option) *Mutex
• type Mutex
  • func (m *Mutex) Extend() (bool, error)
  • func (m *Mutex) ExtendContext(ctx context.Context) (bool, error)
  • func (m *Mutex) Lock() error
  • func (m *Mutex) LockContext(ctx context.Context) error
  • func (m *Mutex) Name() string
  • func (m *Mutex) Unlock() (bool, error)
  • func (m *Mutex) UnlockContext(ctx context.Context) (bool, error)
  • func (m *Mutex) Until() time.Time
  • func (m *Mutex) Valid() (bool, error)
  • func (m *Mutex) ValidContext(ctx context.Context) (bool, error)
  • func (m *Mutex) Value() string
• type Option
  • func WithDriftFactor(factor float64) Option
  • func WithExpiry(expiry time.Duration) Option
  • func WithGenValueFunc(genValueFunc func() (string, error)) Option
  • func WithRetryDelay(delay time.Duration) Option
  • func WithRetryDelayFunc(delayFunc DelayFunc) Option
  • func WithTimeoutFactor(factor float64) Option
  • func WithTries(tries int) Option
  • func WithValue(v string) Option
• type OptionFunc
  • func (f OptionFunc) Apply(mutex *Mutex)
• type RedisError
  • func (err RedisError) Error() string

Variables

var ErrExtendFailed = errors.New("redislock: failed to extend lock")

ErrExtendFailed is the error resulting if Redsync fails to extend the lock.

var ErrFailed = errors.New("redislock: failed to acquire lock")

ErrFailed is the error resulting if Redsync fails to acquire the lock after exhausting all retries.

Types

type DelayFunc

type DelayFunc func(tries int) time.Duration

A DelayFunc is used to decide the amount of time to wait between retries.

type ErrNodeTaken

type ErrNodeTaken struct {
	Node int
}

ErrNodeTaken is the error resulting if the lock is already taken in one of the cluster's nodes

func (ErrNodeTaken) Error

func (err ErrNodeTaken) Error() string

type ErrTaken

type ErrTaken struct {
	Nodes []int
}

ErrTaken happens when the lock is already taken in a quorum on nodes.

func (ErrTaken) Error

func (err ErrTaken) Error() string

type Lock

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

Lock provides a simple method for creating distributed mutexes using multiple Redis connection pools.

func New

func New(pools ...redis.Pool) *Lock

New creates and returns a new Lock instance from given Redis connection pools.

func (*Lock) NewMutex

func (r *Lock) NewMutex(name string, options ...Option) *Mutex

NewMutex returns a new distributed mutex with given name.

type Mutex

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

A Mutex is a distributed mutual exclusion lock.

func (*Mutex) Extend

func (m *Mutex) Extend() (bool, error)

Extend resets the mutex's expiry and returns the status of expiry extension.

func (*Mutex) ExtendContext

func (m *Mutex) ExtendContext(ctx context.Context) (bool, error)

ExtendContext resets the mutex's expiry and returns the status of expiry extension.

func (*Mutex) Lock

func (m *Mutex) Lock() error

Lock locks m. In case it returns an error on failure, you may retry to acquire the lock by calling this method again.

func (*Mutex) LockContext

func (m *Mutex) LockContext(ctx context.Context) error

LockContext locks m. In case it returns an error on failure, you may retry to acquire the lock by calling this method again.

func (*Mutex) Name

func (m *Mutex) Name() string

Name returns mutex name (i.e. the Redis key).

func (*Mutex) Unlock

func (m *Mutex) Unlock() (bool, error)

Unlock unlocks m and returns the status of unlock.

func (*Mutex) UnlockContext

func (m *Mutex) UnlockContext(ctx context.Context) (bool, error)

UnlockContext unlocks m and returns the status of unlock.

func (*Mutex) Until

func (m *Mutex) Until() time.Time

Until returns the time of validity of acquired lock. The value will be zero value until a lock is acquired.

func (*Mutex) Valid

func (m *Mutex) Valid() (bool, error)

Valid returns true if the lock acquired through m is still valid. It may also return true erroneously if quorum is achieved during the call and at least one node then takes long enough to respond for the lock to expire.

func (*Mutex) ValidContext

func (m *Mutex) ValidContext(ctx context.Context) (bool, error)

ValidContext returns true if the lock acquired through m is still valid. It may also return true erroneously if quorum is achieved during the call and at least one node then takes long enough to respond for the lock to expire.

func (*Mutex) Value

func (m *Mutex) Value() string

Value returns the current random value. The value will be empty until a lock is acquired (or WithValue option is used).

type Option

type Option interface {
	Apply(*Mutex)
}

An Option configures a mutex.

func WithDriftFactor

func WithDriftFactor(factor float64) Option

WithDriftFactor can be used to set the clock drift factor.

func WithExpiry

func WithExpiry(expiry time.Duration) Option

WithExpiry can be used to set the expiry of a mutex to the given value.

func WithGenValueFunc

func WithGenValueFunc(genValueFunc func() (string, error)) Option

WithGenValueFunc can be used to set the custom value generator.

func WithRetryDelay

func WithRetryDelay(delay time.Duration) Option

WithRetryDelay can be used to set the amount of time to wait between retries.

func WithRetryDelayFunc

func WithRetryDelayFunc(delayFunc DelayFunc) Option

WithRetryDelayFunc can be used to override default delay behavior.

func WithTimeoutFactor

func WithTimeoutFactor(factor float64) Option

WithTimeoutFactor can be used to set the timeout factor.

func WithTries

func WithTries(tries int) Option

WithTries can be used to set the number of times lock acquire is attempted.

func WithValue

func WithValue(v string) Option

WithValue can be used to assign the random value without having to call lock. This allows the ownership of a lock to be "transferred" and allows the lock to be unlocked from elsewhere.

type OptionFunc

type OptionFunc func(*Mutex)

OptionFunc is a function that configures a mutex.

func (OptionFunc) Apply

func (f OptionFunc) Apply(mutex *Mutex)

Apply calls f(mutex)

type RedisError

type RedisError struct {
	Node int
	Err  error
}

A RedisError is an error communicating with one of the Redis nodes.

func (RedisError) Error

func (err RedisError) Error() string