Redsync

https://pkg.go.dev/github.com/go-redsync/redsync/v4
Admin
Redsync is a Go library that provides a Redis-based distributed mutual exclusion lock implementation...
Tokens:4,523
Snippets:66
Trust Score:9.6
Update:6 months ago
Show doc for...
Tokens:
Raw
### Install Redsync

Source: https://pkg.go.dev/github.com/go-redsync/redsync/v4

Command to install the Redsync package via go get.

```bash
$ go get github.com/go-redsync/redsync/v4
```

--------------------------------

### Implement Distributed Locking

Source: https://pkg.go.dev/github.com/go-redsync/redsync/v4

Example showing how to initialize a Redis pool, create a mutex, and perform lock/unlock operations.

```go
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 redsync 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 redsync 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")
	}
}
```

--------------------------------

### Get Mutex Name

Source: https://pkg.go.dev/github.com/go-redsync/redsync/v4

Retrieves the Redis key associated with the mutex.

```go
func (m *Mutex) Name() string
```

--------------------------------

### Get Mutex Value

Source: https://pkg.go.dev/github.com/go-redsync/redsync/v4

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

```go
func (m *Mutex) Value() string
```

--------------------------------

### Redigo Pool Interface

Source: https://pkg.go.dev/github.com/go-redsync/redsync/v4/redis/redigo

The Pool interface defines the methods required for a Redigo connection pool. It includes Get and GetContext for obtaining connections.

```go
type Pool interface {
	Get() redis.Conn
	GetContext(ctx context.Context) (redis.Conn, error)
}
```

--------------------------------

### Get Mutex Validity Time

Source: https://pkg.go.dev/github.com/go-redsync/redsync/v4

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

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

--------------------------------

### Redsync Initialization

Source: https://pkg.go.dev/github.com/go-redsync/redsync/v4

How to initialize the Redsync instance and create new mutexes.

```APIDOC
## Redsync Initialization

### Description
Initialize the Redsync client with Redis pools and create mutex instances.

### Methods
- **New(pools ...redis.Pool) *Redsync**: Creates a new Redsync instance.
- **NewMutex(name string, options ...Option) *Mutex**: Creates a new mutex with a specific name and optional configurations.
```

--------------------------------

### Create a new pool with NewPool

Source: https://pkg.go.dev/github.com/go-redsync/redsync/v4/redis/valkeygo

Initializes a new pool implementation compatible with redsync using a valkeycompat.Cmdable delegate.

```go
func NewPool(delegate valkeycompat.Cmdable) redsyncredis.Pool
```

--------------------------------

### Initialize New Script Object

Source: https://pkg.go.dev/github.com/go-redsync/redsync/v4/redis

Creates a new Script instance. The keyCount parameter determines how the script count is handled in EVAL commands.

```go
func NewScript(keyCount int, src, hash string) *Script
```

--------------------------------

### Redsync Instance Management

Source: https://pkg.go.dev/github.com/go-redsync/redsync/v4

Methods for initializing the Redsync library and creating new distributed mutexes.

```APIDOC
## func New

### Description
Creates and returns a new Redsync instance from given Redis connection pools.

### Method
Constructor

### Parameters
- **pools** (...redis.Pool) - Required - Redis connection pools to be used by Redsync.

## func (*Redsync) NewMutex

### Description
Returns a new distributed mutex with the given name and optional configurations.

### Method
Method

### Parameters
- **name** (string) - Required - The name of the mutex.
- **options** (...Option) - Optional - Configuration options for the mutex.
```

--------------------------------

### Create New Redsync Instance

Source: https://pkg.go.dev/github.com/go-redsync/redsync/v4

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

```go
func New(pools ...redis.Pool) *Redsync
```

--------------------------------

### Enable SetNX on Extend Option

Source: https://pkg.go.dev/github.com/go-redsync/redsync/v4

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

```go
func WithSetNXOnExtend() Option
```

--------------------------------

### Create Goredis Pool

Source: https://pkg.go.dev/github.com/go-redsync/redsync/v4/redis/goredis/v8

Use NewPool to create a Goredis-based pool implementation for redsync. It requires a delegate redis.UniversalClient.

```go
func NewPool(delegate redis.UniversalClient) redsyncredis.Pool
```

--------------------------------

### Create Redigo Pool Implementation

Source: https://pkg.go.dev/github.com/go-redsync/redsync/v4/redis/redigo

Use NewPool to create a Redigo-based pool. This is useful when integrating redsync with a Redigo client.

```go
func NewPool(delegate Pool) redsyncredis.Pool
```

--------------------------------

### NewPool Function Signature

Source: https://pkg.go.dev/github.com/go-redsync/redsync/v4/redis/rueidis

Use NewPool to create a rueidis-based pool implementation. It requires a rueidiscompat.Cmdable delegate.

```go
func NewPool(delegate rueidiscompat.Cmdable) redsyncredis.Pool
```

--------------------------------

### Mutex Option Interface

Source: https://pkg.go.dev/github.com/go-redsync/redsync/v4

An Option configures a mutex. Implement this interface to create custom mutex configurations.

```go
type Option interface {
	Apply(*Mutex)
}
```

--------------------------------

### func NewPool

Source: https://pkg.go.dev/github.com/go-redsync/redsync/v4/redis/goredis/v8

Initializes a new pool implementation for redsync using a provided redis.UniversalClient.

```APIDOC
## func NewPool

### Description
NewPool returns a Goredis-based pool implementation that allows redsync to interact with Redis using the go-redis client.

### Signature
`func NewPool(delegate redis.UniversalClient) redsyncredis.Pool`

### Parameters
- **delegate** (redis.UniversalClient) - Required - The underlying Redis client instance (supports single, cluster, or sentinel modes).

### Returns
- **redsyncredis.Pool** - A pool implementation compatible with the redsync library.
```

--------------------------------

### NewPool Function - goredis

Source: https://pkg.go.dev/github.com/go-redsync/redsync/v4/redis/goredis

Use NewPool to create a Goredis-based pool. It requires a delegate *redis.Client.

```go
func NewPool(delegate *redis.Client) redsyncredis.Pool
```

--------------------------------

### Apply OptionFunc

Source: https://pkg.go.dev/github.com/go-redsync/redsync/v4

Apply calls f(mutex). This method is part of the OptionFunc type, allowing functions to be used as mutex options.

```go
func (f OptionFunc) Apply(mutex *Mutex)
```

--------------------------------

### Set Fail-Fast Lock Acquisition Option

Source: https://pkg.go.dev/github.com/go-redsync/redsync/v4

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.

```go
func WithFailFast(b bool) Option
```

--------------------------------

### NewPool Function

Source: https://pkg.go.dev/github.com/go-redsync/redsync/v4/redis/rueidis

This function returns a rueidis-based pool implementation for redsync.

```APIDOC
## func NewPool

### Description
NewPool returns a rueidis-based pool implementation.

### Method
N/A (Function Signature)

### Endpoint
N/A (Function)

### Parameters
#### Path Parameters
N/A

#### Query Parameters
N/A

#### Request Body
N/A

### Request Example
N/A

### Response
#### Success Response (200)
- **redsyncredis.Pool** (type) - A rueidis-based pool implementation.

#### Response Example
N/A
```

--------------------------------

### NewPool Function

Source: https://pkg.go.dev/github.com/go-redsync/redsync/v4/redis/goredis/v7

Provides details about the NewPool function, which returns a Goredis-based pool implementation.

```APIDOC
## func NewPool

### Description
NewPool returns a Goredis-based pool implementation.

### Signature
```go
func NewPool(delegate redis.UniversalClient) redsyncredis.Pool
```
```

--------------------------------

### func NewPool

Source: https://pkg.go.dev/github.com/go-redsync/redsync/v4/redis/goredis/v9

Initializes a new Goredis-based pool implementation for use with redsync.

```APIDOC
## func NewPool

### Description
NewPool returns a Goredis-based pool implementation that satisfies the redsyncredis.Pool interface using a provided redis.UniversalClient.

### Parameters
- **delegate** (redis.UniversalClient) - Required - The Redis client instance to be used by the pool.

### Returns
- **redsyncredis.Pool** - A pool implementation compatible with redsync.
```

--------------------------------

### Mutex Configuration Options

Source: https://pkg.go.dev/github.com/go-redsync/redsync/v4

Functions used to configure the behavior of a Mutex, such as expiry, retry logic, and drift factors.

```APIDOC
## Mutex Options

### Description
Functions that return an Option to configure a Mutex.

### Available Options
- **WithDriftFactor(factor float64)**: Sets the clock drift factor (default 0.01).
- **WithExpiry(expiry time.Duration)**: Sets the expiry of a mutex (default 8s).
- **WithFailFast(b bool)**: Quickly acquire/release lock based on quorum.
- **WithRetryDelay(delay time.Duration)**: Sets time to wait between retries.
- **WithTries(tries int)**: Sets number of acquisition attempts (default 32).
- **WithValue(v string)**: Assigns a random value to the mutex.
```

--------------------------------

### Redsync Struct

Source: https://pkg.go.dev/github.com/go-redsync/redsync/v4

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

```go
type Redsync struct {
	// contains filtered or unexported fields
}
```

--------------------------------

### func NewScript

Source: https://pkg.go.dev/github.com/go-redsync/redsync/v4/redis

Creates a new Script object for executing Lua scripts in Redis.

```APIDOC
## func NewScript

### Description
Returns a new script object. If keyCount is greater than or equal to zero, the count is automatically inserted in the EVAL command argument list.

### Parameters
- **keyCount** (int) - Required - The number of keys used by the script.
- **src** (string) - Required - The Lua script source code.
- **hash** (string) - Required - The SHA1 hash of the script.

### Response
- **Script** (object) - A pointer to the initialized Script structure.
```

--------------------------------

### Lock Mutex

Source: https://pkg.go.dev/github.com/go-redsync/redsync/v4

Methods to acquire a lock, supporting retries on failure.

```go
func (m *Mutex) Lock() error
```

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

--------------------------------

### Define Lua Script Structure

Source: https://pkg.go.dev/github.com/go-redsync/redsync/v4/redis

Defines the Script struct used to encapsulate Lua script metadata.

```go
type Script struct {
	KeyCount int
	Src      string
	Hash     string
}
```

--------------------------------

### Create New Mutex

Source: https://pkg.go.dev/github.com/go-redsync/redsync/v4

NewMutex returns a new distributed mutex with the given name and options.

```go
func (r *Redsync) NewMutex(name string, options ...Option) *Mutex
```

--------------------------------

### func NewPool

Source: https://pkg.go.dev/github.com/go-redsync/redsync/v4/redis/goredis

Creates a new pool implementation for redsync using a provided redis.Client.

```APIDOC
## func NewPool

### Description
NewPool returns a Goredis-based pool implementation, allowing redsync to utilize a redis.Client for distributed locking operations.

### Parameters
- **delegate** (*redis.Client) - Required - The underlying Redis client instance to be used by the pool.

### Returns
- **redsyncredis.Pool** - A pool implementation compatible with the redsync library.
```

--------------------------------

### func NewPool

Source: https://pkg.go.dev/github.com/go-redsync/redsync/v4/redis/redigo

Creates a new Redigo-based pool implementation for use with redsync.

```APIDOC
## func NewPool

### Description
NewPool returns a Redigo-based pool implementation.

### Parameters
- **delegate** (Pool) - Required - The pool interface to be wrapped.

### Returns
- **redsyncredis.Pool** - A Redigo-based pool implementation.
```

--------------------------------

### Set Number of Tries Option

Source: https://pkg.go.dev/github.com/go-redsync/redsync/v4

WithTries can be used to set the number of times lock acquire is attempted. The default value is 32.

```go
func WithTries(tries int) Option
```

--------------------------------

### interface Conn

Source: https://pkg.go.dev/github.com/go-redsync/redsync/v4/redis

Defines the methods for interacting with a single Redis connection.

```APIDOC
## interface Conn

### Description
Conn represents a single Redis connection interface.

### Methods
- **Get(name string)**: Retrieves a value by name.
- **Set(name string, value string)**: Sets a value by name.
- **SetNX(name string, value string, expiry time.Duration)**: Sets a value if it does not exist with an expiry.
- **Eval(script *Script, keysAndArgs ...interface{})**: Executes a Lua script.
- **ScriptLoad(script *Script)**: Loads a script into the Redis server.
- **PTTL(name string)**: Gets the time-to-live for a key in milliseconds.
- **Close()**: Closes the connection.
```

--------------------------------

### Override Default Delay Behavior Option

Source: https://pkg.go.dev/github.com/go-redsync/redsync/v4

WithRetryDelayFunc can be used to override default delay behavior.

```go
func WithRetryDelayFunc(delayFunc DelayFunc) Option
```

--------------------------------

### TryLock Mutex

Source: https://pkg.go.dev/github.com/go-redsync/redsync/v4

Attempts to acquire a lock once without retrying.

```go
func (m *Mutex) TryLock() error
```

```go
func (m *Mutex) TryLockContext(ctx context.Context) error
```

--------------------------------

### Set Custom Value Generator Option

Source: https://pkg.go.dev/github.com/go-redsync/redsync/v4

WithGenValueFunc can be used to set the custom value generator.

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

--------------------------------

### type Pool

Source: https://pkg.go.dev/github.com/go-redsync/redsync/v4/redis/redigo

Interface definition for the connection pool used by redsync.

```APIDOC
## type Pool

### Description
An interface representing a connection pool for Redis.

### Methods
- **Get()** (redis.Conn) - Retrieves a connection from the pool.
- **GetContext(ctx context.Context)** (redis.Conn, error) - Retrieves a connection from the pool using the provided context.
```

--------------------------------

### func NewPool

Source: https://pkg.go.dev/github.com/go-redsync/redsync/v4/redis/valkeygo

Creates a new redsyncredis.Pool implementation using a valkeycompat.Cmdable delegate.

```APIDOC
## func NewPool

### Description
NewPool returns a rueidis-based pool implementation for use with redsync.

### Signature
`func NewPool(delegate valkeycompat.Cmdable) redsyncredis.Pool`

### Parameters
- **delegate** (valkeycompat.Cmdable) - Required - The underlying commandable interface to be used by the pool.

### Returns
- **redsyncredis.Pool** - A pool implementation compatible with redsync.
```

--------------------------------

### Error Method for RedisError

Source: https://pkg.go.dev/github.com/go-redsync/redsync/v4

Error returns the string representation of the RedisError.

```go
func (e RedisError) Error() string
```

--------------------------------

### Define Redis Connection Interface

Source: https://pkg.go.dev/github.com/go-redsync/redsync/v4/redis

Defines the Conn interface for interacting with a single Redis connection.

```go
type Conn interface {
	Get(name string) (string, error)
	Set(name string, value string) (bool, error)
	SetNX(name string, value string, expiry time.Duration) (bool, error)
	Eval(script *Script, keysAndArgs ...interface{}) (interface{}, error)
	ScriptLoad(script *Script) error
	PTTL(name string) (time.Duration, error)
	Close() error
}
```

--------------------------------

### interface Pool

Source: https://pkg.go.dev/github.com/go-redsync/redsync/v4/redis

Defines the methods for managing a pool of Redis connections.

```APIDOC
## interface Pool

### Description
Pool maintains a pool of Redis connections.

### Methods
- **Get(ctx context.Context)**: Retrieves a connection from the pool.
```

--------------------------------

### Mutex Operations

Source: https://pkg.go.dev/github.com/go-redsync/redsync/v4

Methods for inspecting the state and validity of an acquired distributed mutex.

```APIDOC
## func (*Mutex) Until

### Description
Returns the time of validity of the acquired lock. The value will be zero until a lock is acquired.

## func (*Mutex) Value

### Description
Returns the current random value associated with the mutex. The value will be empty until a lock is acquired or WithValue is used.
```

--------------------------------

### Unlock Mutex

Source: https://pkg.go.dev/github.com/go-redsync/redsync/v4

Releases the lock, with and without context support.

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

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

--------------------------------

### Assign Value Option

Source: https://pkg.go.dev/github.com/go-redsync/redsync/v4

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.

```go
func WithValue(v string) Option
```

--------------------------------

### Extend Mutex Lock

Source: https://pkg.go.dev/github.com/go-redsync/redsync/v4

Methods to reset the expiry of an existing lock, with and without context support.

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

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

--------------------------------

### Define Redsync Error Variables

Source: https://pkg.go.dev/github.com/go-redsync/redsync/v4

Standard error variables used to indicate specific failure states during lock operations.

```go
var ErrExtendFailed = errors.New("redsync: failed to extend lock")
```

```go
var ErrFailed = errors.New("redsync: failed to acquire lock")
```

```go
var ErrLockAlreadyExpired = errors.New("redsync: failed to unlock, lock was already expired")
```

--------------------------------

### Unwrap Method for RedisError

Source: https://pkg.go.dev/github.com/go-redsync/redsync/v4

Unwrap returns the underlying error for a RedisError, useful for error inspection.

```go
func (e RedisError) Unwrap() error
```

--------------------------------

### Define Redis Pool Interface

Source: https://pkg.go.dev/github.com/go-redsync/redsync/v4/redis

Defines the Pool interface for managing a collection of Redis connections.

```go
type Pool interface {
	Get(ctx context.Context) (Conn, error)
}
```

--------------------------------

### Check Mutex Validity with Context (Deprecated)

Source: https://pkg.go.dev/github.com/go-redsync/redsync/v4

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. Use Until instead.

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

--------------------------------

### Set Retry Delay Option

Source: https://pkg.go.dev/github.com/go-redsync/redsync/v4

WithRetryDelay can be used to set the amount of time to wait between retries. The default value is rand(50ms, 250ms).

```go
func WithRetryDelay(delay time.Duration) Option
```

--------------------------------

### Shuffle Redis Pools Option

Source: https://pkg.go.dev/github.com/go-redsync/redsync/v4

WithShufflePools can be used to shuffle Redis pools to reduce centralized access in concurrent scenarios.

```go
func WithShufflePools(b bool) Option
```

--------------------------------

### Mutex OptionFunc Type

Source: https://pkg.go.dev/github.com/go-redsync/redsync/v4

OptionFunc is a function that configures a mutex.

```go
type OptionFunc func(*Mutex)
```

--------------------------------

### Check Mutex Validity (Deprecated)

Source: https://pkg.go.dev/github.com/go-redsync/redsync/v4

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. Use Until instead.

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

--------------------------------

### Set Mutex Expiry Option

Source: https://pkg.go.dev/github.com/go-redsync/redsync/v4

WithExpiry can be used to set the expiry of a mutex to the given value. The default is 8s.

```go
func WithExpiry(expiry time.Duration) Option
```

--------------------------------

### Mutex Operations

Source: https://pkg.go.dev/github.com/go-redsync/redsync/v4

Methods for managing distributed locks using the Mutex type.

```APIDOC
## Mutex Operations

### Description
Methods to acquire, release, and extend distributed locks.

### Methods
- **Lock()**: Acquires the lock.
- **Unlock()**: Releases the lock.
- **Extend()**: Resets the mutex expiry.
- **TryLock()**: Attempts to lock once without retrying.

### Parameters
- **ctx** (context.Context) - Optional - Context for cancellation and timeout support in Context-suffixed methods.

### Response
- **bool** - Status of the operation (for Extend and Unlock).
- **error** - Error object if the operation fails.
```

--------------------------------

### Define Mutex Type

Source: https://pkg.go.dev/github.com/go-redsync/redsync/v4

The primary structure for a distributed mutual exclusion lock.

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

--------------------------------

### RedisError Struct

Source: https://pkg.go.dev/github.com/go-redsync/redsync/v4

A RedisError is an error communicating with one of the Redis nodes. It includes the node index and the underlying error.

```go
type RedisError struct {
	Node int
	Err  error
}
```

--------------------------------

### Set Mutex Drift Factor Option

Source: https://pkg.go.dev/github.com/go-redsync/redsync/v4

WithDriftFactor can be used to set the clock drift factor. The default value is 0.01.

```go
func WithDriftFactor(factor float64) Option
```

--------------------------------

### Set Timeout Factor Option

Source: https://pkg.go.dev/github.com/go-redsync/redsync/v4

WithTimeoutFactor can be used to set the timeout factor. The default value is 0.05.

```go
func WithTimeoutFactor(factor float64) Option
```

--------------------------------

### Define ErrTaken Error

Source: https://pkg.go.dev/github.com/go-redsync/redsync/v4

Error type indicating that a lock is held on a quorum of nodes.

```go
type ErrTaken struct {
	Nodes []int
}
```

```go
func (err ErrTaken) Error() string
```

--------------------------------

### Define ErrNodeTaken Error

Source: https://pkg.go.dev/github.com/go-redsync/redsync/v4

Error type indicating that a lock is already held on a specific node.

```go
type ErrNodeTaken struct {
	Node int
}
```

```go
func (err ErrNodeTaken) Error() string
```

--------------------------------

### Define DelayFunc Type

Source: https://pkg.go.dev/github.com/go-redsync/redsync/v4

A function type used to calculate the wait duration between retry attempts.

```go
type DelayFunc func(tries int) time.Duration
```
Tokens:
Raw