README
¶
Redsync
Redsync provides a Redis-based distributed mutual exclusion lock implementation for Go as described in this post. A reference library (by antirez) for Ruby is available at github.com/antirez/redlock-rb.
Installation
Install Redsync using the go get command:
$ go get github.com/go-redsync/redsync/v4
Two driver implementations will be installed; however, only the one used will be included in your project.
See the examples folder for usage of each driver.
Documentation
Usage
Error handling is simplified to panic for shorter example.
package main
import (
goredislib "github.com/redis/go-redis/v9"
"github.com/go-redsync/redsync/v4"
"github.com/go-redsync/redsync/v4/redis/goredis/v9"
)
func main() {
// Create a pool with go-redis (or redigo) which is the pool redisync will
// use while communicating with Redis. This can also be any pool that
// implements the `redis.Pool` interface.
client := goredislib.NewClient(&goredislib.Options{
Addr: "localhost:6379",
})
pool := goredis.NewPool(client) // or, pool := redigo.NewPool(...)
// Create an instance of redisync to be used to obtain a mutual exclusion
// lock.
rs := redsync.New(pool)
// Obtain a new mutex by using the same name for all instances wanting the
// same lock.
mutexname := "my-global-mutex"
mutex := rs.NewMutex(mutexname)
// 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 ok, err := mutex.Unlock(); !ok || err != nil {
panic("unlock failed")
}
}
Contributing
Contributions are welcome.
License
Redsync is available under the BSD (3-Clause) License.
Disclaimer
This code implements an algorithm which is currently a proposal, it was not formally analyzed. Make sure to understand how it works before using it in production environments.
Real World Uses
Below is a list of public, open source projects that use Redsync:
- Sourcegraph: Universal code search and intelligence platform. Uses Redsync in an internal cache implementation.
- Open Match by Google: Flexible, extensible, and scalable video game matchmaking. Uses Redsync with its state store implementation.
- Gocron by go-co-op: gocron is a job distributed scheduling package which lets you run Go functions at pre-determined intervals using a simple, human-friendly syntax. Uses Redsync with its distributed job scheduler implementation.
If you are using Redsync in a project please send a pull request to add it to the list.
Documentation
¶
Overview ¶
Package redsync provides a Redis-based distributed mutual exclusion lock implementation as described in the post http://redis.io/topics/distlock.
Values containing the types defined in this package should not be copied.
Index ¶
- Variables
- type DelayFunc
- type ErrNodeTaken
- type ErrTaken
- 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) TryLock() error
- func (m *Mutex) TryLockContext(ctx context.Context) error
- 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)deprecated
- func (m *Mutex) ValidContext(ctx context.Context) (bool, error)deprecated
- func (m *Mutex) Value() string
- type Option
- func WithDriftFactor(factor float64) Option
- func WithExpiry(expiry time.Duration) Option
- func WithFailFast(b bool) Option
- func WithGenValueFunc(genValueFunc func() (string, error)) Option
- func WithRetryDelay(delay time.Duration) Option
- func WithRetryDelayFunc(delayFunc DelayFunc) Option
- func WithSetNXOnExtend() Option
- func WithShufflePools(b bool) Option
- func WithTimeoutFactor(factor float64) Option
- func WithTries(tries int) Option
- func WithValue(v string) Option
- type OptionFunc
- type RedisError
- type Redsync
Constants ¶
This section is empty.
Variables ¶
var ErrExtendFailed = errors.New("redsync: failed to extend lock")
ErrExtendFailed is the error resulting if Redsync fails to extend the lock.
var ErrFailed = errors.New("redsync: failed to acquire lock")
ErrFailed is the error resulting if Redsync fails to acquire the lock after exhausting all retries.
var ErrLockAlreadyExpired = errors.New("redsync: failed to unlock, lock was already expired")
ErrLockAlreadyExpired is the error resulting if trying to unlock the lock which already expired.
Functions ¶
This section is empty.
Types ¶
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.
type Mutex ¶
type Mutex struct {
// contains filtered or unexported fields
}
A Mutex is a distributed mutual exclusion lock.
func (*Mutex) ExtendContext ¶
ExtendContext resets the mutex's expiry and returns the status of expiry extension.
func (*Mutex) Lock ¶
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 ¶
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) TryLock ¶
TryLock only attempts to lock m once and returns immediately regardless of success or failure without retrying.
func (*Mutex) TryLockContext ¶
TryLockContext only attempts to lock m once and returns immediately regardless of success or failure without retrying.
func (*Mutex) UnlockContext ¶
UnlockContext unlocks m and returns the status of unlock.
func (*Mutex) Until ¶
Until returns the time of validity of acquired lock. The value will be zero value until a lock is acquired.
func (*Mutex) Valid
deprecated
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.
Deprecated: Use Until instead. See https://github.com/go-redsync/redsync/issues/72.
func (*Mutex) ValidContext
deprecated
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.
Deprecated: Use Until instead. See https://github.com/go-redsync/redsync/issues/72.
type Option ¶
type Option interface {
Apply(*Mutex)
}
An Option configures a mutex.
func WithDriftFactor ¶
WithDriftFactor can be used to set the clock drift factor. The default value is 0.01.
func WithExpiry ¶
WithExpiry can be used to set the expiry of a mutex to the given value. The default is 8s.
func WithFailFast ¶
WithFailFast can be used to quickly acquire and release the lock. When some Redis servers are blocking, we do not need to wait for responses from all the Redis servers response. As long as the quorum is met, we can assume the lock is acquired. The effect of this parameter is to achieve low latency, avoid Redis blocking causing Lock/Unlock to not return for a long time.
func WithGenValueFunc ¶
WithGenValueFunc can be used to set the custom value generator.
func WithRetryDelay ¶
WithRetryDelay can be used to set the amount of time to wait between retries. The default value is rand(50ms, 250ms).
func WithRetryDelayFunc ¶
WithRetryDelayFunc can be used to override default delay behavior.
func WithSetNXOnExtend ¶
func WithSetNXOnExtend() Option
WithSetNXOnExtend improves extending logic to extend the key if exist and if not, tries to set a new key in redis Useful if your redises restart often and you want to reduce the chances of losing the lock Read this MR for more info: https://github.com/go-redsync/redsync/pull/149
func WithShufflePools ¶
WithShufflePools can be used to shuffle Redis pools to reduce centralized access in concurrent scenarios.
func WithTimeoutFactor ¶
WithTimeoutFactor can be used to set the timeout factor. The default value is 0.05.
type RedisError ¶
A RedisError is an error communicating with one of the Redis nodes.
func (RedisError) Error ¶
func (err RedisError) Error() string
Source Files
Directories